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

namespace QYZH.InteractiveMagazine.IService;

/// <summary>
/// 用户作答任务服务接口
/// </summary>
public interface IUserAnswerTaskService : IBaseService<JournalPageTaskUserAnswer>
{
    /// <summary>
    /// 获取用户期刊学习进度列表（按期刊分组）
    /// </summary>
    /// <param name="userId">用户Id</param>
    /// <returns>按期刊分组的学习进度数据</returns>
    Task<List<JournalProgressOutput>> GetJournalProgressAsync(long userId);

    /// <summary>
    /// 获取目录列表（按一级目录分组，二级目录含完成状态）
    /// </summary>
    /// <param name="journalId">期刊Id</param>
    /// <param name="userId">用户Id</param>
    /// <returns>按一级目录分组的目录列表</returns>
    Task<List<CatalogListOutput>> GetCatalogListAsync(long journalId, long userId);

    /// <summary>
    /// 获取一级目录概览（含二级目录详情、页码范围、任务完成状态）
    /// </summary>
    /// <param name="catalogId">一级目录Id（JournalCatalogId）</param>
    /// <param name="userId">用户Id</param>
    /// <returns>一级目录概览数据</returns>
    Task<CatalogOverviewOutput> GetCatalogOverviewAsync(long catalogId, long userId);

    /// <summary>
    /// 获取用户答题任务列表
    /// </summary>
    /// <param name="catalogId">二级目录Id（CatalogId）</param>
    /// <param name="userId">用户Id</param>
    /// <returns>答题任务列表</returns>
    Task<UserAnswerTaskListOutput> GetUserAnswerTaskListAsync(long catalogId, long userId);

    /// <summary>
    /// 获取跨页题目详情
    /// </summary>
    /// <param name="groupId">任务分组ID（JournalPageTaskGroupId）</param>
    /// <param name="userId">用户Id</param>
    /// <returns>跨页题目详情</returns>
    Task<CrossPageTaskOutput> GetCrossPageTaskAsync(long groupId, long userId);

    /// <summary>
    /// 领取任务积分
    /// </summary>
    /// <param name="groupId">任务分组Id（JournalPageTask.GroupId）</param>
    /// <param name="userId">用户Id</param>
    /// <returns>领取结果</returns>
    Task<ClaimTaskPointsOutput> ClaimTaskPointsAsync(long groupId, long userId);

    /// <summary>
    /// 批量领取任务积分（一键领取）
    /// </summary>
    /// <param name="input">批量领取参数</param>
    /// <param name="userId">用户Id</param>
    /// <returns>批量领取结果</returns>
    Task<BatchClaimPointsOutput> BatchClaimPointsAsync(BatchClaimPointsInput input, long userId);
}