package com.ruoyi.task.api.spi;

import com.ruoyi.task.domain.ServiceSubtask;
import com.ruoyi.task.domain.ServiceSubtaskPreachform;

import java.util.List;

/**
 * 子任务「执行方式明细」（{@code service_subtask_preachform}）读写能力 ——
 * <b>ruoyi-task 的对外 SPI，由 smartor 侧实现</b>。
 *
 * <h3>为什么需要它</h3>
 * 任务侧的 4 个类（{@code ServiceSubtaskServiceImpl} / {@code ServiceTaskServiceImpl} /
 * {@code ServiceTaskScheduleServiceImpl} / {@code ScheduleSubtaskBuilder}）都要读写这张表，
 * 但该表的<b>归属模块是 {@code ruoyi-inhospvisit}</b>（已收口到 ruoyi-common 的
 * {@code PreachformApi}），ruoyi-task 不能依赖 smartor、也不该自写该表 SQL。
 *
 * <h3>⚠️ 这是【过渡】端口，形态刻意与旧 Mapper 一致</h3>
 * 本端口<b>逐方法镜像</b> smartor 既有的（已 {@code @Deprecated} 的）
 * {@code ServiceSubtaskPreachformMapper}：同名方法、同名参数、同返回类型
 * （{@code insert/update} 仍返回 {@code int}）。
 * 这样那 4 个类搬进 ruoyi-task 时<b>只需把注入的字段类型换成本端口，调用点一行都不用改</b>，
 * 把"改 25 处调用点 + 逐处换类型"的风险降到最低。
 * <p>
 * 之所以不直接让它们注入 {@code PreachformApi}：那需要把
 * {@code ServiceSubtaskPreachform} 换成 {@code VisitPreachformRow}、
 * 并把 {@code int} 返回值改成 {@code boolean}，共约 25 处调用点，
 * 属独立的收口动作（见 {@code doc/跨模块数据访问原则与收口方案.md}），不在本次范围内。
 *
 * <h3>将来动作</h3>
 * 待 preachform 全面收口时，把本端口与 smartor 的 Bridge 一并删除，
 * 4 个类改为直接注入 {@code PreachformApi}。
 *
 * <h3>⚠️ 实现必须保持"纯转发"</h3>
 * 实现方只转发到既有 Mapper/Bridge，<b>不得</b>加入业务判断或字段补齐。
 *
 * @see com.ruoyi.common.core.service.PreachformApi 该表真正的归属契约
 */
public interface TaskPreachformPort {

    /**
     * 按主键查（原 {@code selectServiceSubtaskPreachformById}）。
     */
    ServiceSubtaskPreachform selectServiceSubtaskPreachformById(Long id);

    /**
     * 按条件查列表（原 {@code selectServiceSubtaskPreachformList}）。
     */
    List<ServiceSubtaskPreachform> selectServiceSubtaskPreachformList(ServiceSubtaskPreachform query);

    /**
     * 新增（原 {@code insertServiceSubtaskPreachform}）。
     *
     * @return 受影响行数（与原实现一致，仍为 {@code int}）
     */
    int insertServiceSubtaskPreachform(ServiceSubtaskPreachform row);

    /**
     * 按主键更新（原 {@code updateServiceSubtaskPreachform}）。
     */
    int updateServiceSubtaskPreachform(ServiceSubtaskPreachform row);

    /**
     * 按条件更新（原 {@code updateSSPByCondition}）。
     */
    int updateSSPByCondition(ServiceSubtaskPreachform row);

    /**
     * 按 {@code subid} 删除该子任务的所有发送方式（原
     * {@code deleteServiceSubtaskPreachformBySubid}，实际是软删）。
     */
    int deleteServiceSubtaskPreachformBySubid(Long subId);

    /**
     * 按 taskid/orgid 查（原 {@code selectBySubtask}；⚠️ 方法名易误解，
     * 它不按 subtask 主键查，见 {@code PreachformApi#findByTaskidAndOrgid}）。
     */
    List<ServiceSubtaskPreachform> selectBySubtask(ServiceSubtask subtask);
}