BLMS 名单管理系统

一、系统概述

1.1 系统定位

BLMS（Blacklist Management Service / 名单管理系统）是微众银行（WeBank）CNC（Cross-border Network Center）平台下的一个名单管理系统。该系统主要负责黑名单查询、通用名单查询、黑名单联机上报、白名单异步新增以及名单文件批量导入等核心业务功能。

1.2 技术栈

技术要素	详情
Artifact	`cn.webank.cnc.blms:blms-parent`
Java 版本	Java 8
父 POM	`cn.webank.cnc.sdk:zcnc-sdk-starter-parent:3.22.0-SNAPSHOT`
Spring 版本	Spring 5.3.20 / Spring Boot
ORM 框架	MyBatis 3.4.2 + mybatis-spring 1.3.0
消息中间件	RMB（WeMQ）2.1.13.1
数据库	TDSQL（MySQL 兼容），使用 commons-dbcp 连接池
文件传输	FPS（File Platform Service）
Excel 处理	EasyExcel（阿里巴巴）
序列化	Jackson 2.13.4 + FastJSON 1.2.83
系统编号	Z468
SCM 地址	`git@code.weoa.com:wb-intl-suites/BLMS/blms.git`

1.3 系统编号与接口注册

配置项	值	说明
systemId	Z468	系统编号
syncServiceId	06100854	名单同步服务
syncScenario	01	同步场景
asyncServiceId	06100857	名单更改同步服务
asyncScenario	01	异步场景
listFileServiceId	06100855	名单文件处理服务
listFileScenario	01	文件场景
lmsBlackListAddServiceID	06100855	黑名单联机上报服务
lmsBlackListAddScenario	01	上报场景

二、模块结构

BLMS 采用 Maven 多模块结构，但实际仅包含一个功能子模块：

blms/
├── pom.xml                          # 父 POM（blms-parent，packaging=pom）
├── blms-service/
│   ├── pom.xml                      # 子模块 POM（blms-service）
│   └── src/
│       ├── main/
│       │   ├── java/cn/webank/cnc/blms/   # Java 源码
│       │   └── resources/                   # 配置与 MyBatis Mapper
│       └── test/                            # 单元测试
├── conf/                            # 生产环境配置
│   └── blms-service/
├── conf-local/                      # 本地开发配置
│   └── blms-service/
└── dbScript/                        # 数据库脚本
    └── 24.05.30/tdsql/adm/lmsdb/ddl/   # 历史目录命名，运行配置中的逻辑库名为 blmsdb

子模块 blms-service

Artifact: cn.webank.cnc.blms:blms-service
描述: "BLMS - Service - 名单服务"
启动类: cn.webank.cnc.blms.Application
打包方式: Spring Boot fat JAR（spring-boot-maven-plugin repackage）

SDK 依赖

SDK 组件	用途
`zcnc-sdk-starter-core`	CNC SDK 核心功能
`zcnc-sdk-starter-rmb`	RMB 消息通信
`zcnc-sdk-starter-seq`	序列号生成
`zcnc-sdk-starter-data-clean`	数据脱敏
`zcnc-sdk-starter-io`	IO/FPS 文件操作
`zcnc-sdk-starter-db`	TDSQL 数据库访问
`zcnc-sdk-starter-msgtools`	消息工具
`zcnc-sdk-starter-systemstatus`	系统状态监控

三、包架构（完整包树）

cn.webank.cnc.blms
├── Application.java                     # Spring Boot 启动类
├── annotation/
│   └── Attribute.java                   # 字段属性注解（Map-Object 映射）
├── config/
│   └── FilterConfig.java                # 过滤器配置（已注释）
├── constants/
│   └── CommonValues.java                # 公共常量定义
├── dao/
│   ├── BlkListDao.java                  # 黑名单 DAO
│   ├── CommonListDao.java               # 通用名单 DAO
│   ├── ListFileConfigDao.java           # 名单文件配置 DAO
│   ├── ListFileFlowDao.java             # 名单文件流水 DAO
│   ├── OnlineAddFlowDao.java            # 联机新增流水 DAO
│   └── WhiteListDao.java                # 白名单 DAO
├── enums/
│   ├── ListFileStatus.java              # 文件状态枚举
│   ├── LogKeyWordEnum.java              # 日志关键字枚举
│   ├── RspCodeEnum.java                 # 响应码枚举
│   └── ServiceCodeEnum.java             # 服务编码枚举
├── listener/
│   ├── BlkListListener.java             # Excel 黑名单读取校验监听器
│   └── BlkListWriteListener.java        # Excel 黑名单批量写入监听器
├── model/
│   ├── BlkList.java                     # 黑名单实体
│   ├── CommonList.java                  # 通用名单实体
│   ├── ListFileConfig.java              # 名单文件配置实体
│   ├── ListFileFlow.java                # 名单文件流水实体
│   ├── WhiteListDTO.java                # 白名单 DTO
│   └── exceptions/
│       ├── JsonReSerializeException.java  # JSON 反序列化异常
│       ├── JsonSerializeException.java    # JSON 序列化异常
│       └── ServiceNotExistException.java  # 服务不存在异常
├── service/
│   ├── AsyncService.java                # 异步服务接口
│   ├── MsgEnhancer.java                 # 消息增强器接口
│   ├── ServiceHandler.java              # 服务处理器接口
│   ├── ServiceHandlerHolder.java        # 服务处理器持有者
│   ├── SyncService.java                 # 同步服务接口
│   ├── common/
│   │   └── AbstractBaseService.java     # 基础服务抽象类
│   ├── impl/
│   │   ├── AsyncRouteService.java       # 异步路由服务
│   │   └── ListFileHelper.java          # 名单文件处理辅助类
│   ├── impl/api/
│   │   ├── AsyncServiceA0001.java       # 异步白名单新增服务
│   │   ├── FileServiceS0004.java        # 文件导入服务
│   │   ├── SyncServiceS0001.java        # 同步通用名单查询服务
│   │   ├── SyncServiceS0002.java        # 同步黑名单查询服务
│   │   └── SyncServiceS0003.java        # 同步黑名单联机上报服务
│   ├── impl/enhancer/
│   │   └── ListTypeEnhancer.java        # 名单类型增强器
│   ├── rmb/
│   │   └── MyRmbService.java            # RMB 消息入口服务
│   └── rmbhandler/
│       └── SyncListHandler.java         # 同步名单消息处理器
└── util/
    ├── BeanUtil.java                    # Spring Bean 工具
    ├── DateUtil.java                    # 日期工具
    ├── EnvironmentFactoryBean.java      # 环境配置工厂
    ├── ExcelUtils.java                  # Excel 工具（基于 EasyExcel）
    ├── FpsAgent.java                    # FPS 文件代理（旧版）
    ├── FpsFileExchange.java             # FPS 文件交换（新版）
    ├── LogUtil.java                     # 日志工具
    ├── MapUtil.java                     # Map 工具（含参数校验）
    ├── MyTradeLogUtil.java              # 交易日志工具
    ├── ParamCheckUtil.java              # 参数校验工具
    ├── RmbUtil.java                     # RMB 消息工具
    └── ThreadContext.java               # 线程上下文

四、核心类详解

4.1 Application — 启动类

文件: cn.webank.cnc.blms.Application
功能: Spring Boot 应用入口
注解:
- @SpringBootApplication：扫描 cn.webank.blms.** 和 cn.webank.cnc.blms.**
- @EnableTransactionManagement：启用事务管理
- @EnableConfigurationProperties：启用配置属性绑定
- @EnableAspectJAutoProxy：启用 AOP 代理
作者: sihangwang, 2024/5/13

4.2 annotation/Attribute — 属性注解

