package com.zcloud.safetyDutyList.api.tasklist;

import com.alibaba.cola.dto.MultiResponse;
import com.alibaba.cola.dto.PageResponse;
import com.alibaba.cola.dto.Response;
import com.alibaba.cola.dto.SingleResponse;
import com.zcloud.safetyDutyList.dto.clientobject.tasklist.*;
import com.zcloud.safetyDutyList.dto.tasklist.*;

import java.util.List;

/**
 * 安全责任清单服务接口
 * <p>
 * 定义安全责任清单相关的所有业务操作，包括清单管理、任务详情管理、
 * 执行反馈管理、反馈异常查询、统计分析等功能。
 * <p>
 * 实现类为TaskListServiceImpl，通过各类Exe执行器完成具体业务逻辑。
 */
public interface TaskListServiceI {

    /**
     * 分页查询任务模板列表（以task_detail为主表）
     *
     * @param qry 分页查询参数（支持taskListId、执行内容、反馈周期等筛选）
     * @return 任务模板分页结果
     */
    PageResponse<TaskDetailCO> listTaskDetailPage(TaskDetailPageQry qry);

    /**
     * 分页查询任务清单列表（以task_list为主表）
     *
     * @param qry 分页查询参数（支持清单名称、等级、状态等筛选）
     * @return 清单分页结果
     */
    PageResponse<TaskListCO> listPage(TaskListPageQry qry);

    /**
     * 新增任务清单（同时创建关联的任务详情）
     *
     * @param cmd 新增命令（包含清单信息和任务详情列表）
     * @return 新增后的清单信息
     */
    SingleResponse<TaskListCO> add(TaskListAddCmd cmd);

    /**
     * 修改任务清单（先删除旧任务详情再重建）
     *
     * @param cmd 修改命令
     * @return 修改后的清单信息
     */
    SingleResponse<TaskListCO> edit(TaskListUpdateCmd cmd);

    /**
     * 删除任务清单
     *
     * @param id 主键ID
     * @return 操作结果
     */
    Response remove(Long id);

    /**
     * 根据主键ID获取任务清单详情（含关联的任务详情列表）
     *
     * @param id 主键ID
     * @return 清单详情
     */
    SingleResponse<TaskListCO> getInfoById(Long id);

    /**
     * 开启/关闭任务清单开关
     *
     * @param cmd 开关切换命令
     * @return 操作结果
     */
    SingleResponse<TaskListCO> switchFlag(TaskListSwitchCmd cmd);

    /**
     * 关闭任务清单（同时关闭关联的所有任务详情）
     *
     * @return 操作结果
     */
    SingleResponse close(String taskIssueId);

    /**
     * 任务清单下发（指定执行企业和执行人，设置周期起止时间）
     *
     * @param cmd 下发命令
     * @return 操作结果
     */
    SingleResponse issue(TaskListIssueCmd cmd);

    /**
     * 分页查询任务详情列表（含反馈统计和异常记录）
     *
     * @param qry 分页查询参数
     * @return 任务详情分页结果
     */
    PageResponse<TaskDetailFullCO> listPage(TaskDetailPageQry qry);

    /**
     * 新增任务详情（校验清单总分不超过100）
     *
     * @param cmd 任务保存命令
     * @return 新增后的任务详情
     */
    SingleResponse<TaskDetailCO> addTaskDetail(TaskDetailSaveCmd cmd);

    /**
     * 批量保存任务详情（id为空新增，id非空更新，数据库有但传参无则删除）
     *
     * @param cmds 任务保存命令列表
     * @return 保存后的任务详情列表
     */
    MultiResponse<TaskDetailCO> addTaskDetailBatch(List<TaskDetailSaveBatchCmd> cmds);

    /**
     * 编辑任务详情（校验清单总分不超过100）
     *
     * @param cmd 任务编辑命令
     * @return 编辑后的任务详情
     */
    SingleResponse<TaskDetailCO> editTaskDetail(TaskDetailEditCmd cmd);

    /**
     * 根据任务详情ID获取任务详情（含所属清单信息）
     *
     * @param detailId 任务详情业务ID
     * @return 任务详情信息
     */
    SingleResponse<TaskDetailInfoCO> getByTaskDetailId(String detailId);

    /**
     * 关闭任务详情
     *
     * @param cmd 关闭命令
     * @return 操作结果
     */
    Response closeTaskExecution(TaskExecutionCloseCmd cmd);

    /**
     * 更新任务评分（评分不能超过任务分值）
     *
     * @param cmd 评分命令
     * @return 操作结果
     */
    Response updateTaskDetailScore(TaskDetailUpdateScoreCmd cmd);

    /**
     * 提交执行反馈
     *
     * @param cmd 反馈提交命令
     * @return 反馈信息
     */
    SingleResponse<FeedbackCO> addFeedback(FeedbackAddCmd cmd);

