package com.ruoyi.common.core.service;

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

import java.util.List;

/**
 * 随访子任务「执行方式明细」（{@code service_subtask_preachform}）的对外契约。
 *
 * <h3>为什么需要它（跨模块 SQL 收口）</h3>
 * 这张表的归属模块是 {@code ruoyi-inhospvisit}，但在收口之前：
 * <ul>
 *   <li>smartor 里<b>另有一整份</b> {@code ServiceSubtaskPreachformMapper}（9 个方法）
 *       与同名 XML —— 与本模块的 {@code VisitPreachformMapper} 是<b>同一个表的两套 CRUD</b>；</li>
 *   <li>有 <b>15 个文件</b>（跨 smartor / ruoyi-admin / ruoyi-quartz）直连那份 Mapper。</li>
 * </ul>
 * 这违反了"各模块独占自己的数据访问"的原则：改任一边的 SQL 都可能与另一边漂移。
 * 本契约把"读写这张表"收敛成<b>唯一入口</b>，调用方一律经此访问。
 *
 * <h3>⚠️ 本契约是纯数据访问，不含任何业务判断</h3>
 * 逐方法与原 {@code ServiceSubtaskPreachformMapper} 对应，条件/列/顺序照抄。
 * "什么时候该插一条、该置什么状态"属于调用方的业务，留在调用方。
 *
 * <h3>⚠️ 三个 softDelete* 是"软删"</h3>
 * 原实现里 {@code deleteServiceSubtaskPreachformById / ByIds / BySubid} 的语句
 * 都是 {@code update ... set del_flag = 1}（其中一个还用 {@code <delete>} 标签包着 update）。
 * 本契约按<b>实际行为</b>命名为 {@code softDelete*}，语义不变。
 *
 * @see VisitPreachformRow
 */
public interface PreachformApi {

    /**
     * 按主键查（原 {@code selectServiceSubtaskPreachformById}）。
     *
     * @return 行；不存在返回 {@code null}
     */
    VisitPreachformRow findById(Long id);

    /**
     * 按条件查（原 {@code selectServiceSubtaskPreachformList}）。
     * <p>
     * 固定条件 {@code del_flag = 0}，其余 8 个字段为可选条件：
     * {@code subid / taskid / currentSendTime / preachform / sendstate / orgid / sort / compensateTime}。
     *
     * @param query 查询条件（非 null 字段参与过滤）
     * @return 行集合；无匹配返回空集合（<b>不返回 null</b>）
     */
    List<VisitPreachformRow> findList(VisitPreachformRow query);

    /**
     * 按 {@code taskid + orgid} 查（原 {@code selectBySubtask}）。
     * <p>
     * ⚠️ 原方法名易误解：它<b>不按 subtask 主键查</b>，而是以
     * {@code del_flag = 0} 加可选的 {@code taskid}、{@code orgid} 为条件。
     */
    List<VisitPreachformRow> findByTaskidAndOrgid(Long taskid, String orgid);

    /**
     * 新增（原 {@code insertServiceSubtaskPreachform}）。
     * <p>自增主键会回填到 {@code row.id}（对应原 XML 的 {@code useGeneratedKeys}）。
     *
     * @return true = 落库成功（原返回 {@code int}，此处按"== 1"折算）
     */
    boolean insert(VisitPreachformRow row);

    /**
     * 按主键更新（原 {@code updateServiceSubtaskPreachform}，WHERE {@code id = #{id}}）。
     */
    boolean updateById(VisitPreachformRow row);

    /**
     * 按条件更新（原 {@code updateSSPByCondition}）。
     * <p>
     * SET 子句与 {@link #updateById} 相同，区别只在 WHERE：
     * 按 {@code subid / taskid / preachform / remark / orgid} 逐项可选，且<b>没有 id 条件</b>。
     * 两处刻意不合并 —— 合并会改变"按什么定位行"的语义。
     */
    boolean updateByCondition(VisitPreachformRow row);

    /**
     * 按主键软删（原 {@code deleteServiceSubtaskPreachformById}）。
     */
    boolean softDeleteById(Long id);

    /**
     * 按主键集合软删（原 {@code deleteServiceSubtaskPreachformByIds}）。
     */
    boolean softDeleteByIds(Long[] ids);

    /**
     * 按 {@code subid} 软删（原 {@code deleteServiceSubtaskPreachformBySubid}）。
     */
    boolean softDeleteBySubid(Long subid);
}