文件: cn.webank.cnc.blms.annotation.Attribute
功能: 标注在字段上，用于将 Java 对象字段与数据库列名建立映射关系
使用场景: MapUtil.toMap() 方法利用此注解将实体对象转换为 Map<String, Object>，实现对象到 Map 的属性映射
示例: @Attribute("PRODUCT_CD") 标注在 productCd 字段上

4.3 config/FilterConfig — 过滤器配置

文件: cn.webank.cnc.blms.config.FilterConfig
状态: 已注释（@Configuration 被注释掉），当前未生效
功能: 配置过滤器加载顺序，确保在 SeqAutoConfiguration 之前、TdsqlAutoConfiguration 之后加载

4.4 constants/CommonValues — 公共常量

文件: cn.webank.cnc.blms.constants.CommonValues
功能: 定义系统全局使用的常量字符串
关键常量:
- 上下文键：CTX_KEY_SERVICE_CODE, CTX_KEY_BIZ_NO, CTX_KEY_FROM_SYSTEM_ID, CTX_KEY_TTL
- 参数键：PARAM_F_BLKLIST, PARAM_F_GREYLIST, PARAM_F_WHITELIST, PARAM_F_MOBILE, PARAM_F_NAME 等
- 名单类型：LIST_TYPE
- 结果码：KDQS_SUCCESS_CODE（60800000）、KDQS_NO_DATA_CODE（60800002）
- 通用描述：DESC_SUCCESS（成功）、DESC_FAIL（失败）

4.5 dao 层 — 数据访问对象

4.5.1 BlkListDao — 黑名单 DAO

文件: cn.webank.cnc.blms.dao.BlkListDao
对应表: TM_BLK_LIST
方法:
- selectOneBlkList(productCd, type, value): 根据产品号、类型、值查询单条黑名单，条件包含 OPERATED_SIGN!='0'（未删除）且 EXPIRED_DATE>=当前日期（未过期）
- insertOrUpdateBlkList(List<BlkList>): 批量插入或更新黑名单，使用 ON DUPLICATE KEY UPDATE 语法

4.5.2 CommonListDao — 通用名单 DAO

文件: cn.webank.cnc.blms.dao.CommonListDao
对应表: TM_COMMON_LIST
方法:
- selectOneCommonList(productCd, listType, appType, appAcctNo): 根据产品号、名单类型、账号类型、账号值查询单条通用名单

4.5.3 ListFileConfigDao — 名单文件配置 DAO

文件: cn.webank.cnc.blms.dao.ListFileConfigDao
对应表: TM_LIST_FILE_CONFIG
方法:
- selectListFileConfig(fileType): 根据文件类型查询文件配置

4.5.4 ListFileFlowDao — 名单文件流水 DAO

文件: cn.webank.cnc.blms.dao.ListFileFlowDao
对应表: TM_LIST_FILE_FLOW
方法:
- insertListFileFlow(fileFlow): 插入文件操作流水，使用 ON DUPLICATE KEY UPDATE
- updateListFileFlowStatus(fileFlow): 更新文件处理状态（支持更新审批人、差错文件信息）
- selectListFileFlow(fileId): 根据文件 ID 查询文件流水

4.5.5 OnlineAddFlowDao — 联机新增流水 DAO

文件: cn.webank.cnc.blms.dao.OnlineAddFlowDao
对应表: TM_ONLINE_ADD_REC
方法:
- insert(record): 插入联机新增流水记录，包含 BIZ_NO、CONTENT、STATUS 字段

4.5.6 WhiteListDao — 白名单 DAO

文件: cn.webank.cnc.blms.dao.WhiteListDao
对应表: TM_WHITE_LIST
方法:
- addOrUpdateAsKey(map): 以主键进行 INSERT/UPDATE 操作（UPSERT），更新操作标志、手机号等

4.6 enums 层 — 枚举定义

4.6.1 ListFileStatus — 文件处理状态

文件: cn.webank.cnc.blms.enums.ListFileStatus

状态流转:

UNAUDITED → AUDITED → PRE_CHECKING → PRE_CHECKED_SUC → PUSHED → CHECKED_SUC → LOAD_SUC
                     → REFUSED                    → PRE_CHECKED_FAIL
                                                   → PUSH_FAILED
                                                               → CHECKED_FAIL
                                                                            → LOAD_FAIL
INNER_FAIL（内部异常）

说明:
- UNAUDITED: 未审核，LMS 收到 BDP 加载通知但业务尚未确认
- AUDITED: 已审核，业务确认可推送
- REFUSED: 已拒绝
- PRE_CHECKING: 预检查中
- PUSHED: 已推送给 BDP 处理
- LOAD_SUC: 大数据加工处理成功

4.6.2 LogKeyWordEnum — 日志关键字

文件: cn.webank.cnc.blms.enums.LogKeyWordEnum
枚举值:
- INT_INIT（INT-INIT）：启动-初始化错误
- TXN_PARAM（TNX-PARAM）：交易-参数错误
- TXN_CONF（TNX-CONF）：交易-配置错误
- TXN_BIZ_LOGIC（TNX-BIZ_LOGIC）：交易-业务逻辑错误
- TXN_SYS（TNX-SYS）：交易-系统错误

4.6.3 RspCodeEnum — 响应码枚举

文件: cn.webank.cnc.blms.enums.RspCodeEnum
枚举值:

枚举	编码	描述
`SUCCESS`	Z468S00000000	成功
`SYSTEM_EXCEPTION`	Z468S00000001	系统异常
`PARAM_BAD`	Z468S00000002	参数无效/不合法
`NO_DATA_FOUND`	Z468S00000003	查无数据
`UNKNOWN_EXCEPTION`	Z468T00009999	未知异常
`DOWNSTREAM_TIMEOUT`	Z4686T00000006	下游超时

4.6.4 ServiceCodeEnum — 服务编码枚举

文件: cn.webank.cnc.blms.enums.ServiceCodeEnum
映射关系:

编码	服务Bean名称	说明
S001	SyncServiceS0001	通用名单查询
S002	SyncServiceS0002	黑名单查询
S003	SyncServiceS0003	黑名单联机上报

扩展机制: 通过 registerService(code, beanName) 支持运行时动态注册服务

4.7 listener 层 — EasyExcel 监听器

4.7.1 BlkListListener — 黑名单读取校验监听器

文件: cn.webank.cnc.blms.listener.BlkListListener
功能: 实现 EasyExcel 的 ReadListener<BlkList> 接口，逐行读取 Excel 并校验数据
校验规则:
- productCd: 非空且长度 1-6
- type: 必须为 inDev 或 inId
- value: 非空且长度 1-100
- reason: 非空且长度 1-1024
- source: 非空且长度 1-30
- operatedSign: 必须为 0 或 1
错误处理: 校验失败的数据写入 BufferedWriter（错误文件）

4.7.2 BlkListWriteListener — 黑名单批量写入监听器

文件: cn.webank.cnc.blms.listener.BlkListWriteListener
功能: 实现 EasyExcel 的 ReadListener<BlkList> 接口，批量将 Excel 数据写入数据库
批处理: 每 100 条批量执行一次 blkListDao.insertOrUpdateBlkList()
依赖: BlkListDao

4.8 model 层 — 数据模型

4.8.1 BlkList — 黑名单实体

文件: cn.webank.cnc.blms.model.BlkList
对应表: TM_BLK_LIST
字段:

字段	数据库列	类型	说明
productCd	PRODUCT_CD	String	产品号
type	TYPE	String	黑名单类型（inDev/inId）
value	VALUE	String	黑名单值
dayOfBirth	DOB	Date	出生日期
name	NAME	String	姓名
alias	ALIAS	String	别名
telephoneNo	TELEPHONE_NO	String	电话号码
reason	REASON	String	入黑原因
source	SRC	String	入黑来源
expiredDate	EXPIRED_DATE	Date	到期日期
operatedSign	OPERATED_SIGN	String	操作标志（0-删除，1-新增/修改）
updatedOpr	UPDATED_OPR	String	更新操作人
lastModifiedDatetime	LAST_MODIFIED_DATETIME	String	最后修改时间