    /**
     * 删除反馈记录
     *
     * @param id 主键ID
     * @return 操作结果
     */
    SingleResponse deleteFeedback(Long id);

    /**
     * 编辑反馈记录
     *
     * @param cmd 编辑命令（含反馈ID和反馈内容）
     * @return 编辑后的反馈信息
     */
    SingleResponse<FeedbackCO> editFeedback(FeedbackEditCmd cmd);

    /**
     * 查询反馈周期分组列表（按周期标识分组统计反馈数量）
     *
     * @param qry 查询参数
     * @return 周期分组列表
     */
    MultiResponse<FeedbackPeriodGroupCO> feedbackPeriodGroupList(FeedbackPeriodGroupQry qry);

    /**
     * 分页查询反馈列表
     *
     * @param qry 分页查询参数（含taskDetailId、taskListId、feedbackPeriodFlag等）
     * @return 反馈分页结果
     */
    PageResponse<FeedbackCO> feedbackPage(FeedbackListQry qry);

    /**
     * 根据反馈ID获取反馈详情（含关联任务信息）
     *
     * @param feedbackId 反馈业务ID
     * @return 反馈详情
     */
    SingleResponse<FeedbackCO> getByFeedbackId(String feedbackId);

    /**
     * 分页查询反馈异常记录
     *
     * @param qry 分页查询参数
     * @return 异常记录分页结果
     */
    PageResponse<FeedbackExceptionCO> exceptionPage(FeedbackExceptionPageQry qry);

    /**
     * 安全责任清单统计（按企业分组统计清单数量和状态分布）
     *
     * @param qry 查询参数
     * @return 统计结果列表
     */
    MultiResponse<TaskListStatisticsCO> statistics(TaskListStatisticsQry qry);

    /**
     * 企业统计（按企业分组统计完成和关闭的清单数量）
     *
     * @param qry 分页查询参数
     * @return 企业统计分页结果
     */
    PageResponse<CorpStatisticsCO> corpStatistics(CorpStatisticsQry qry);

    /**
     * 考核清单查询（按企业分组统计清单数量）
     *
     * @param qry 分页查询参数
     * @return 考核清单分页结果
     */
    PageResponse<EvaluationListCO> evaluationList(EvaluationListQry qry);

    /**
     * 下发统计（按执行企业分组统计已下发的清单数量）
     *
     * @param qry 分页查询参数
     * @return 下发统计分页结果
     */
    PageResponse<IssueStatisticsCO> issueStatistics(IssueStatisticsQry qry);

    /**
     * 分页查询任务清单列表（以task_list_issue为主表联表查询）
     *
     * @param qry 分页查询参数（支持执行公司ID、清单名称、等级、反馈状态、开关标识等筛选）
     * @return 清单下发记录分页结果
     */
    PageResponse<TaskListIssueCO> listIssuePage(TaskListIssuePageQry qry);

    /**
     * 根据下发记录ID获取下发记录详情
     *
     * @param taskIssueId 下发记录业务ID
     * @return 下发记录详情
     */
    SingleResponse<TaskListIssueCO> getIssueByTaskIssueId(String taskIssueId);

    /**
     * 统计执行者为指定用户的下发记录数量
     *
     * @param executeUserId 执行用户ID
     * @return 数量
     */
    SingleResponse<Long> countIssueByExecuteUserId(Long executeUserId);

    /**
     * 分页查询任务执行记录（以task_execution为主表联表查询）
     *
     * @param qry 分页查询参数（支持taskIssueId、执行内容、反馈周期、反馈状态、任务状态等筛选）
     * @return 任务执行记录分页结果
     */
    PageResponse<TaskExecutionCO> listExecutionPage(TaskExecutionPageQry qry);

    /**
     * 根据任务执行ID获取任务执行记录详情
     *
     * @param taskExecutionId 任务执行业务ID
     * @return 任务执行记录详情
     */
    SingleResponse<TaskExecutionCO> getExecutionByTaskExecutionId(String taskExecutionId);

    /**
     * 定时任务1：更新过期清单和任务状态
     * <p>
     * 查询所有状态为进行中(status=1)且周期结束时间小于当前时间的清单，
     * 将其状态更新为已完成(status=2)，同时将该清单下所有进行中的任务也标记为已完成。
     * 由TaskStatusUpdateJob定时任务调用。
     */
    void updateExpiredTaskListStatus();

    /**
     * 定时任务2：反馈异常检测
     * <p>
     * 获取所有进行中的任务，根据反馈周期类型判断上一阶段是否有反馈记录，
     * 若无反馈则创建反馈异常记录。由FeedbackExceptionCheckJob定时任务调用。
     */
    void checkFeedbackException();

    /**
     * 定时任务3：发送待办消息
     * <p>
     * 获取所有进行中的任务，根据反馈周期类型判断上一阶段是否有反馈记录，
     * 若无反馈则创建反馈异常记录。由FeedbackExceptionCheckJob定时任务调用。
     */
    void sendTodoMessage();
}
