package com.ruoyi.common.core.service;

import com.ruoyi.common.core.service.dto.InhospPositionRecord;
import com.ruoyi.common.core.service.dto.SltdGatherReq;

import java.time.LocalDateTime;
import java.util.Date;
import java.util.List;

/**
 * HIS 采集能力契约 —— 新华 / 河南 / 省立同德（南华附一）/ 疾病字典。
 *
 * <h3>为什么有这个契约</h3>
 * HIS 采集的调度编排（原 {@code RyTask#dealHisData}）已搬进 {@code ruoyi-datacollection}，
 * 但四个采集实现当前<b>仍在 smartor</b>：
 * <ul>
 *   <li>{@code IXHGatherPatArchiveServiceImpl}（新华，含预约停诊）</li>
 *   <li>{@code IHNGatherPatArchiveServiceImpl}（河南）</li>
 *   <li>{@code IServiceSLTDHealthcareRecordServiceImpl}（省立同德 / 南华附一，来未来）</li>
 *   <li>{@code IIcd10Service#queryAddIcd10}（疾病字典增量）</li>
 * </ul>
 * {@code ruoyi-datacollection} 不依赖 smartor（否则新模块就被单体绑死），
 * 所以按 {@code doc/跨模块数据访问原则与收口方案.md} 走<b>契约</b>：
 * 契约声明在 ruoyi-common，smartor 侧用纯转发的 Bridge 实现
 * （{@code com.smartor.service.impl.bridge.HisGatherApiBridge}）。
 *
 * <h3>⚠️ 这是【过渡】契约，形态刻意与旧 Service 一致</h3>
 * 逐方法镜像既有 Service 方法：同名语义、同参数含义、同返回类型
 * （<b>唯一例外</b>：{@link #gatherSltdHealthcareRecords} 返回条数而非 List，原因见该方法注释），
 * 使 Bridge 只做"建 VO + 转发"，<b>不在 Bridge 里加任何业务判断</b>。
 *
 * <h3>将来动作（分阶段搬迁）</h3>
 * 采集实现按批搬进 {@code ruoyi-datacollection}（见
 * {@code doc/数据采集模块化_调研与实施方案.md}）：搬完一批，对应方法就从本契约删除，
 * 全部搬完后本契约与 smartor 的 Bridge 一起删除，收为模块内部接口。
 *
 * @see com.ruoyi.common.core.service.dto.SltdGatherReq 省立同德/南华附一采集入参
 */
public interface HisGatherApi {

    /**
     * 新华：采集出入院信息并落 {@code pat_med_inhosp} / {@code pat_archive}
     * （原 {@code IXHGatherPatArchiveService#getInHospDataGather}）。
     *
     * @param cry       出入院类型：0-入院，1-出院
     * @param startTime 开始时间
     * @param endTime   结束时间
     */
    void gatherXhInhospRecords(String cry, LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 河南：采集数据（原 {@code IHNGatherPatArchiveService#hnDataGather}，
     * 入参 {@code HnDataGatherVO} 只有 startTime / endTime 两个字段，故这里直接传两个 Date）。
     *
     * @param startTime 开始出院日期
     * @param endTime   结束出院日期
     */
    void gatherHnRecords(Date startTime, Date endTime);

    /**
     * 省立同德 / 南华附一：采集科室病区信息
     * （原 {@code IServiceSLTDHealthcareRecordService#queryDeptWardAreaInfoList}）。
     *
     * @param req 只需 {@code orgId} + {@code campusIds}
     * @return 原 Service 的返回值，原样透出（可能为 {@code null}）
     */
    Boolean gatherSltdDeptWardArea(SltdGatherReq req);

    /**
     * 省立同德 / 南华附一：采集医院用户信息
     * （原 {@code IServiceSLTDHealthcareRecordService#queryHospUserInfoList}）。
     *
     * @param req 只需 {@code orgId} + {@code campusId} + {@code statusList}
     * @return 原 Service 的返回值，原样透出（可能为 {@code null}）
     */
    Boolean gatherSltdHospUser(SltdGatherReq req);

    /**
     * 省立同德 / 南华附一：采集诊疗记录（预入院 / 入院 / 出院）
     * （原 {@code IServiceSLTDHealthcareRecordService#queryHealthcareRecordList}）。
     * <p>
     * ⚠️ <b>唯一偏离"逐方法镜像"的地方：返回条数。</b>原实现丢弃 List 返回值，但来未来查询接口
     * 单次最多返回 1500 条且<b>截断不报错</b>，编排侧必须拿到"这次到底返回了几条"才能判断是否要拆小重采，
     * 否则就是静默丢数据（2026-10 已踩过：7 月病区人数比真实值少）。这里只透出 {@code size}，
     * 不做任何业务判断。
     *
     * @param req 采集入参（各字段含义与 {@code ServiceSLTDInhospReqVO} 同名）
     * @return 本次接口<b>实际返回</b>的记录条数；== 1500 表示可能已被截断
     */
    int gatherSltdHealthcareRecords(SltdGatherReq req);

    /**
     * 省立同德 / 南华附一：查询某个在院患者<b>当前</b>的科室 / 病区 / 床位
     * （来未来 {@code /osj/hbos-thirdparty-integration/standard/common/healthcareRecord/dtcQueryHealthcareRecordList}，
     * 与"入院采集"是同一个接口，区别只是按 {@code healthcareRecordNo} 单查）。
     * <p>
     * ⚠️ <b>只取数、不落库</b>：与库内比对、决定改哪些字段，属于采集模块
     * （{@code ruoyi-datacollection}），不在这里判断。
     * <p>
     * 入参约定（由调用方填）：{@code orgId} + {@code campusId} + {@code statusList=["FH0109.24"]}
     * + {@code healthcareRecordNo}。其中 {@code statusList} 是可靠的"真在院"过滤 ——
     * 患者已出院/预出院时接口返回<b>空列表</b>。
     * <p>
     * 取数失败（HTTP 异常 / 返回非 200 / 返回体为空）时<b>抛 RuntimeException</b>，
     * 由调用方按"该患者这一轮失败"计数并继续下一个患者 —— 不返回空列表，
     * 否则"接口挂了"和"患者已不在院"会被混成同一件事。
     *
     * @param req 见上
     * @return 当前位置记录；<b>空列表 = 该患者当前不在"入院"状态</b>（不是失败）
     */
    List<InhospPositionRecord> querySltdInhospPosition(SltdGatherReq req);

    /**
     * 疾病字典增量采集（原 {@code IIcd10Service#queryAddIcd10}）。
     * <p>
     * 它属于"档案字典域"，不是 HIS 采集实现，但它就在同一次采集轮次里被触发
     * （原 {@code RyTask#dealHisData} 的 {@code sltd.gather.sysuser=2} 分支），
     * 所以一并纳入本契约，避免新模块为一行调用再开一个契约。
     *
     * @return 新增条数
     */
    int gatherIcd10();
}