4.8.2 CommonList — 通用名单实体

文件: cn.webank.cnc.blms.model.CommonList
对应表: TM_COMMON_LIST
使用 Lombok: @Data 注解自动生成 getter/setter
字段: productCd, listType, listValue, appType, operatedSign, reservedObligate1~10, createdOpr, updatedOpr, createdDatetime, lastModifiedDatetime
支持的名单类型: RPI_BC_BL（断卡来账黑名单）、RPI_FP_BL（止付冻结失败拦截黑名单）、RPP_BL（来账人工黑名单）

4.8.3 ListFileConfig — 名单文件配置

文件: cn.webank.cnc.blms.model.ListFileConfig
对应表: TM_LIST_FILE_CONFIG
字段: fileType, mustAudited, doPreCheck, taskGroupId, tspServiceId, tspScenarioId, msgEnhancer
说明: 配置不同文件类型的处理策略，包括是否需要审核、是否预检查、关联的任务组及 TSP 服务信息

4.8.4 ListFileFlow — 名单文件流水

文件: cn.webank.cnc.blms.model.ListFileFlow
对应表: TM_LIST_FILE_FLOW
字段: fileId, hashValues, fileType, fileCount, bizNo, batchNo, checkDatetime, checkUser, smFileId, smHashValues, smPath, errFileId, errHashValues, status

4.8.5 WhiteListDTO — 白名单 DTO

文件: cn.webank.cnc.blms.model.WhiteListDTO
对应表: TM_WHITE_LIST
字段: productCd, idNo, idType, name, phone, operateSign, createdOpr, updatedOpr, createdDatetime, lastModifiedDatetime

4.9 service 层 — 业务逻辑

4.9.1 ServiceHandler — 服务处理器接口

文件: cn.webank.cnc.blms.service.ServiceHandler
功能: 定义同步服务的统一处理入口
方法:
- default Message handle(Message reqMsg, Map paramMap): 默认处理逻辑 — 构建 context，调用 handle(paramMap, context)，封装 RMB 响应消息
- Map handle(Map reqMap, Map serviceCtx): 业务处理方法（子类实现）

4.9.2 ServiceHandlerHolder — 服务处理器持有者

文件: cn.webank.cnc.blms.service.ServiceHandlerHolder
注解: @Service
功能: 根据 serviceCode 查找并返回对应的 ServiceHandler Bean
依赖: ApplicationContext
查找逻辑: 通过 ServiceCodeEnum.getServiceNameByCode(code) 获取 Bean 名称，再从 Spring 容器获取 Bean 实例

4.9.3 SyncService — 同步服务接口

文件: cn.webank.cnc.blms.service.SyncService
方法: Map<String, Object> doService(Map<String, Object> reqMap)

4.9.4 AsyncService — 异步服务接口

文件: cn.webank.cnc.blms.service.AsyncService
方法: void doService(Map<String, Object> reqMap)

4.9.5 MsgEnhancer — 消息增强器接口

文件: cn.webank.cnc.blms.service.MsgEnhancer
功能: 消息补充钩子接口，用于在文件处理流程中对消息进行增强
方法: boolean enhance(Map srcReqMap, Map transReqMap)

4.9.6 AbstractBaseService — 基础服务抽象类

文件: cn.webank.cnc.blms.service.common.AbstractBaseService
功能: 所有同步服务的基类，实现 ServiceHandler 接口
模板方法模式:
- handle() 调用 checkParam() → doService() → postProcess()
- 参数校验失败直接返回 PARAM_BAD
核心方法:
- checkParam(reqMap): 抽象方法，子类实现参数校验逻辑，返回 "S" 表示通过
- doService(reqMap, serviceCtx): 抽象方法，子类实现业务逻辑
- postProcess(result): 后置处理，将 DOWNSTREAM_TIMEOUT 替换为 SYSTEM_EXCEPTION（兼容性处理）
- buildRspMap(code): 构建响应 Map（含 code/desc）
- removeIfNotIn(), removeIfIn(), removeIf(): Map 过滤工具方法

4.10 service/impl 层 — 服务实现

4.10.1 AsyncRouteService — 异步路由服务

文件: cn.webank.cnc.blms.service.impl.AsyncRouteService
注解: @Component("asyncRouteService")
功能: 异步消息路由器，根据 SERVICE_CODE 拼接 Bean 名称（如 AsyncServiceA0001），查找对应的 AsyncService Bean 并委托执行
异常处理: 找不到服务时抛出 ServiceNotExistException

4.10.2 ListFileHelper — 名单文件处理辅助类

文件: cn.webank.cnc.blms.service.impl.ListFileHelper
注解: @Service
功能: 封装名单文件处理流程中的公共操作
核心方法:
- shouldAck(fileType): 判断文件类型是否需要审核确认
- getListFileConfig(fileType): 获取文件类型配置
- getListFileFlow(fileId): 获取文件操作流水
- updateFlowStatus(fileId, status): 更新文件状态
- makeAndInsertListFileFlow(bizNo, status, reqMap): 创建并插入文件操作流水
- makeTransBaseReqMap(reqMap, flow, config): 构建转换后的请求 Map，调用 MsgEnhancer 进行消息增强
- getEnhancer(enhancerName): 获取消息增强器实例，无配置时使用空实现

4.11 service/impl/api 层 — API 服务实现

4.11.1 SyncServiceS0001 — 通用名单查询

文件: cn.webank.cnc.blms.service.impl.api.SyncServiceS0001
注解: @Component("SyncServiceS0001")
服务编码: S001
功能: 根据请求中的 commonList 批量查询通用名单
参数校验:
- commonList 列表非空且不超过 10 条
- 每条记录：productCd（1-6位，可选），listType（必须为 RPI_BC_BL/RPI_FP_BL/RPP_BL），appAcctNo（1-100位，必填），appType（1-2位，必填）
业务逻辑: 遍历请求列表，逐条调用 commonListDao.selectOneCommonList() 查询，匹配的记录加入结果列表
响应: 无匹配返回 NO_DATA_FOUND，有匹配返回 SUCCESS + commonList

4.11.2 SyncServiceS0002 — 黑名单查询

文件: cn.webank.cnc.blms.service.impl.api.SyncServiceS0002
注解: @Component("SyncServiceS0002")
服务编码: S002
功能: 根据产品号和黑名单列表批量查询黑名单匹配结果
参数校验:
- productCd 必填（1-6位）
- blkList 非空且不超过 10 条
- 每条记录：blkType（必须为 inDev/inId），blkValue（1-100位）
业务逻辑: 遍历请求列表，逐条调用 blkListDao.selectOneBlkList() 查询
响应: 每条记录返回 matched=Y/N，匹配时额外返回 blkReason

4.11.3 SyncServiceS0003 — 黑名单联机上报

文件: cn.webank.cnc.blms.service.impl.api.SyncServiceS0003
注解: @Component("SyncServiceS0003")
服务编码: S003
功能: 联机新增/更新黑名单记录
参数校验:
- blkList 非空且不超过 10 条
- 每条记录：productCd（1-6位），blkType（inDev/inId），blkValue（1-100位）
业务逻辑:
1. 构造 BlkList 实体列表（设置 operatedSign="1"，expiredDate 默认 100 年后）
2. 调用 blkListDao.insertOrUpdateBlkList() 批量入库
3. 记录联机新增流水到 TM_ONLINE_ADD_REC（CONTENT 超过 1024 字符则截断）
依赖: BlkListDao, OnlineAddFlowDao

