package com.ruoyi.common.core.service;

/**
 * 任务运维触发能力 —— <b>端口反转</b>契约。
 *
 * <h3>为什么需要它（解 ruoyi-task ↔ ruoyi-quartz 循环依赖）</h3>
 * {@code /smartor/serviceSubtask} 下有 6 个「手工触发同步/截止/异常推送」的运维端点
 * （{@code syncMedInhospForShiyi} / {@code syncMedInhospForShiyiYesterday} /
 * {@code syncMedInhospForShiyiDaysBefore} / {@code syncMedOperForShiyi} /
 * {@code dealSubtaskDeadline} / {@code sendExceptInfo}），
 * 它们原先由 {@code ruoyi-admin} 的 {@code ServiceSubtaskController} 直接调用
 * {@code ruoyi-quartz} 的 {@code RyTask} / {@code ICollectHISService}。
 * <p>
 * 任务模块化后这 6 个端点的<b>归属</b>搬进 {@code ruoyi-task}，但它们的<b>实现不能搬</b>：
 * <ul>
 *   <li>{@code RyTask}（2214 行）注入 <b>约 20 个 smartor service</b> + {@code com.smartor.mapper.*}
 *       —— 搬走会让 {@code ruoyi-task -> smartor}，而 smartor 有 35 个文件引用任务域实体，
 *       形成硬循环；</li>
 *   <li>{@code collectHIS*} 本质是 <b>HIS 数据采集</b>（{@code CollectHISMapper} + {@code MzGather*}
 *       常量/枚举），属 quartz 域，不是任务域。</li>
 * </ul>
 * 因此采用<b>端口反转</b>：接口定义在 {@code ruoyi-common}（唯一能同时满足
 * 「ruoyi-task 不依赖 ruoyi-quartz」+「ruoyi-quartz 依赖 ruoyi-task」的位置），
 * 由 {@code ruoyi-quartz} 提供实现。这样端点在任务模块内、实现在 quartz 内，
 * 编译期<b>无环</b>。
 *
 * <h3>⚠️ 实现必须保持"纯搬运"</h3>
 * 实现方只做转发，<b>不得</b>加入去重、状态机、默认值补齐等新逻辑 ——
 * 那些语义原本就在 {@code RyTask} / {@code ICollectHISService} 里。
 *
 * <h3>调用方务必降级</h3>
 * 取不到实现（quartz 未打进应用 / 容器异常）时，调用方应按"未触发"处理并打 WARN，
 * 不要让运维端点抛 500。
 *
 * @see VisitTaskCreateApi 同一手法（接口在 ruoyi-common、实现由归属方提供）的先例
 */
public interface TaskOpsTriggerApi {

    /**
     * 市一：同步住院信息（原 {@code ICollectHISService#syncMedInhosp}）。
     *
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @return 同步条数
     */
    Integer syncMedInhosp(String startTime, String endTime);

    /**
     * 采集昨天至今的 HIS 数据（原 {@code RyTask#collectHISYesterday}）。
     */
    void collectHISYesterday();

    /**
     * 采集 N 天前的 HIS 数据（原 {@code RyTask#collectHISDaysBefore}）。
     *
     * @param daysBefore 天数
     */
    void collectHISDaysBefore(Long daysBefore);

    /**
     * 市一：同步手术信息（原 {@code ICollectHISService#syncOper}）。
     *
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @return 同步条数
     */
    Integer syncOper(String startTime, String endTime);

    /**
     * 处理子任务截止（原 {@code RyTask#dealSubtaskDeadline}）。
     *
     * @param orgid       机构 id
     * @param deadlineDay 截止天数
     */
    void dealSubtaskDeadline(String orgid, Integer deadlineDay);

    /**
     * 发送异常提醒（原 {@code RyTask#sendExceptInfo}）。
     * <p>
     * ⚠️ 原方法签名带 {@code throws Exception}，此处<b>原样保留</b>：
     * 调用方（运维端点）也声明了 {@code throws Exception}，行为不变。
     *
     * @throws Exception 原实现可能抛出的异常
     */
    void sendExceptInfo() throws Exception;
}