using QYZH.InteractiveMagazine.Models.Dto.Compensation;
using QYZH.InteractiveMagazine.Models.Entity;

namespace QYZH.InteractiveMagazine.IService;

/// <summary>
/// 补偿任务服务接口（仅负责记录和状态管理，处理逻辑由外部项目实现）
/// </summary>
public interface ICompensationTaskService : IBaseService<CompensationTask>
{
    /// <summary>
    /// 创建补偿任务（公共调用入口）
    /// 当业务操作部分成功但某个后续步骤失败时调用，记录失败操作以便后续重试
    /// </summary>
    /// <param name="input">补偿任务创建参数</param>
    /// <returns>补偿任务Id</returns>
    Task<long> CreateTaskAsync(CreateCompensationTaskInput input);

    /// <summary>
    /// 获取待处理的补偿任务列表（Pending + 已过 ScheduledAt 的任务）
    /// </summary>
    /// <param name="limit">每次获取数量上限</param>
    /// <returns>待处理任务列表</returns>
    Task<List<CompensationTaskOutput>> GetPendingTasksAsync(int limit = 50);

    /// <summary>
    /// 按条件查询补偿任务（供外部项目按类型/状态/来源拉取）
    /// </summary>
    /// <param name="input">查询条件</param>
    /// <returns>任务列表</returns>
    Task<List<CompensationTaskOutput>> GetTasksAsync(GetCompensationTasksInput input);

    /// <summary>
    /// 更新补偿任务状态（供外部处理项目回调更新处理结果）
    /// </summary>
    /// <param name="taskId">任务Id</param>
    /// <param name="input">状态更新参数</param>
    Task UpdateTaskStatusAsync(long taskId, UpdateCompensationStatusInput input);

    /// <summary>
    /// 取消补偿任务
    /// </summary>
    /// <param name="taskId">任务Id</param>
    /// <param name="reason">取消原因</param>
    Task CancelTaskAsync(long taskId, string reason);
}