4.11.4 AsyncServiceA0001 — 白名单异步新增

文件: cn.webank.cnc.blms.service.impl.api.AsyncServiceA0001
注解: @Component("AsyncServiceA0001")
功能: 异步接收白名单数据并写入数据库
业务逻辑:
1. 从请求中提取 PRODUCT_CD, ID_TYPE, ID_NO, NAME, MOBILE
2. 参数校验：productCd, idType, idNo, name 不允许为空
3. 调用 whiteListDao.addOrUpdateAsKey() 执行 UPSERT
4. 记录联机新增流水
依赖: OnlineAddFlowDao, WhiteListDao

4.11.5 FileServiceS0004 — 名单文件导入

文件: cn.webank.cnc.blms.service.impl.api.FileServiceS0004
注解: @Component("FileServiceS0004")
功能: 通过 FPS 下载名单文件并导入数据库
参数校验:
- hashValues 非空，首元素长度 1-40
- fileType 必须为 BLK/RPI_BC_BL/RPI_FP_BL/RPP_BL
- fileId（1-70位），lastUpdateOpr（1-20位）
业务逻辑:
1. 通过 fpsFileExchange.getFile() 从 FPS 下载文件
2. 若 fileType=BLK：先用 ExcelUtils.checkBlkList() 校验，再用 ExcelUtils.importBlkList() 导入
3. 其他类型（RPI_BC_BL 等）：当前代码已注释
依赖: BlkListDao, FpsFileExchange

4.12 service/impl/enhancer — 消息增强器

ListTypeEnhancer — 名单类型增强器

文件: cn.webank.cnc.blms.service.impl.enhancer.ListTypeEnhancer
注解: @Service("listTypeEnhancer")
功能: 根据 fileType 和 fileName 推断名单类型
逻辑:
- 当 fileType=NY_BLK_LIST 时：
  - fileName 以 EX_BLK 开头 → listType=EX_BLK（外部黑名单）
  - fileName 以 IN_BLK 开头 → listType=IN_BLK（内部黑名单）

4.13 service/rmb — RMB 消息入口

MyRmbService — RMB 服务入口

文件: cn.webank.cnc.blms.service.rmb.MyRmbService
注解: @Service
功能: RMB 消息接收入口，通过 @RmbMap 注解将方法绑定到 RMB 服务
注册的两个 RMB 接口:

方法	服务ID	场景ID	说明
`syncListHandler`	syncServiceId (06100854)	syncScenario (01)	名单同步查询
`blackListAddHandler`	lmsBlackListAddServiceID (06100855)	lmsBlackListAddScenario (01)	黑名单联机上报

排除的拦截器: MessageAnalyseInterceptor、TradeLogInterceptor

4.14 service/rmbhandler — RMB 消息处理器

SyncListHandler — 同步名单处理器

文件: cn.webank.cnc.blms.service.rmbhandler.SyncListHandler
注解: @Component
继承: cn.webank.rmb.api.RequestHandler
功能: 处理所有同步 RMB 消息的入口处理器
处理流程:
1. 记录日志上下文（bizSeqNo, consumerSeqNo, serviceId-scenario）
2. 解析消息体为 Map<String, Object>
3. 设置 ThreadContext（bizSeqNo, consumerId, orgSysid, consumerSeqNo）
4. 根据 serviceCode 查找 ServiceHandler
5. 委托 ServiceHandler 处理请求并返回响应
6. 记录交易日志（MyTradeLogUtil.traceSyncIn）
7. 异常处理：返回错误消息

4.15 util 层 — 工具类

BeanUtil — Spring Bean 工具

文件: cn.webank.cnc.blms.util.BeanUtil
功能: 实现 ApplicationContextAware，提供静态方法从 Spring 容器获取 Bean
方法: getBean(name, clazz)

DateUtil — 日期工具

文件: cn.webank.cnc.blms.util.DateUtil
功能: 日期格式化与解析工具
特性:
- 使用 ThreadLocal 缓存 SimpleDateFormat 实例（线程安全）
- 使用 ThreadLocal 缓存 GregorianCalendar 实例
- 支持日期校验（checkFormat）、日期跳转（jumpDate）

EnvironmentFactoryBean — 环境配置工厂

文件: cn.webank.cnc.blms.util.EnvironmentFactoryBean
功能: Spring FactoryBean，从环境变量或属性文件加载配置
优先级: 环境变量 > moduleConfigLocations 配置文件 > System Properties

ExcelUtils — Excel 工具

文件: cn.webank.cnc.blms.util.ExcelUtils
功能: 基于 EasyExcel 的 Excel 文件处理
方法:
- checkBlkList(file, errFile): 校验 Excel 中的黑名单数据，使用 BlkListListener 逐行验证
- importBlkList(file, blkListDao): 导入 Excel 中的黑名单数据，使用 BlkListWriteListener 批量写入
文件格式: XLSX

FpsAgent — FPS 文件代理（旧版）

文件: cn.webank.cnc.blms.util.FpsAgent
注解: @Component("fpsAgent"), @Scope("singleton")
功能: 通过 FPS Client 进行文件上传和下载
方法:
- upload(fileName): 上传文件到 FPS，返回 FileHashInfo
- download(fileId, hashValues, path): 从 FPS 下载文件
依赖: FpsClientUtil, RsautilManager（密码解密）
注意: 此为旧版实现，新版使用 FpsFileExchange

FpsFileExchange — FPS 文件交换（新版）

文件: cn.webank.cnc.blms.util.FpsFileExchange
注解: @Component
功能: 新版 FPS 文件下载工具，实现 InitializingBean 在启动时创建工作目录
方法:
- getFile(fileId, hashValues): 从 FPS 下载文件到本地工作目录
- 文件命名格式：{workDir}/{yyyyMMdd}/RMS_LIST_{yyyyMMddHHmmss}.xlsx
依赖: FpsClientUtil

LogUtil — 日志工具

文件: cn.webank.cnc.blms.util.LogUtil
功能: 封装 CNC SDK 的 GeneralLogUtil，提供统一的日志接口
方法: setContextLogHeader, debug, info, warn, error

MapUtil — Map 工具

文件: cn.webank.cnc.blms.util.MapUtil
功能: Map 操作工具类，提供对象映射和参数校验
核心方法:
- copyEntry(from, to, keys): 复制指定 key 的条目
- toObject(m, clazz): Map 转对象（基于 @Attribute 注解映射）
- toMap(o): 对象转 Map（基于 @Attribute 注解映射）
- check(param, conditions): 参数校验（支持 REQUIRED/OPTIONAL + 长度/枚举/日期/正则）
- Conditions: 流式构造校验条件

MyTradeLogUtil — 交易日志工具

文件: cn.webank.cnc.blms.util.MyTradeLogUtil
功能: 封装交易日志记录，支持同步/异步、入/出方向的日志追踪
关键特性:
- 定义了多个默认响应码常量
- 维护了 interfaceDescMap 接口描述映射表（约 20+ 个接口）
- trace(): 统一记录交易日志
- traceMultInterface(): 支持多接口组合查询的日志记录
- mapToRetType(): 将业务响应码映射为交易日志返回类型（SUCCESS/BUSINESS_FAIL/SYSTEM_FAIL）

ParamCheckUtil — 参数校验工具

文件: cn.webank.cnc.blms.util.ParamCheckUtil
功能: 接口入参检查工具类（与 MapUtil 类似但增加了 LIST 类型检查）
支持的检查类型: OPTIONAL, OPTIONAL_IN, OPTIONAL_REGEX, REQUIRED, REQUIRED_IN, REQUIRED_REGEX, REQUIRED_LIST, OPTIONAL_LIST
返回值: "S" 表示校验通过，否则返回错误信息字符串

