免增加出参名单配置 · 设计文档

2.1 建表 DDL

CREATE TABLE `agg_special_list` (
  `id`            bigint        NOT NULL AUTO_INCREMENT  COMMENT '自增主键(即规则编号)',
  `account_id`    bigint        NOT NULL                 COMMENT '客户账户标识',
  `status`        varchar(10)   NOT NULL DEFAULT '1'   COMMENT '状态:1=启用,0=停用(字典JG0000019)',
  `creator`       varchar(128)           DEFAULT NULL   COMMENT '创建人(username)',
  `created_time`  datetime                DEFAULT NULL   COMMENT '创建时间',
  `modifier`      varchar(128)  DEFAULT NULL                  COMMENT '修改人(username)',
  `modified_time` datetime      NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_account_id` (`account_id`)
) ENGINE=InnoDB COMMENT='免增加出参名单(聚合特殊名单)';

2.2 字段说明

2.3 设计说明

3.1 缓存结构

• 类型：R2MHashCache（Redis Hash，主 R2M 集群）
• Redis Key：AGG_SPECIAL_LIST（常量 R2MConstant.AGG_SPECIAL_LIST）
• Hash Field：accountId.toString()，Value："1"（仅作命中标志，无业务含义，命中 Field 即表示该账户在名单中）
• 业务语义：按 accountId 查缓存，命中则该账户出参不增加合规用固定出参

3.2 缓存加载

• 加载器：AggSpecialListCacheLoader extends AbstractCacheVersionLoader<String, String>，构造器传业务类型 VersionBusinessTypeEnum.AGG_SPECIAL_LIST.getType()
• 实现 loadAll()：全量加载 status='1'（启用）记录，按 accountId 建映射；停用记录不入缓存
• 加载时机：启动加载 + 定时任务检测版本号变化刷新

3.3 版本号

• 版本号由 BusinessVersionAspect 切面维护：对 AggSpecialList 实体的 save/update/remove/delete 操作，切面自动递增 OperationBusinessVersion 表中业务类型 aggSpecialList 的 version（version = 当前时间戳）
• getLatestGlobalVersion() 由 AbstractCacheVersionLoader 父类实现，查 OperationBusinessVersion 表取 version，子类无需覆盖
• 新增/启用/停用操作均会推高 version，定时任务检测到变化即触发全量重载

3.4 刷新机制

• 缓存刷新统一由定时任务 AggSpecialListCacheTask（EasyJob）负责：检测 OperationBusinessVersion 版本号变化，变化时触发全量重载
• 写操作（add / changeStatus）只更新数据库，不主动调缓存刷新方法；版本号递增由 BusinessVersionAspect 切面在写操作后自动完成，定时任务下一周期感知并刷新
• 刷新延迟：取决于定时任务执行周期（配置表低频写入，延迟可接受）

3.5 注册

• CacheConfig 新增 @Bean：返回 AbstractCache<String, String>，实例化 new R2MHashCache(R2MConstant.AGG_SPECIAL_LIST, aggSpecialListCacheLoader, null, r2mClusterClient, null, null, false, false)（参照现有 R2MHashCache 注册）
• R2MConstant 新增常量 AGG_SPECIAL_LIST

4.1 包结构与文件清单

实体统一放 service/aggSpecialList/dao/model/ 下，不沿用历史分包。

4.2 实体 / BO / DTO / VO / 转换

4.2 实体类 AggSpecialList

4.3 BO

4.4 DTO

4.5 VO

• AggSpecialListPageVo：见 5.1 返回字段表。creator/modifier 加 @GenerateStrField(type=TranslateType.USER, suffix="Name")，时间字段加 @JsonFormat(pattern="yyyy-MM-dd HH:mm:ss", timezone="GMT+8")
• AggSpecialListAccountInfoVo：accountId/orgNo/fullName/shortName/merchantName/accountName/status

4.6 对象转换

4.7 Service 方法

缓存刷新由定时任务 AggSpecialListCacheTask 统一负责；Service 写操作不主动刷缓存，版本号递增由 BusinessVersionAspect 切面自动完成。

5.0 接口总览

权限说明：本功能接口均为 NORMAL（走菜单按钮鉴权）。

统一返回包装 Result<T>，分页返回 Result<PageResult<T>>。

5.1 规则列表分页

5.2 新增配置

5.3 启用/停用

5.4 校验账户是否已有生效规则

5.5 按账户标识查客户信息

5.6 字段翻译约定

• creator/modifier：后端用 @GenerateStrField(type=TranslateType.USER) 注解，序列化时自动追加 creatorName/modifierName（中文名）。前端直接展示 xxxName，鼠标悬浮展示 xxx（username）。
• 时间字段：@JsonFormat(pattern="yyyy-MM-dd HH:mm:ss", timezone="GMT+8")。

6.1 分页查询

单表查询 + 关联账户/客户信息，因多表 JOIN 采用自定义 XML 分页（selectPage）。

SELECT
    t.id,
    t.account_id,
    t.status,
    t.creator,
    t.created_time,
    t.modifier,
    t.modified_time,
    obi.org_no,
    ai.account_name,
    CASE
        WHEN obi.short_name IS NOT NULL AND obi.short_name != ''
        THEN CONCAT(obi.full_name, '（', obi.short_name, '）')
        ELSE obi.full_name
    END AS merchantName
FROM agg_special_list t
LEFT JOIN account_info ai ON ai.id = t.account_id
LEFT JOIN t_crm_org_base_info obi ON obi.org_no = ai.org_no
<where>
    <if test="orgNo != null and orgNo != ''">
        AND obi.org_no LIKE CONCAT('%', #{orgNo}, '%')
    </if>
    <if test="merchantName != null and merchantName != ''">
        AND (instr(fullwidth_to_halfwidth(obi.full_name), fullwidth_to_halfwidth(#{merchantName})) != 0
          OR instr(fullwidth_to_halfwidth(obi.short_name), fullwidth_to_halfwidth(#{merchantName})) != 0)
    </if>
    <if test="accountId != null">
        AND t.account_id = #{accountId}
    </if>
    <if test="status != null and status != ''">
        AND t.status = #{status}
    </if>
</where>
ORDER BY t.modified_time DESC, t.id DESC

6.2 新增配置校验

6.3 启用/停用（changeStatus）

6.4 校验账户是否已有生效规则（checkAccount）

6.5 按账户标识查客户信息（accountInfo）

💡 用途：新增弹窗选中账户后带出客户编号、客户名称、账户名称（只读）。