package jnpf.tmsService;

import jnpf.tmsEntity.record.TmsQuizAnswerPaperVO;
import jnpf.tmsEntity.record.TmsRecordForm;
import jnpf.tmsEntity.record.TmsRecordIncompleteVO;
import jnpf.tmsEntity.record.TmsRecordProgressVO;
import jnpf.tmsEntity.record.TmsRecordQuery;
import jnpf.tmsEntity.record.TmsRecordScanSignForm;
import jnpf.tmsEntity.record.TmsRecordSignQrVO;
import jnpf.tmsEntity.person.TmsPersonTaskSignResult;

import java.util.List;

/**
 * 培训记录服务：签到、归档状态机、归档写个人培训目录。
 *
 * @see jnpf.tmsService.impl.TmsRecordServiceImpl
 */
public interface TmsRecordService {

    List<TmsRecordForm> getList(TmsRecordQuery query);

    TmsRecordForm getInfo(String id);

    /** 实时参与进度（签到率/合格率/未完成率） */
    TmsRecordProgressVO getProgress(String recordId);

    /** 未完成人员清单（按部门排序） */
    List<TmsRecordIncompleteVO> listIncomplete(String recordId);

    /** 按任务回写记录签到率/合格率（签到、交卷后调用） */
    void refreshRatesByTaskId(String taskId);

    TmsRecordSignQrVO getSignQr(String id);

    /** 扫码签到落库（校验二维码后写 person_task） */
    TmsPersonTaskSignResult scanSign(TmsRecordScanSignForm form);

    void update(String id, TmsRecordForm form);

    /**
     * 关闭时间已到：null/空 → pending（FDS 待归档；供 XXL-JOB / 数据接口 / 临时按钮）
     *
     * @return 本次转入待归档的条数
     */
    int markReadyByCloseTime();

    /**
     * 待归档 → 可归档：pending → ready（可选中间态）
     */
    int promoteToReady(List<String> ids);

    /**
     * 可归档恢复为待归档：ready → pending（临时联调，上线 Job 后可保留作运维）
     */
    int restoreToPending(List<String> ids);

    /**
     * 归档：写 {@code tms_person_train}、任务 done、未完成人再培训草稿。
     * 仅 pending / ready 可归档。
     */
    int archive(List<String> ids);

    /**
     * 无效任务：无人完成时可打 invalid，并自动生成再维护草稿任务。
     *
     * @return 本次作废条数
     */
    int markInvalid(List<String> ids);

    /**
     * 提问人数：ceil(签到人数 * task.quiz_ratio / 100)
     */
    int calcQuizCount(String recordId);

    /** 某学员在该培训记录下的提问答卷（题目/学员答案/参考答案/对错） */
    TmsQuizAnswerPaperVO getQuizAnswers(String recordId, String userId);

    void delete(List<String> ids);
}