package com.ruoyi.task.api;

import com.ruoyi.task.domain.IvrTaskVisitResult;
import com.ruoyi.task.domain.ServiceSubtask;
import com.ruoyi.task.domain.ServiceSubtaskDetail;
import com.ruoyi.task.domain.ServiceSubtaskDetailTrace;
import com.ruoyi.task.domain.ServiceTask;
import com.ruoyi.task.domain.entity.ServiceSubtaskEntity;

import java.util.List;

/**
 * 任务模块的<b>子任务数据访问 API</b>：给"需要在归属模块之外读写子任务数据"的模块用。
 *
 * <h3>为什么要有它</h3>
 * 按 {@code doc/跨模块数据访问原则与收口方案.md} 的落地口径：
 * <b>写操作（insert/update/delete 归属表）任何非归属模块一律禁止</b>；
 * {@code service_subtask} / {@code service_subtask_detail} / {@code service_task} 等表归本模块，
 * 所以需要这些数据的模块（当前是 {@code ruoyi-phone}）只能经本 API 调用，
 * <b>不许在自己模块里写针对这些表的 SQL</b>。
 *
 * <h3>与其它对外契约的关系</h3>
 * <ul>
 *   <li>{@code com.ruoyi.common.core.service.*}（VisitTaskCreateApi / ServiceTaskMatchApi /
 *       SubtaskStatApi / SubtaskOptionMatchApi）：给 smartor / ruoyi-admin / ruoyi-quartz 用的
 *       "下沉到 ruoyi-common 的查询契约"，走的是 smartor 侧实现；</li>
 *   <li>{@link TaskSubtaskApi}（本接口）：<b>模块到模块</b>的数据访问入口，
 *       实现就在本模块内（{@code api.contract.TaskSubtaskApiImpl}），
 *       因此只允许"模块 → 任务模块"这一个方向，不会形成循环依赖。</li>
 * </ul>
 *
 * <h3>方法语义</h3>
 * 每个方法都是对既有 Mapper/Service 的<b>原样转发</b>，不含任何额外业务判断
 * （尤其 {@link #updateSubtask} 用动态 SQL 只更新非空字段，语义必须与
 * {@code ServiceSubtaskMapper.updateServiceSubtask} 保持一致，否则电话流程会误改字段）。
 */
public interface TaskSubtaskApi {

    /**
     * 按子任务 ID 取子任务（原 {@code ServiceSubtaskMapper#selectServiceSubtaskById}）
     *
     * @param subId 子任务 ID
     * @return 子任务；不存在返回 {@code null}
     */
    ServiceSubtask getSubtask(Long subId);

    /**
     * 按条件查子任务列表（原 {@code ServiceSubtaskMapper#selectServiceSubtaskList}）
     *
     * @param query 查询条件（taskid / patid / phone / type / sendstate 等）
     * @return 子任务列表
     */
    List<ServiceSubtask> findSubtasks(ServiceSubtaskEntity query);

    /**
     * 更新子任务（原 {@code ServiceSubtaskMapper#updateServiceSubtask}，动态 SQL 只改非空字段）
     *
     * @param subtask 待更新对象（必须带 id）
     * @return 受影响行数
     */
    int updateSubtask(ServiceSubtask subtask);

    /**
     * 按任务 ID 取任务（原 {@code IServiceTaskService#selectServiceTaskByTaskid}），
     * 电话流程用它取开场白（kcb）、结束语（jsy）以及话术通配符（textParam）
     *
     * @param taskid 任务 ID
     * @return 任务；不存在返回 {@code null}
     */
    ServiceTask getTask(Long taskid);

    /**
     * 按条件查子任务明细（原 {@code ServiceSubtaskDetailMapper#selectServiceSubtaskDetailList}）
     *
     * @param query 查询条件（subId / taskid / scriptid / guid / orgid 等）
     * @return 明细列表
     */
    List<ServiceSubtaskDetail> findSubtaskDetails(ServiceSubtaskDetail query);

    /**
     * 新增子任务明细（原 {@code ServiceSubtaskDetailMapper#insertServiceSubtaskDetail}）
     *
     * @param detail 明细
     * @return 受影响行数
     */
    int insertSubtaskDetail(ServiceSubtaskDetail detail);

    /**
     * 修改子任务明细（原 {@code ServiceSubtaskDetailMapper#updateServiceSubtaskDetail}）
     *
     * @param detail 明细（必须带 id）
     * @return 受影响行数
     */
    int updateSubtaskDetail(ServiceSubtaskDetail detail);

    /**
     * 新增任务访问结果（原 {@code IvrTaskVisitResultMapper#insertIvrTaskVisitResult}），
     * 电话流程把每一题的"问题 + 患者原话 + 命中选项"记进该表
     *
     * @param visitResult 访问结果
     * @return 受影响行数
     */
    int insertVisitResult(IvrTaskVisitResult visitResult);

    /**
     * 新增子任务异常跟踪（原 {@code IServiceSubtaskDetailTraceService#insertServiceSubtaskDetailTtrace}），
     * 电话流程命中"异常选项且带责任科室"时写一条，供随访异常处理页使用
     *
     * @param trace 异常跟踪记录
     * @return 受影响行数
     */
    int insertDetailTrace(ServiceSubtaskDetailTrace trace);
}