package com.ruoyi.datacollection.api;

/**
 * 数据采集模块的对外契约（<b>其它模块唯一允许依赖的类型</b>）。
 * <p>
 * 实现是本模块的常驻门面 {@link DataCollectionFacade}。
 *
 * <h3>约定（照抄其它模块的 api 契约纪律）</h3>
 * <ul>
 *   <li><b>只暴露基本类型</b>，不暴露本模块内部 Service / domain；</li>
 *   <li>门面<b>永远存在</b>，调用方的 {@code @Autowired} 不会因开关状态而启动失败；</li>
 *   <li>模块被关闭时<b>抛 {@link DataCollectionModuleDisabledException}</b>
 *       （而不是静默返回）：采集是"数据进不来"的链路，
 *       静默跳过与"本来就没数据"分不开，排查时最怕这个。</li>
 * </ul>
 */
public interface DataCollectionApi {

    /**
     * 模块是否可用（开关打开）
     * <p>
     * ⚠️ 这是<b>查询开关状态</b>的方法，刻意不受守卫：调用方需要它来预判，
     * 如果它也抛异常就自我矛盾了。
     */
    boolean isEnabled();

    /**
     * HIS 数据采集（原 {@code RyTask#dealHisData(String)}）：
     * 按 {@code spring.profiles.active} 分站点采集新华 / 河南 / 省立同德（南华附一）的
     * 出入院、预入院、出院与医院用户/部门信息。
     *
     * @param todayZeroStr 采集基准时间 {@code yyyy-MM-dd HH:mm:ss}；
     *                     为空时取"今天 00:00"，采集范围是 {@code [基准-1天, 基准)}。
     *                     nhfy / sltd 站点在入参非空时会额外做 30 天分段回溯采集。
     * @throws DataCollectionModuleDisabledException 模块被关闭（{@code datacollection.enabled=false}）
     */
    void dealHisData(String todayZeroStr);

    /**
     * 在院患者"科室 / 病区 / 床位"刷新（南华附一，每天一次全量核对）：
     * 按患者查 HIS 的转科记录、取最新一段，与 {@code pat_med_inhosp} 比对后只写变化的字段。
     * <p>
     * 幂等，可重复触发；站点不是 {@code nhfy} 时不做任何事并返回 0。
     *
     * @return 实际发生更新的记录条数
     * @throws DataCollectionModuleDisabledException 模块被关闭（{@code datacollection.enabled=false}）
     */
    int refreshInhospDeptInfo();
}