package com.ruoyi.common.core.service;

import com.ruoyi.common.core.service.dto.PatMedReq;
import com.ruoyi.common.core.service.dto.PatMedRes;

/**
 * 随访子任务<b>统计</b>的对外契约（只读）。
 *
 * <h3>为什么单独一个契约，而不是塞进 ServiceTaskMatchApi</h3>
 * {@link ServiceTaskMatchApi} 管的是"<b>按维度匹配长期随访任务</b>"
 * （科室/诊断/手术编码 → 任务行）；而本契约管的是
 * "<b>对 service_subtask 做聚合统计</b>"。两者虽然都读随访域的数据，
 * 但语义无关，混在一个契约里会让调用方难以判断"我到底该依赖谁"。
 *
 * <h3>为什么需要它（跨模块 SQL 收口）</h3>
 * 门诊的 {@code selectPatMedOuthospCount} 需要把
 * "本域门诊人次/人数" 与 "随访人次/人数" 合并成一个 {@code PatMedRes} 返回。
 * 后者查的是 {@code service_subtask}（子任务域），属跨域读；
 * 按"各模块独占自己的数据访问"原则，应由归属方提供查询能力。
 * 在「随访任务创建模块」落地之前，先放在 ruoyi-common。
 *
 * <h3>⚠️ 本契约只管"查"，不管"合并"</h3>
 * 原实现里 {@code patMedRes.setRc(count)}（把本域算出的门诊人次塞回去）
 * 属门诊域，留在调用方。
 */
public interface SubtaskStatApi {

    /**
     * 门诊随访人次/人数统计。
     * <p>
     * 原实现（门诊 {@code PatMedOuthospServiceImpl#selectPatMedOuthospCount} L345）：
     * {@code serviceSubtaskMapper.selectVisitCount(patMedReq)}。
     *
     * <h3>原 SQL 口径（逐字照搬，勿改）</h3>
     * <pre>
     * select 0 AS rc, count(1) AS rs
     * from service_subtask
     * where del_flag = 0 and service_type = 3
     *   [and orgid = ?] [and campusid = ?]
     *   [and date_format(visit_time,'%y%m%d') &gt;= date_format(?,'%y%m%d')]
     *   [and date_format(visit_time,'%y%m%d') &lt;= date_format(?,'%y%m%d')]
     *   [and deptcode in (...)]
     * </pre>
     * 注意：① 它<b>刻意把 rc（人次）置 0</b>，人次由调用方另行设置；
     * ② 日期比较用 {@code date_format} 到天，不是时间戳比较。
     *
     * @param req 统计条件（{@code startDate}/{@code endDate}/{@code orgid}/
     *            {@code campusid}/{@code deptcodeList}）
     * @return 含 {@code rs}（人数）的结果
     *         ⚠️ 原实现<b>不判空</b>直接 {@code patMedRes.setRc(...)} ——
     *         若 Mapper 返回 null 会 NPE。此处保持原行为（不额外兜底），
     *         由调用方按原样处理。
     */
    PatMedRes countVisitForStat(PatMedReq req);
}