package com.ruoyi.common.core.service;

/**
 * 手术随访 / 门诊随访能力的预留接口。
 *
 * <h3>为什么现在就要留</h3>
 * 出入院随访的入口里混着手术随访的调用：
 * <ul>
 *   <li>{@code PatMedInhospServiceImpl#dealOutHospInfo} L449-451 —— {@code !active.equals("xh")} 时调
 *       {@code addOperationSubTask(config)}；</li>
 *   <li>{@code #dealOutHospInfoBySchedule} L559-608 —— 任务组的手术分支
 *       （查 {@code selectOperationItemListMaxLevel}、走 {@code boxedServiceSubtaskForOp}）。</li>
 * </ul>
 * 而手术随访按你的版图属于第二批的 {@code ruoyi-othervisit}，本次<b>不搬</b>。
 * 但 {@code dealOutHospInfo} 本次就要搬进 {@code ruoyi-inhospvisit}，
 * 于是必须有地方安放这两个调用点 —— 就是本接口。
 *
 * <h3>本次（第一批）落地程度</h3>
 * <ul>
 *   <li>接口：现在就建（本文件）；</li>
 *   <li>实现：<b>过渡实现留在 smartor</b>（包一层现有 {@code PatMedInhospServiceImpl} 的方法，
 *       零逻辑改动）；</li>
 *   <li>第二批做 {@code ruoyi-othervisit} 时，把实现方换成新模块即可，
 *       {@code ruoyi-inhospvisit} 一行都不用改。</li>
 * </ul>
 *
 * <h3>调用方务必降级</h3>
 * 取不到实现时按"不做手术随访"处理并打 WARN，不能影响出院/入院随访主流程。
 */
public interface OtherVisitApi {

    /**
     * 手术随访扫描（原 {@code PatMedInhospServiceImpl#addOperationSubTask}，迁移前 L1362-1430）。
     * <p>
     * 内部行为要点（迁移时必须保留）：
     * <ul>
     *   <li>非 {@code active == "hzszlyy"} 站点才设 {@code inhospstate="1"}（迁移前 L1366-1368）；</li>
     *   <li>查 {@code selectOperationItemListMaxLevel}（{@code opercheck_flag='0'} 且 {@code main_flag='1'}）；</li>
     *   <li>{@code oplevelcode} 为空则跳过；</li>
     *   <li>按离院科室 + 离院病区<b>分别</b>查 {@code ServiceTaskoper} 并合并；</li>
     *   <li>没配任务 → 置 {@code opercheck_flag="2"} + 「所患的手术未配置长期任务;」。</li>
     * </ul>
     *
     * @param config {@code sys_config: visit.early.day} 的值，可能为 null
     * @return 处理的手术记录数
     */
    int addOperationSubTask(String config);

    /**
     * 任务组（appltype=5）首轮纳入 —— <b>本次未搬，仍由 smartor 的实现承接</b>。
     *
     * <h3>为什么放在这个接口上</h3>
     * 原 {@code dealOutHospInfoBySchedule}(L471-614) 由两段构成：
     * <ul>
     *   <li><b>非手术分支</b>：按维度过滤扫患者 → {@code boxedServiceSubtask}
     *       → {@code scheduleSubtaskBuilder.buildSubtasksForPatient}；</li>
     *   <li><b>手术分支</b>：{@code selectOperationItemListMaxLevel}
     *       + {@code boxedServiceSubtaskForOp} → 同一 builder。</li>
     * </ul>
     * 手术分支正是本接口的域（手术随访），而非手术分支依赖的
     * {@code ScheduleSubtaskBuilder} 同时服务"HIS 自动纳入"与"前端手动勾选"两条路径，
     * 不属本次范围。所以<b>整个方法本次留在 smartor</b>，
     * 由新模块的 Controller 通过本接口转发 —— 这样端点能迁进新模块（URL 不变），
     * 而实现不必"搬一半留一半"。
     * <p>
     * 第二批做 {@code ruoyi-othervisit} 时，连同 {@code ScheduleSubtaskBuilder} 一起收走。
     *
     * @param config {@code sys_config: visit.early.day}
     * @return 原实现固定返回 1
     */
    int dealOutHospInfoBySchedule(String config);
}