RmbUtil — RMB 消息工具

文件: cn.webank.cnc.blms.util.RmbUtil
功能: RMB 消息构建与发送工具
常量: MY_SYSTEM_ID = "Z468"
方法:
- getSimpleErrorMessage(message, retCode, retMsg): 构建错误响应消息
- getSimpleSuccessMessage(message, content): 构建成功响应消息
- getErrorMessage(message, content): 构建含 Map 内容的错误消息
- syncRawSend(...): 原始字符串同步调用（返回 String）
- syncSend(...): Map 类型同步调用（返回 Map）
- syncSendAndLogInfo(...): 同步调用（日志级别 INFO）
- syncSendAndLogDebug(...): 同步调用（日志级别 DEBUG）

ThreadContext — 线程上下文

文件: cn.webank.cnc.blms.util.ThreadContext
功能: 基于 ThreadLocal 的线程上下文，存储请求级别的上下文信息
字段: bizSeqNo, selfDcn, serviceCode, orgSysid, consumerId, consumerSeqNo

五、数据模型

5.1 数据库表结构

TM_BLK_LIST — 黑名单表

列名	类型	说明
PRODUCT_CD	varchar(6)	产品号（PK）
TYPE	varchar(20)	黑名单类型（PK），inDev=设备/inId=证件
VALUE	varchar(100)	黑名单值（PK）
RAW_VALUE	varchar(404)	原始值
DOB	date	出生日期
NAME	varchar(100)	姓名
ALIAS	varchar(1024)	别名
TELEPHONE_NO	varchar(30)	电话号码
REASON	varchar(1024)	入黑原因
SRC	varchar(30)	入黑来源
EXPIRED_DATE	date	到期日期
OPERATED_SIGN	varchar(2)	操作标志（0-删除，1-新增/修改）
UPDATED_OPR	varchar(100)	更新人
LAST_MODIFIED_DATETIME	timestamp	最后修改时间

主键: (VALUE, TYPE, PRODUCT_CD)
索引: IDX_LAST_MODIFIED_DATETIME

TM_COMMON_LIST — 通用名单表

列名	类型	说明
PRODUCT_CD	varchar(6)	产品号（PK）
LIST_TYPE	varchar(20)	名单类型（PK）
APP_TYPE	varchar(2)	账号类型（PK）
LIST_VALUE	varchar(100)	名单值（PK）
OPERATED_SIGN	varchar(2)	操作标志
RESERVED_OBLIGATE1~10	varchar(40)	预留扩展字段
CREATED_OPR	varchar(20)	创建人
UPDATED_OPR	varchar(20)	更新人
CREATED_DATETIME	varchar(24)	创建时间
LAST_MODIFIED_DATETIME	varchar(24)	最后修改时间

主键: (LIST_VALUE, LIST_TYPE, PRODUCT_CD)
支持的名单类型: RPI_BC_BL（断卡来账黑名单）、RPI_FP_BL（止付冻结失败拦截黑名单）、RPP_BL（来账人工黑名单）

TM_LIST_FILE_CONFIG — 名单文件配置表

列名	类型	说明
FILE_TYPE	varchar(20)	文件类型（PK）
MUST_AUDITED	varchar(2)	是否必须审核（Y/N）
DO_PRE_CHECK	varchar(2)	是否预检查
TASK_GROUP_ID	varchar	任务组 ID
TSP_SERVICE_ID	varchar	TSP 服务 ID
TSP_SCENARIO_ID	varchar	TSP 场景 ID
MSG_ENHANCER	varchar	消息增强器 Bean 名称

TM_LIST_FILE_FLOW — 名单文件操作流水表

列名	类型	说明
FILE_ID	varchar(70)	文件 ID（PK）
FILE_TYPE	varchar(20)	文件类型
HASH_VALUES	varchar(40)	文件哈希值
FILE_COUNT	varchar(20)	文件行数
BIZ_NO	varchar(40)	业务流水号
BATCH_NO	varchar(14)	批次号
STATUS	varchar(20)	处理状态
CHECK_DATETIME	timestamp	审批时间
CHECK_USER	varchar(20)	审批人
SM_FILE_ID	varchar(70)	摘要文件 ID
SM_HASH_VALUES	varchar(40)	摘要文件哈希
SM_PATH	varchar(255)	摘要文件路径
ERR_FILE_ID	varchar(70)	差错文件 ID
ERR_HASH_VALUES	varchar(40)	差错文件哈希
CREATED_DATETIME	timestamp	创建时间
LAST_MODIFIED_DATETIME	timestamp	修改时间

TM_ONLINE_ADD_REC — 联机新增流水记录表

列名	类型	说明
BIZ_NO	varchar(40)	业务流水号（PK）
CONTENT	varchar(1024)	请求内容（JSON）
STATUS	varchar(40)	执行结果（0-成功，1-失败）
LAST_MODIFIED_DATETIME	timestamp	修改时间

TM_WHITE_LIST — 白名单表

列名	类型	说明
PRODUCT_CD	varchar	产品号
ID_TYPE	varchar	证件类型
ID_NO	varchar	证件号码
NAME	varchar	姓名
PHONE	varchar	手机号
OPERATE_SIGN	varchar	操作标志
CREATED_OPR	varchar	创建人
UPDATED_OPR	varchar	更新人
CREATED_DATETIME	timestamp	创建时间
LAST_MODIFIED_DATETIME	timestamp	修改时间

TM_SEC_SEQ — 序列号表

列名	类型	说明
TABLE_NAME	varchar(20)	序列号名（PK）
SEQ_VAL	bigint(20)	当前值

5.2 MyBatis Mapper 文件清单

Mapper 文件	命名空间	说明
`BlkListDao.map.xml`	`cn.webank.cnc.blms.dao.BlkListDao`	黑名单 CRUD
`CommonListDao.map.xml`	`cn.webank.cnc.blms.dao.CommonListDao`	通用名单 CRUD
`ListFileConfigMapper.map.xml`	`cn.webank.cnc.blms.dao.ListFileConfigDao`	文件配置查询
`ListFileFlowMapper.map.xml`	`cn.webank.cnc.blms.dao.ListFileFlowDao`	文件流水 CRUD
`OnlineAddFlowDao.map.xml`	`cn.webank.cnc.blms.dao.OnlineAddFlowDao`	联机新增流水插入
`WhiteListDao.map.xml`	`cn.webank.cnc.blms.dao.WhiteListDao`	白名单 UPSERT
`SeqNo.map.xml`	`seq22`	序列号管理

六、Service 层

6.1 接口定义

接口	方法	说明
`SyncService`	`Map<String,Object> doService(Map<String,Object> reqMap)`	同步服务接口
`AsyncService`	`void doService(Map<String,Object> reqMap)`	异步服务接口
`ServiceHandler`	`Message handle(Message, Map)` / `Map handle(Map, Map)`	服务处理器接口
`MsgEnhancer`	`boolean enhance(Map srcReqMap, Map transReqMap)`	消息增强钩子接口

6.2 基类 AbstractBaseService

采用模板方法模式，定义了统一的服务处理流程：

handle(reqMap)
  ├── 1. checkParam(reqMap)         // 参数校验
  │     └── 失败 → 返回 PARAM_BAD
  ├── 2. doService(reqMap, ctx)     // 业务处理（子类实现）
  └── 3. postProcess(result)        // 后置处理
        └── DOWNSTREAM_TIMEOUT → SYSTEM_EXCEPTION（兼容替换）

6.3 API 实现一览

