package com.ruoyi.task.api.spi;

import com.ruoyi.common.core.domain.entity.PatArchive;

import java.util.List;

/**
 * 患者档案读取能力 —— <b>ruoyi-task 的对外 SPI，由 smartor 侧实现</b>。
 *
 * <h3>为什么端口声明在 ruoyi-task、实现在 smartor</h3>
 * 任务侧要读 {@code pat_archive}，但该表不归 ruoyi-task
 * （患者档案是独立域，本次只把 {@link PatArchive} 这个<b>类型</b>上提到了 ruoyi-common）。
 * 按"各模块独占自己的数据访问"原则，ruoyi-task 不得自写针对 {@code pat_archive} 的 SQL。
 * <p>
 * 又因为 ruoyi-task <b>不能依赖 smartor</b>（会形成
 * {@code smartor -> ruoyi-task -> smartor} 硬循环），所以方向必须反过来：
 * <b>接口声明在 ruoyi-task、实现放在 smartor</b>，由 Spring 在运行期注入。
 * 编译期 ruoyi-task 只看到接口，smartor 依赖 ruoyi-task 因此可以 implements 它 —— 无环。
 *
 * <h3>为什么不需要新 DTO</h3>
 * {@link PatArchive} 已上提到 {@code com.ruoyi.common.core.domain.entity}，
 * 双方都可见，因此端口直接用实体本身，<b>无需逐字段映射</b>。
 *
 * <h3>⚠️ 实现必须保持"纯转发"</h3>
 * 实现方只做转发或等价的类型转换，不得加入业务判断。
 *
 * @see com.ruoyi.common.core.domain.entity.PatArchive
 */
public interface TaskArchivePort {

    /**
     * 按患者档案 id 查档案（原 {@code PatArchiveMapper#selectPatArchiveByPatid}，
     * 亦即 {@code IPatArchiveService#selectPatArchiveByPatid} —— 后者是前者的纯委托）。
     *
     * @param patid 档案 id
     * @return 档案；不存在返回 {@code null}
     */
    PatArchive findByPatid(Long patid);

    /**
     * 按条件查档案列表（原 {@code PatArchiveMapper#selectPatArchiveList}）。
     *
     * @param query 查询条件（非 null 字段参与过滤）
     * @return 档案集合
     */
    List<PatArchive> findList(PatArchive query);

    /**
     * 按 id 查「导入档案」并转成档案视图（原
     * {@code DtoConversionUtils.sourceToTarget(patArchiveImportMapper.selectPatArchiveImportById(patid), PatArchive.class)}）。
     * <p>
     * ⚠️ 原实现拿到的 {@code PatArchiveImport} <b>从不逐字段访问</b>，而是整体转成
     * {@link PatArchive}，所以这里把"取 + 转"合成一个方法，调用方拿到的仍是 {@link PatArchive}，
     * <b>行为完全不变</b>，且无需把 {@code PatArchiveImport} 暴露到 ruoyi-task。
     *
     * @param patid 档案 id
     * @return 转换后的档案；不存在返回 {@code null}
     */
    PatArchive findImportedByPatid(Long patid);
}