package com.ruoyi.inhospvisit.mapper;

import com.ruoyi.inhospvisit.domain.row.VisitInhospRow;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

import java.util.List;

/**
 * 出入院记录（{@code pat_med_inhosp}）随访侧 Mapper —— 出入院随访模块自带。
 *
 * <h3>⚠️ 与 smartor 的 {@code PatMedInhospMapper} 是两套查询（本模块唯一真正的 SQL 重复）</h3>
 * 同一张表、两套 SQL，理由见 {@link VisitInhospRow} 的类注释。纪律：
 * <ul>
 *   <li>两边的 SQL 必须<b>逐条等价</b>；</li>
 *   <li>由 {@code sql/_probe/verify_inhospvisit_sql_expansion.py} 把两边的 WHERE/GROUP BY/ORDER BY
 *       动态展开后逐条比对（AND 顺序无关、{@code #{}}→{@code ?}、列清单折叠）；</li>
 *   <li>由 {@code sql/_probe/verify_inhospvisit_mapper.py} 校验接口方法↔XML statement 一一对应；</li>
 *   <li><b>改任一边必须同步改另一边</b>，并重跑这两个探针。</li>
 * </ul>
 *
 * <h3>方法对应的原实现（@ b25c3b51）</h3>
 * <table border="1">
 *   <tr><th>本方法</th><th>原调用点</th></tr>
 *   <tr><td>{@link #selectForScan}</td><td>{@code PatMedInhospServiceImpl} L329/458/527/1195/1328/1438/1529/1598
 *       （都是 {@code selectPatMedInhospList}）</td></tr>
 *   <tr><td>{@link #selectByInhospid}</td><td>L356/399/480/632/1409/1480/1505/1572/1632/1867/1915/1955/1968
 *       （都是 {@code selectPatMedInhospByInhospid}）</td></tr>
 *   <tr><td>{@link #updateFlags}</td><td>{@code updatePatMedInhosp}（多处，只回写标志位与 reason）</td></tr>
 * </table>
 */
@Mapper
public interface VisitInhospMapper {

    /**
     * 随访扫描/按标志位过滤（原 {@code PatMedInhospMapper#selectPatMedInhospList}）。
     * <p>
     * ⚠️ <b>必须逐字等价地保留原 SQL 的三处关键语义</b>：
     * <ol>
     *   <li>JOIN {@code pat_archive} 且要求 {@code a.del_flag = 0}、{@code b.del_flag = 0}、
     *       {@code a.idcardno IS NOT NULL} —— 这三个条件决定"谁会被扫到"；</li>
     *   <li>{@code GROUP BY b.inhospid, a.age, a.age_unit, a.telcode, a.id, a.sex} —— 去重语义；</li>
     *   <li>排序：{@code cry=1/2/3} 时 {@code order by b.endtime desc}；
     *       {@code cry=0} 时按 {@code bedSort} 三选一（含床位自然序的复杂表达式），
     *       默认 {@code order by b.starttime desc, b.bed_no asc}。
     *       <b>顺序会影响处理次序与最终结果</b>（尤其再入院停机逻辑），不能简化。</li>
     * </ol>
     *
     * @param query 过滤条件（随访侧只用到 flag / inhospstate / fuflag / orgid / cry / bedSort / patid 等）
     * @return 匹配行
     */
    List<VisitInhospRow> selectForScan(VisitInhospRow query);

    /**
     * 按主键查（原 {@code PatMedInhospMapper#selectPatMedInhospByInhospid}）。
     *
     * @param inhospid 出入院记录ID
     * @return 记录行；不存在返回 {@code null}
     */
    VisitInhospRow selectByInhospid(@Param("inhospid") Long inhospid);

    /**
     * 只回写随访标志位与 {@code long_task_reason}（原 {@code updatePatMedInhosp} 的随访用途子集）。
     * <p>
     * ⚠️ <b>刻意不做成"全字段动态更新"</b>：原 {@code updatePatMedInhosp} 有近百个
     * {@code <if test="xxx != null">}，调用方传什么就更新什么。随访侧只写这几列，
     * 所以这里显式列出，避免"传了个半满的实体导致某些列被意外写空/漏写"。
     * <p>
     * 传入的 {@code reason} 为 null 时<b>不改动</b> {@code long_task_reason}（与原 {@code <if>} 一致）。
     *
     * @param inhospid 出入院记录ID
     * @param flagColumn 标志位列名，只允许
     *        {@code deptcheck_flag} / {@code wardcheck_flag} / {@code diagcheck_flag} /
     *        {@code medcheck_flag} / {@code in_deptcheck_flag} / {@code in_wardcheck_flag} /
     *        {@code schedulecheck_flag}
     *        （白名单在 Service 层校验，SQL 里用 {@code <choose>} 展开成常量列名，不做字符串拼接）
     * @param flagValue  标志位值（"0" / "1" / "2" …）
     * @param reason     {@code long_task_reason} 的新值；null = 不改动
     * @return 影响行数
     */
    int updateFlags(@Param("inhospid") Long inhospid,
                    @Param("flagColumn") String flagColumn,
                    @Param("flagValue") String flagValue,
                    @Param("reason") String reason);

    /**
     * 只回写 {@code remark}（原 {@code updateCheckFlag} 的附带动作，L1680-1683）。
     * <p>
     * 原实现是在同一个"整实体动态更新"里顺手写 remark 的：
     * <pre>
     * if (StringUtils.isNotEmpty(remark)) {
     *     updateObj.setRemark(remark + " (type=" + type + ")");
     * }
     * patMedInhospMapper.updatePatMedInhosp(updateObj);
     * </pre>
     * 因为 {@code updatePatMedInhosp} 是"每个字段各自 {@code <if test="xxx != null">}"，
     * 所以拆成两次 update（flag 一次、remark 一次）与原来的"一次整实体更新"在结果上等价。
     *
     * @param inhospid 出入院记录ID
     * @param remark   新的备注（覆盖式）
     * @return 影响行数
     */
    int updateRemark(@Param("inhospid") Long inhospid, @Param("remark") String remark);
}