Bean 名称	服务编码	功能	类型
`SyncServiceS0001`	S001	通用名单查询	同步
`SyncServiceS0002`	S002	黑名单查询	同步
`SyncServiceS0003`	S003	黑名单联机上报	同步
`FileServiceS0004`	—	名单文件导入	同步
`AsyncServiceA0001`	A0001	白名单异步新增	异步

6.4 Enhancer 模式

系统通过 MsgEnhancer 接口实现了可插拔的消息增强机制：

ListFileEnhancer（listTypeEnhancer）：根据文件名前缀推断名单子类型（EX_BLK/IN_BLK）
空实现（EmptyEnhancer）：无配置时使用，直接返回 true
扩展方式：实现 MsgEnhancer 接口并注册为 Spring Bean，在 TM_LIST_FILE_CONFIG 表的 MSG_ENHANCER 列配置 Bean 名称

6.5 服务路由机制

同步路由:

RMB消息 → MyRmbService.@RmbMap → SyncListHandler.handle()
  → 解析 serviceCode → ServiceHandlerHolder.getServiceHandler(code)
  → ServiceHandler.handle(message, paramMap) → AbstractBaseService.handle()

异步路由:

RMB消息 → AsyncRouteService.doService()
  → 解析 SERVICE_CODE → BeanUtil.getBean("AsyncService" + code)
  → AsyncService.doService(reqMap)

七、RMB 消息处理

7.1 消息入口

所有 RMB 消息通过 MyRmbService 接收，该类注册了两个 @RmbMap 方法：

方法	服务ID	场景	用途
`syncListHandler`	06100854	01	名单同步查询（S001/S002/S003 均通过此入口）
`blackListAddHandler`	06100855	01	黑名单联机上报（S003）

7.2 SyncServiceS0001 — 通用名单查询

服务编码: S001
Bean: SyncServiceS0001
请求格式:

json

{
  "serviceCode": "S001",
  "commonList": [
    {
      "productCd": "xxx",
      "listType": "RPI_BC_BL",
      "appType": "01",
      "appAcctNo": "account_value"
    }
  ]
}

响应格式:

json

{
  "code": "Z468S00000000",
  "desc": "success",
  "commonList": [...]
}

7.3 SyncServiceS0002 — 黑名单查询

服务编码: S002
Bean: SyncServiceS0002
请求格式:

json

{
  "serviceCode": "S002",
  "productCd": "xxx",
  "blkList": [
    {
      "blkType": "inDev",
      "blkValue": "device_id"
    }
  ]
}

响应格式:

json

{
  "code": "Z468S00000000",
  "desc": "success",
  "blkList": [
    {
      "matched": "Y",
      "blkType": "inDev",
      "blkValue": "device_id",
      "blkReason": "reason_text"
    }
  ]
}

查询条件: 自动过滤已删除记录（OPERATED_SIGN!='0'）和已过期记录（EXPIRED_DATE>=当前日期）

7.4 SyncServiceS0003 — 黑名单联机上报

服务编码: S003
Bean: SyncServiceS0003
请求格式:

json

{
  "serviceCode": "S003",
  "blkList": [
    {
      "productCd": "xxx",
      "blkType": "inDev",
      "blkValue": "value",
      "birthDate": "2024/01/01",
      "blkName": "name",
      "blkAlias": "alias",
      "blkPhoneNo": "phone",
      "blkReason": "reason",
      "blkSource": "source",
      "blkExpiredDate": "2124/01/01",
      "blkUpdatedOpr": "operator"
    }
  ]
}

特殊逻辑:
- operatedSign 固定为 "1"（新增）
- expiredDate 默认为当前时间 +100 年
- 请求内容记录到 TM_ONLINE_ADD_REC（超过 1024 字符截断）

7.5 AsyncServiceA0001 — 白名单异步新增

服务编码: A0001
Bean: AsyncServiceA0001
请求格式:

json

{
  "PRODUCT_CD": "xxx",
  "ID_TYPE": "01",
  "ID_NO": "id_number",
  "NAME": "name",
  "MOBILE": "phone_number"
}

处理逻辑: UPSERT 到 TM_WHITE_LIST 表

7.6 FileServiceS0004 — 名单文件导入

Bean: FileServiceS0004
请求格式:

json

{
  "serviceCode": "S004",
  "fileType": "BLK",
  "fileId": "fps_file_id",
  "hashValues": ["hash_value"],
  "lastUpdateOpr": "operator"
}

处理流程:
1. 从 FPS 下载 Excel 文件
2. 校验 Excel 数据合法性
3. 批量导入黑名单（100 条一批）

7.7 消息格式与路由总结

外部系统
   │
   ▼
RMB (WeMQ)
   │
   ├── 服务 06100854-01 ──→ MyRmbService.syncListHandler()
   │                           └── SyncListHandler.handle()
   │                               ├── serviceCode=S001 → SyncServiceS0001（通用名单查询）
   │                               ├── serviceCode=S002 → SyncServiceS0002（黑名单查询）
   │                               └── serviceCode=S003 → SyncServiceS0003（黑名单上报）
   │
   └── 服务 06100855-01 ──→ MyRmbService.blackListAddHandler()
                               └── SyncListHandler.handle()
                                   └── serviceCode=S003 → SyncServiceS0003（黑名单上报）

八、业务流程

8.1 黑名单查询流程（S002）

请求方 → RMB消息(S002) → SyncListHandler
  → ServiceHandlerHolder → SyncServiceS0002
    → 参数校验（productCd, blkList）
    → 遍历 blkList:
      → BlkListDao.selectOneBlkList(productCd, type, value)
        → SQL: WHERE PRODUCT_CD=? AND TYPE=? AND VALUE=? AND OPERATED_SIGN!='0' AND EXPIRED_DATE>=today
      → 构建 matched=Y/N 响应
    → 返回匹配结果列表

8.2 通用名单查询流程（S001）

请求方 → RMB消息(S001) → SyncListHandler
  → ServiceHandlerHolder → SyncServiceS0001
    → 参数校验（commonList, listType in [RPI_BC_BL, RPI_FP_BL, RPP_BL]）
    → 遍历 commonList:
      → CommonListDao.selectOneCommonList(productCd, listType, appType, appAcctNo)
        → SQL: WHERE PRODUCT_CD=? AND LIST_TYPE=? AND APP_TYPE=? AND LIST_VALUE=? AND OPERATED_SIGN!='0'
      → 收集匹配记录
    → 有匹配返回 SUCCESS + 结果，无匹配返回 NO_DATA_FOUND

8.3 黑名单联机上报流程（S003）

请求方 → RMB消息(S003) → SyncListHandler
  → ServiceHandlerHolder → SyncServiceS0003
    → 参数校验（blkList, productCd, blkType, blkValue）
    → 构建 BlkList 实体列表:
      - 设置 operatedSign="1"
      - expiredDate 默认当前日期+100年
    → BlkListDao.insertOrUpdateBlkList(blkLists)
      → SQL: INSERT ... ON DUPLICATE KEY UPDATE
    → OnlineAddFlowDao.insert(record)
      → 记录流水（BIZ_NO, CONTENT, STATUS=0）
    → 返回 SUCCESS

8.4 白名单异步新增流程（A0001）

外部系统 → RMB异步消息 → AsyncRouteService
  → 根据 SERVICE_CODE 查找 AsyncServiceA0001
    → 参数校验（PRODUCT_CD, ID_TYPE, ID_NO, NAME 不为空）
    → WhiteListDao.addOrUpdateAsKey(data)
      → SQL: INSERT TM_WHITE_LIST ... ON DUPLICATE KEY UPDATE
    → OnlineAddFlowDao.insert(record)
    → 记录日志

8.5 名单文件批量导入流程（S0004）

