package com.ruoyi.common.core.service;

import com.ruoyi.common.core.service.dto.ServiceTaskMatchDto;

import java.util.List;

/**
 * 「长期随访任务匹配」的对外契约。
 *
 * <h3>为什么需要它（本契约是门急诊/手术随访模块化的唯一新增契约）</h3>
 * 三个随访模块（出入院 {@code ruoyi-inhospvisit}、门急诊 {@code ruoyi-outpatientvisit}、
 * 其他 {@code ruoyi-othervisit}）都要做同一件事：<b>按某个维度查"有没有配长期随访任务"</b>。
 * 现状是各自直接注入 smartor 的 Mapper：
 *
 * <pre>
 * 门诊：serviceTaskdeptMapper.selectServiceTaskdeptList(q)   // 科室维度 service_type="3"
 *       serviceTaskdiagMapper.selectServiceTaskdiagList(q)   // 诊断维度
 * 手术：serviceTaskoperMapper.selectServiceTaskoperList(q)   // 手术编码维度
 * 宣教：serviceTaskmedicalMapper...                          // 药品维度（本模块自带 PublicityDataPort）
 * </pre>
 *
 * 这些 Mapper 属于 smartor 的「服务任务」域，<b>不能</b>跟着随访模块搬
 * （它们同时被出入院/门诊/手术/宣教四方共用，搬给任何一方都会让另外三方反向依赖）。
 * 所以按既有套路（{@code VisitTaskCreateApi} / {@code PublicityDataPort} 同样的做法）
 * 把"查"这一层做成 ruoyi-common 的契约，smartor 侧提供过渡实现。
 *
 * <h3>⚠️ 本契约只管"查"，不管"判断"</h3>
 * 原实现里"查不到就把标志位置 {@code "2"} 并写原因文案"属于<b>随访域的业务规则</b>，
 * 留在各随访模块里（门诊/出入院/手术的原因文案各不相同）。
 * 本契约只做「给定条件 → 返回匹配到的行」，与 {@code selectServiceTask*List} 逐字对应。
 *
 * <h3>⚠️ 返回类型不得是 smartor 实体</h3>
 * 见 {@link ServiceTaskMatchDto} 的反向依赖红线说明。
 *
 * <h3>各方法的原实现对应</h3>
 * <table border="1">
 *   <tr><th>本契约方法</th><th>原 Mapper 调用</th></tr>
 *   <tr><td>{@link #findLongTasksByDept(String, String)}</td>
 *       <td>{@code ServiceTaskdeptMapper.selectServiceTaskdeptList}</td></tr>
 *   <tr><td>{@link #findLongTasksByDiag(String)}</td>
 *       <td>{@code ServiceTaskdiagMapper.selectServiceTaskdiagList}</td></tr>
 *   <tr><td>{@link #findLongTasksByOpcode(String)}</td>
 *       <td>{@code ServiceTaskoperMapper.selectServiceTaskoperList}</td></tr>
 * </table>
 *
 * @see ServiceTaskMatchDto
 */
public interface ServiceTaskMatchApi {

    /**
     * 科室维度：查该科室下已配置的长期随访任务。
     * <p>
     * 原实现（门诊 {@code PatMedOuthospServiceImpl#dealOutpatientInfo} L394-398）：
     * <pre>
     * ServiceTaskdept q = new ServiceTaskdept();
     * q.setLongtask(1L);
     * q.setDeptCode(patMedOuthosp1.getDeptcode());
     * q.setServiceType("3");
     * List&lt;ServiceTaskdept&gt; list = serviceTaskdeptMapper.selectServiceTaskdeptList(q);
     * </pre>
     * 即：{@code del_flag=0} + {@code longtask=1} + {@code dept_code=?} + {@code service_type=?}。
     *
     * @param deptCode    科室编码（原 {@code patMedOuthosp.deptcode}）
     * @param serviceType 服务类型（门诊传 {@code "3"}；其它调用方传各自的值，不做假设）
     * @return 匹配到的任务行；查不到返回空集合（<b>不返回 null</b>）
     */
    List<ServiceTaskMatchDto> findLongTasksByDept(String deptCode, String serviceType);

    /**
     * 诊断维度：查该 ICD10 下已配置的长期随访任务。
     * <p>
     * 原实现（门诊 L410-413）：{@code longtask=1} + {@code icd10code=?}（<b>不设 serviceType</b>）。
     *
     * @param icd10code ICD10 编码（原 {@code patMedOuthosp.icd10code}）
     * @return 匹配到的任务行；查不到返回空集合
     */
    List<ServiceTaskMatchDto> findLongTasksByDiag(String icd10code);

    /**
     * 手术编码维度：查该手术编码下已配置的长期随访任务。
     * <p>
     * 原实现（手术 {@code PatMedOperationServiceImpl#dealOperationInfo} L118-121）：
     * {@code longtask=1} + {@code opcode=?}（<b>不设 serviceType</b>）。
     *
     * @param opcode 手术编码（原 {@code patMedOperation.opcode}）
     * @return 匹配到的任务行；查不到返回空集合
     */
    List<ServiceTaskMatchDto> findLongTasksByOpcode(String opcode);
}