package com.ruoyi.task.api.spi;

/**
 * 参数配置读取能力 —— <b>ruoyi-task 的对外 SPI，由 smartor 侧实现</b>。
 *
 * <h3>用途</h3>
 * 子任务统计里要读 {@code sys_config} 的 {@code wj.sms.template} 取值
 * （原 {@code ServiceSubtaskServiceImpl} L5141-5146）：
 * <pre>
 * SysConfig sysConfig = new SysConfig();
 * sysConfig = sysConfigMapper.checkConfigKeyUnique("wj.sms.template");
 * if (!Objects.isNull(sysConfig)) { String smsContemt = sysConfig.getConfigValue(); ... }
 * </pre>
 * {@code sys_config} 属系统域。ruoyi-task 自己的模块开关读参数走
 * {@code ruoyi-common} 的 {@code IConfigService}；但这里原本走的是
 * {@code SysConfigMapper#checkConfigKeyUnique}（返回整行），
 * 且只用到 {@code configValue} 一个字段，故收成一个<b>只返回值</b>的端口。
 *
 * <h3>⚠️ 关于"行存在但值为 null"的边界</h3>
 * 原判定是"行存在"（{@code !isNull(sysConfig)}），本端口判定是"值非 null"。
 * 二者只在 {@code sys_config} 存在一行且 {@code config_value IS NULL} 时不同 ——
 * 而 RuoYi 的 {@code sys_config.config_value} 是 {@code varchar(500) NOT NULL DEFAULT ''}，
 * <b>该情形不可能出现</b>，因此行为等价。
 * （实现方按原样调 {@code checkConfigKeyUnique} 后取 {@code getConfigValue()}。）
 *
 * <h3>⚠️ 实现必须保持"纯转发"</h3>
 */
public interface TaskSysConfigPort {

    /**
     * 按参数键名取参数值（原 {@code SysConfigMapper#checkConfigKeyUnique} + {@code getConfigValue()}）。
     *
     * @param configKey 参数键名
     * @return 参数值；该键不存在时返回 {@code null}
     */
    String findConfigValueByKey(String configKey);

    /**
     * 按参数键名取参数值（原 {@code ISysConfigService#selectConfigByKey(String)}）。
     * <p>
     * ⚠️ 与 {@link #findConfigValueByKey} <b>不是同一个东西</b>，不要合并：
     * 前者走的是 {@code SysConfigMapper#checkConfigKeyUnique}（按 key 查整行），
     * 本方法走的是 {@code ISysConfigService#selectConfigByKey}（带缓存、且支持 orgid 维度）。
     * 两者 SQL 不同，合并会改变取值来源 —— 故并列保留、各自对应原调用。
     *
     * @param configKey 参数键名
     * @return 参数值；不存在返回 {@code StringUtils.EMPTY}（与原实现一致，不是 null）
     */
    String selectConfigValue(String configKey);

    /**
     * 按参数键名 + 机构 id 取参数值（原 {@code ISysConfigService#selectConfigByKey(String, String)}）。
     * <p>
     * ⚠️ 该 2 参重载<b>只在 ruoyi-system 的 {@code ISysConfigService} 上</b>，
     * 不在 ruoyi-common 的 {@code IConfigService} 上 —— 这也是为什么不能简单地把
     * 调用方字段类型换成 {@code IConfigService} 来省掉依赖。
     *
     * @param configKey 参数键名
     * @param orgid     机构 id
     * @return 参数值；不存在返回空串
     */
    String selectConfigValue(String configKey, String orgid);
}