请求方 → RMB消息(S004) → SyncListHandler
  → ServiceHandlerHolder → FileServiceS0004
    → 参数校验（hashValues, fileType in [BLK, RPI_BC_BL, RPI_FP_BL, RPP_BL], fileId）
    → FpsFileExchange.getFile(fileId, hashValues)
      → 从 FPS 下载 Excel 文件到本地
    → if fileType == "BLK":
      → ExcelUtils.checkBlkList(file, errorFile)
        → BlkListListener 逐行校验
          - productCd: 1-6 位
          - type: inDev/inId
          - value: 1-100 位
          - reason: 1-1024 位
          - source: 1-30 位
          - operatedSign: 0/1
      → ExcelUtils.importBlkList(file, blkListDao)
        → BlkListWriteListener 批量写入（每 100 条一批）
          → BlkListDao.insertOrUpdateBlkList()
    → 返回 SUCCESS / PARAM_BAD / SYSTEM_EXCEPTION

8.6 名单类型管理

系统支持的名单类型包括：

类型代码	说明	存储表
inDev	设备黑名单	TM_BLK_LIST
inId	证件黑名单	TM_BLK_LIST
RPI_BC_BL	断卡来账黑名单	TM_COMMON_LIST
RPI_FP_BL	止付冻结失败拦截黑名单	TM_COMMON_LIST
RPP_BL	来账人工黑名单	TM_COMMON_LIST
EX_BLK	外部黑名单（文件导入）	—
IN_BLK	内部黑名单（文件导入）	—
BLK	通用黑名单文件类型	TM_BLK_LIST

九、配置与部署

9.1 配置文件结构

conf/blms-service/              # 生产配置
├── blms-service.properties     # 业务配置（系统ID、服务ID、数据库参数）
├── blms-service-env.properties # 环境配置（DCN、IDC、数据库连接、FPS）
├── rmb-client.properties       # RMB 客户端配置
├── rmb-system-blms-service.properties  # RMB 系统配置
├── gns-api.properties          # GNS 服务发现配置
├── weservice.properties        # WebService 配置
└── log4j2.xml                  # 日志配置

conf-local/blms-service/        # 本地开发配置（同结构）

9.2 Spring 上下文配置（service-context.xml）

导入 SDK 配置: biz-cncsdk-core.xml, biz-cncsdk-seq.xml
环境变量加载: EnvironmentFactoryBean 从属性文件和环境变量加载配置
组件扫描: cn.webank.cnc.blms 包
数据源: commons-dbcp.BasicDataSource，密码通过 RSA 加密
MyBatis: SqlSessionFactoryBean + MapperScannerConfigurer
事务: DataSourceTransactionManager，注解驱动
AOP: AspectJ 自动代理

9.3 数据库连接配置

驱动: com.mysql.cj.jdbc.Driver
连接池: 阿里 Druid（com.alibaba.druid.pool.DruidDataSource）
数据库名: blmsdb
连接参数: useUnicode=true&characterEncoding=UTF-8&useSSL=false
Socket 超时: 60000ms
下划线转驼峰: 开启（mapUnderscoreToCamelCase=true）
密码加密: RSA 加密，通过 RsautilManager.decryptByKeyFile() 解密

9.4 FPS 文件服务配置

Host: 通过 cnc.sdk.fps.host 配置
Port: 通过 cnc.sdk.fps.port 配置
认证: 用户名 + RSA 加密密码
OB Init Server: 10.107.100.191;10.107.116.166
Monitor: 10.107.100.191:17070;10.107.108.9:17070

9.5 RMB 消息配置

系统 ID: Z468
DCN: 通过变量 [@Z468-VIRTUAL_DCN] 配置
IDC: 通过变量 [@Z468-IDC_RMB_IDC_NAME] 配置
配置中心: [@Z468-IDC_WEMQ_CONFIGCENTER_ADDR]
消费线程: 最小 24，最大 72
队列大小: 10000

十、外部系统集成

10.1 RMB（Reliable Message Bus）/ WeMQ

角色: 消息中间件，BLMS 的核心通信通道
用途: 接收外部系统的名单查询/上报请求
SDK: rmb-api 2.1.13.1 + zcnc-sdk-starter-rmb
注册服务:
- 06100854-01：名单同步查询入口
- 06100855-01：黑名单联机上报入口
通信模式: 同步请求/响应（RequestHandler）
消息格式: JSON（通过 JsonUtil.jsonReSerializer 解析）

10.2 FPS（File Platform Service）

角色: 文件传输平台
用途: 名单文件的存储和传输
SDK: fps-agent 1.3.4 + zcnc-sdk-starter-io（FpsClientUtil）
操作:
- 下载：通过 fileId + hashValues 获取文件
- 上传：将本地文件上传到 FPS（旧版 FpsAgent）
文件类型: Excel（.xlsx）

10.3 TDSQL

角色: 持久化存储（MySQL 兼容的分布式数据库）
SDK: zcnc-sdk-starter-db（TdsqlAutoConfiguration）
连接地址: jdbc:mysql://10.107.96.141:3306/blmsdb
操作: 通过 MyBatis Mapper 执行 SQL

10.4 CNC SDK 平台

核心: zcnc-sdk-starter-core — 提供通用工具类（JsonUtil, DateUtils, AppContextUtil, StringUtil 等）
序列号: zcnc-sdk-starter-seq — 基于数据库的序列号生成（TM_SEC_SEQ）
数据脱敏: zcnc-sdk-starter-data-clean
系统状态: zcnc-sdk-starter-systemstatus
加密: RsautilManager — RSA 密钥管理

10.5 接口描述映射（MyTradeLogUtil）

系统记录了与多个外部系统的接口交互：

接口键	描述
06510016-01-06510016-01	DS 白名单导入
06300005-01-XBS001	信保新增被邀请人
06300005-01-XBS002	信保更新被邀请人
06300005-01-003	总行黑名单、关联人查询
06300005-01-DS001	DS 商户黑名单查询
06300005-01-004	信保白名单查询
06300005-01-005	通用简单名单查询接口
06300005-01-JYD_WZH001	经营贷微帐号信息查询
06300005-01-JYD_WL001/002	经营贷白名单查询/删除
06300005-01-FZX_WL001	房产增信白名单查询
06300005-01-DS_RP001	DS 关联人查询
06300005-01-DS_GL002	灰名单查询（新）
06300005-01-DS_BL001/002	DS 黑名单查询 / 黑名单查询（新）
06300005-01-MULT001	名单组合查询接口
06300005-01-DS003/004	DS 白名单指标数据查询 / 更新手机号
06210010-01-06210010-01	CPS 开卡成功异步通知
06210013-01-06210013-01	黑名单异步新增
06300005-01-06300005-01	白名单黑名单关联人灰名单查询
06300005-03-06300005-03	审批名单查询接口
06210011-01-06210011-01	证件匹配错误次数异步通知

附录：关键设计模式

A.1 模板方法模式

AbstractBaseService 定义了 checkParam() → doService() → postProcess() 的模板流程，所有同步服务继承此类实现各自逻辑。

A.2 策略模式

ServiceHandlerHolder 根据 serviceCode 动态选择 ServiceHandler 实现，支持运行时扩展（通过 ServiceCodeEnum.registerService()）。

A.3 观察者/监听器模式

EasyExcel 的 ReadListener 接口实现（BlkListListener, BlkListWriteListener）用于流式处理 Excel 数据。

A.4 钩子模式

MsgEnhancer 接口作为可插拔的消息增强钩子，允许在不修改核心代码的情况下扩展消息处理逻辑。

A.5 工厂模式

EnvironmentFactoryBean 作为 Spring FactoryBean，实现配置的灵活加载。

页面解读

01-公共业务

02-账户查询

03-账户管理

04-账务处理

05-内部账户业务

06-账户特殊业务

专题知识

BLMS 名单管理系统 ​

