namespace Deal.Modules.Cards.Application;

/// <summary>
/// Единый механизм перехода карточки между контейнерами.
/// </summary>
/// <remarks>
/// Заменяет маршрутизацию перехода по эндпоинтам: одна точка знает и контейнеры-стадии пространства
/// «Выбранные», и контейнеры дашборда (доски/служебные зоны). Валидацию «откуда → куда можно» выполняют
/// политики контейнеров и «ворота» между пространствами (например, дашборд → «Выбранные» — только через
/// действие «взять в работу»; «Выбранные» → дашборд — запрещено). Побочные эффекты (запись истории для
/// стадий, сброс напоминания, журнал/обучение ML для дашборда) выполняет реализация перехода.
/// </remarks>
public interface ICardMover
{
    /// <summary>
    /// Перемещает карточку в контейнер назначения с побочными эффектами перехода.
    /// </summary>
    /// <param name="cardId">Id карточки.</param>
    /// <param name="toContainerId">Id контейнера назначения (стадия «Выбранных» либо дашборд-контейнер).</param>
    /// <param name="ctx">Контекст перехода (инициатор, причина, обучение).</param>
    /// <param name="ct">Токен отмены.</param>
    /// <returns>Результат: Error (400-текст отказа) | Exists=false (карточки нет, 404) | успех (Exists=true).</returns>
    public Task<CardMoveResultDto> MoveAsync(
        string cardId, string toContainerId, TransitionContext ctx, CancellationToken ct);
}