package com.ruoyi.inhospvisit.api;

import com.ruoyi.common.core.service.dto.VisitAgainSubtaskDto;

/**
 * 出入院随访模块的对外契约（<b>其它模块唯一允许依赖的类型</b>）。
 * <p>
 * 实现是本模块的常驻门面 {@link InhospVisitFacade}。
 *
 * <h3>约定（照抄满意度模块的 api 契约纪律）</h3>
 * <ul>
 *   <li><b>只暴露 DTO 与基本类型</b>，不暴露本模块内部 Service/Mapper/domain；</li>
 *   <li>门面<b>永远存在</b>，所以调用方的 {@code @Autowired} 不会因开关状态而启动失败；</li>
 *   <li>模块关闭 / 实现缺失 / 容器异常时，各方法返回安全空值并打 WARN，<b>不抛异常</b>
 *       —— 出入院随访挂了就是当天全院随访停摆，绝不能让调用方主流程被拖垮。</li>
 * </ul>
 *
 * <h3>与 ruoyi-common 里那个接口的关系</h3>
 * {@code com.ruoyi.common.core.service.PublicitySubtaskApi} 是<b>下沉给 ruoyi-publicity 用的最小接口</b>
 * （只有 {@code generatePublicitySubtask} 一个方法）。
 * 本接口是<b>完整契约</b>，供直接依赖本模块的 smartor / ruoyi-quartz 使用。
 * <p>
 * 两者<b>刻意不做继承</b>（避免"假继承"）：由门面 {@link InhospVisitFacade} 同时实现二者，
 * 于是按任一种类型查找都能拿到同一个常驻 Bean —— 这与满意度把
 * {@code ISatisfactionCategoryService} 一并实现到 {@code SatisfactionFacade} 是同一手法。
 */
public interface InhospVisitApi {

    /**
     * 模块是否可用（开关打开 <b>且</b> 内部实现存在）
     */
    boolean isEnabled();

    /**
     * 出院随访主扫描（原 {@code PatMedInhospServiceImpl#dealOutHospInfo}，迁移前 L324-463）。
     * <p>
     * 顺序（迁移时必须保持）：
     * <ol>
     *   <li>入院宣教 —— 改为回调 {@code com.ruoyi.common.core.service.PublicityApi#dealInHospPublicity(String)}；</li>
     *   <li>药品宣教（仅 sltd）—— 改为回调 {@code PublicityApi#dealMedicalPublicity(String)}；</li>
     *   <li>基于规则的出院随访 —— {@code addSubTaskByRule}；</li>
     *   <li>手术随访 —— 改为回调 {@code com.ruoyi.common.core.service.OtherVisitApi#addOperationSubTask(String)}；</li>
     *   <li>再入院处理 —— {@code dealInHospInfo}。</li>
     * </ol>
     *
     * @param config {@code sys_config: visit.early.day} 的值，可能为 null
     * @return 原实现固定返回 1
     */
    int dealOutHospInfo(String config);

    /**
     * 任务组（appltype=5）首轮纳入（原 {@code PatMedInhospServiceImpl#dealOutHospInfoBySchedule}，
     * 迁移前 L471-614）。含手术分支（回调 {@code OtherVisitApi}）。
     *
     * @param config {@code sys_config: visit.early.day} 的值，可能为 null
     * @return 原实现固定返回 1
     */
    int dealOutHospInfoBySchedule(String config);

    /**
     * 手术随访手动触发（原 {@code PatMedInhospController#addOperationSubTask}）。
     * <p>
     * ⚠️ <b>本次未搬，仍由 smartor 的实现承接</b>（属第二批 {@code ruoyi-othervisit}）。
     * 本方法存在是为了让端点能迁进本模块（URL 不变），实现转发到
     * {@code com.ruoyi.common.core.service.OtherVisitApi}。
     *
     * @param config {@code sys_config: visit.early.day}
     * @return 转发结果（调用方不依赖该值）
     */
    int addOperationSubTask(String config);

    /**
     * 门诊随访扫描（原 {@code IPatMedOuthospService#dealOutpatientInfo}）。
     * <p>
     * 之所以由本模块的入口一并触发：原 {@code /smartor/patinhosp/dealOutHospInfo} 端点
     * 在同一次请求里做了"出院随访 + 门诊随访"两件事（L263-265），
     * 端点迁进本模块后必须保持这个行为。
     * <p>
     * ⚠️ 站点判断（{@code active != "xh"}）由调用方负责，本方法只管转发。
     *
     * @return 处理的门诊记录数
     */
    int dealOutpatientInfo();

    /**
     * 任务组循环轮次滚动（原 {@code ServiceTaskScheduleServiceImpl#rollCycleTasks}，L170 起 7 个方法 362 行）。
     *
     * @return 本次推进的计划数
     */
    int rollTaskGroupCycle();

    /**
     * 为「随访超时 → 再次随访」组装子任务草稿（替代原 {@code RyTask#dealSubtaskDeadline} 里的
     * {@code selectPatMedInhospList} + {@code boxedServiceSubtask} 两步）。
     * <p>
     * 出入院记录与组装逻辑搬迁后都在本模块内，所以由本方法一次完成；
     * 调用方拿到草稿后自己补 {@code upid / visitCount / visitType / visitDeptCode / visitDeptName}
     * 再落库（落库走 {@code com.ruoyi.common.core.service.VisitTaskCreateApi#createSubtask}）。
     * <p>
     * ⚠️ 原实现在查不到出入院记录时是 {@code continue} 跳过，
     * 调用方必须检查 {@code isInhospFound()}。
     *
     * @param orgid     机构ID
     * @param inhospid  出入院记录ID
     * @param newTaskId 下一个长期任务ID（原 {@code serviceTask.getNexttaskid()}）
     * @param sendstate 调用方要求的发送状态（原实现传 2L）
     * @return 草稿；模块不可用或组装失败时返回 {@code isInhospFound()==false} 的空结果
     */
    VisitAgainSubtaskDto buildAgainVisitDraft(String orgid, Long inhospid, Long newTaskId, Long sendstate);

    /**
     * 给宣教模块用的最小能力：生成一条宣教类子任务（type=0 药品宣教 / 4 入院科室 / 5 入院病区）。
     * <p>
     * 与 {@code com.ruoyi.common.core.service.PublicitySubtaskApi#generatePublicitySubtask} 是同一能力；
     * {@link InhospVisitFacade} 同时实现两个接口，因此按任一种类型查找都能拿到同一个 Bean。
     *
     * @return true = 已处理
     */
    boolean generatePublicitySubtask(Long taskid, Long patid, Long inhospid, int type, String config);
}