一、系统概述 ​

1.1 系统定位 ​

1.2 技术栈 ​

1.3 系统编号与接口注册 ​

二、模块结构 ​

子模块 blms-service ​

SDK 依赖 ​

三、包架构（完整包树） ​

四、核心类详解 ​

4.1 Application — 启动类 ​

4.2 annotation/Attribute — 属性注解 ​

4.3 config/FilterConfig — 过滤器配置 ​

4.4 constants/CommonValues — 公共常量 ​

4.5 dao 层 — 数据访问对象 ​

4.5.1 BlkListDao — 黑名单 DAO ​

4.5.2 CommonListDao — 通用名单 DAO ​

4.5.3 ListFileConfigDao — 名单文件配置 DAO ​

4.5.4 ListFileFlowDao — 名单文件流水 DAO ​

4.5.5 OnlineAddFlowDao — 联机新增流水 DAO ​

4.5.6 WhiteListDao — 白名单 DAO ​

4.6 enums 层 — 枚举定义 ​

4.6.1 ListFileStatus — 文件处理状态 ​

4.6.2 LogKeyWordEnum — 日志关键字 ​

4.6.3 RspCodeEnum — 响应码枚举 ​

4.6.4 ServiceCodeEnum — 服务编码枚举 ​

4.7 listener 层 — EasyExcel 监听器 ​

4.7.1 BlkListListener — 黑名单读取校验监听器 ​

4.7.2 BlkListWriteListener — 黑名单批量写入监听器 ​

4.8 model 层 — 数据模型 ​

4.8.1 BlkList — 黑名单实体 ​

4.8.2 CommonList — 通用名单实体 ​

4.8.3 ListFileConfig — 名单文件配置 ​

4.8.4 ListFileFlow — 名单文件流水 ​

4.8.5 WhiteListDTO — 白名单 DTO ​

4.9 service 层 — 业务逻辑 ​

4.9.1 ServiceHandler — 服务处理器接口 ​

4.9.2 ServiceHandlerHolder — 服务处理器持有者 ​

4.9.3 SyncService — 同步服务接口 ​

4.9.4 AsyncService — 异步服务接口 ​

4.9.5 MsgEnhancer — 消息增强器接口 ​

4.9.6 AbstractBaseService — 基础服务抽象类 ​

4.10 service/impl 层 — 服务实现 ​

4.10.1 AsyncRouteService — 异步路由服务 ​

4.10.2 ListFileHelper — 名单文件处理辅助类 ​

4.11 service/impl/api 层 — API 服务实现 ​

4.11.1 SyncServiceS0001 — 通用名单查询 ​

4.11.2 SyncServiceS0002 — 黑名单查询 ​

4.11.3 SyncServiceS0003 — 黑名单联机上报 ​

4.11.4 AsyncServiceA0001 — 白名单异步新增 ​

4.11.5 FileServiceS0004 — 名单文件导入 ​

4.12 service/impl/enhancer — 消息增强器 ​

ListTypeEnhancer — 名单类型增强器 ​

4.13 service/rmb — RMB 消息入口 ​

MyRmbService — RMB 服务入口 ​

4.14 service/rmbhandler — RMB 消息处理器 ​

SyncListHandler — 同步名单处理器 ​

4.15 util 层 — 工具类 ​

BeanUtil — Spring Bean 工具 ​

DateUtil — 日期工具 ​

EnvironmentFactoryBean — 环境配置工厂 ​

ExcelUtils — Excel 工具 ​

FpsAgent — FPS 文件代理（旧版） ​

FpsFileExchange — FPS 文件交换（新版） ​

LogUtil — 日志工具 ​

MapUtil — Map 工具 ​

MyTradeLogUtil — 交易日志工具 ​

ParamCheckUtil — 参数校验工具 ​

RmbUtil — RMB 消息工具 ​

ThreadContext — 线程上下文 ​

五、数据模型 ​

5.1 数据库表结构 ​

BLMS 名单管理系统

一、系统概述

1.1 系统定位

1.2 技术栈

1.3 系统编号与接口注册

二、模块结构

子模块 blms-service

SDK 依赖

三、包架构（完整包树）

四、核心类详解

4.1 Application — 启动类

4.2 annotation/Attribute — 属性注解

4.3 config/FilterConfig — 过滤器配置

4.4 constants/CommonValues — 公共常量

4.5 dao 层 — 数据访问对象

4.5.1 BlkListDao — 黑名单 DAO

4.5.2 CommonListDao — 通用名单 DAO

4.5.3 ListFileConfigDao — 名单文件配置 DAO

4.5.4 ListFileFlowDao — 名单文件流水 DAO

4.5.5 OnlineAddFlowDao — 联机新增流水 DAO

4.5.6 WhiteListDao — 白名单 DAO

4.6 enums 层 — 枚举定义

4.6.1 ListFileStatus — 文件处理状态

4.6.2 LogKeyWordEnum — 日志关键字

4.6.3 RspCodeEnum — 响应码枚举

4.6.4 ServiceCodeEnum — 服务编码枚举

4.7 listener 层 — EasyExcel 监听器

4.7.1 BlkListListener — 黑名单读取校验监听器

4.7.2 BlkListWriteListener — 黑名单批量写入监听器

4.8 model 层 — 数据模型

4.8.1 BlkList — 黑名单实体

4.8.2 CommonList — 通用名单实体

4.8.3 ListFileConfig — 名单文件配置

4.8.4 ListFileFlow — 名单文件流水

4.8.5 WhiteListDTO — 白名单 DTO

4.9 service 层 — 业务逻辑

4.9.1 ServiceHandler — 服务处理器接口

4.9.2 ServiceHandlerHolder — 服务处理器持有者

4.9.3 SyncService — 同步服务接口

4.9.4 AsyncService — 异步服务接口

4.9.5 MsgEnhancer — 消息增强器接口

4.9.6 AbstractBaseService — 基础服务抽象类

4.10 service/impl 层 — 服务实现

4.10.1 AsyncRouteService — 异步路由服务

4.10.2 ListFileHelper — 名单文件处理辅助类

4.11 service/impl/api 层 — API 服务实现

4.11.1 SyncServiceS0001 — 通用名单查询

4.11.2 SyncServiceS0002 — 黑名单查询

4.11.3 SyncServiceS0003 — 黑名单联机上报

4.11.4 AsyncServiceA0001 — 白名单异步新增

4.11.5 FileServiceS0004 — 名单文件导入

4.12 service/impl/enhancer — 消息增强器

ListTypeEnhancer — 名单类型增强器

4.13 service/rmb — RMB 消息入口

MyRmbService — RMB 服务入口

4.14 service/rmbhandler — RMB 消息处理器

SyncListHandler — 同步名单处理器

4.15 util 层 — 工具类

BeanUtil — Spring Bean 工具

DateUtil — 日期工具

EnvironmentFactoryBean — 环境配置工厂

ExcelUtils — Excel 工具

FpsAgent — FPS 文件代理（旧版）

FpsFileExchange — FPS 文件交换（新版）

LogUtil — 日志工具

MapUtil — Map 工具

MyTradeLogUtil — 交易日志工具

ParamCheckUtil — 参数校验工具

RmbUtil — RMB 消息工具

ThreadContext — 线程上下文

五、数据模型

5.1 数据库表结构

TM_BLK_LIST — 黑名单表

TM_COMMON_LIST — 通用名单表

TM_LIST_FILE_CONFIG — 名单文件配置表

TM_LIST_FILE_FLOW — 名单文件操作流水表

TM_ONLINE_ADD_REC — 联机新增流水记录表

TM_WHITE_LIST — 白名单表

TM_SEC_SEQ — 序列号表

5.2 MyBatis Mapper 文件清单