package cn.iocoder.yudao.module.mes.service.pro.qrexport;

import cn.iocoder.yudao.module.mes.dal.dataobject.pro.qrexport.MesProQrExportTaskDO;
import cn.iocoder.yudao.module.mes.enums.pro.MesProQrExportBizTypeEnum;
import jakarta.servlet.http.HttpServletResponse;

import java.io.IOException;

/**
 * MES 二维码导出任务 Service
 * <p>
 * 仅承担「大批量」这一条路径：数量不超过分界线的导出仍走同步流式下载，不进任务、不排队、不受 CPU 闸门约束，
 * 以保证导几百张永远秒出。
 */
public interface MesProQrExportTaskService {

    /**
     * 统计待导出的标签张数（供调用方判断走同步还是后台）
     *
     * @param bizType 业务类型
     * @param uuid    生成组 UUID
     * @param batchId 生产批次编号
     * @return 标签张数
     */
    long countLabels(MesProQrExportBizTypeEnum bizType, String uuid, Long batchId);

    /**
     * 提交后台导出任务
     * <p>
     * 依次经过并发闸门与 CPU 闸门，任一不通过即拒绝提交并给出原因。
     *
     * @param bizType 业务类型
     * @param uuid    生成组 UUID
     * @param batchId 生产批次编号
     * @return 已创建的任务
     */
    MesProQrExportTaskDO submit(MesProQrExportBizTypeEnum bizType, String uuid, Long batchId);

    /**
     * 获得导出任务
     *
     * @param id 任务编号
     * @return 任务；不存在时抛业务异常
     */
    MesProQrExportTaskDO getTask(Long id);

    /**
     * 取消导出任务
     * <p>
     * 任务正在生成时会尽快中断并删除临时文件；已处于终态的任务不允许取消。
     *
     * @param id 任务编号
     */
    void cancel(Long id);

    /**
     * 下载导出产物
     * <p>
     * 下载成功后立即删除临时 ZIP（避免上 GB 的临时文件堆积）；下载中断则保留至清理任务删除，
     * 以便调用方在短时间内重试而不必重新生成。
     *
     * @param id       任务编号
     * @param response 响应
     */
    void download(Long id, HttpServletResponse response) throws IOException;

    /**
     * 清理超期的临时 ZIP 文件
     *
     * @return 清理的文件数
     */
    int cleanupExpiredFiles();

    /**
     * 回收因进程重启或超时而残留在非终态的任务
     *
     * @return 回收的任务数
     */
    int recycleStaleTasks();

}