新增银行流水模型补齐占位设计文档
This commit is contained in:
@@ -0,0 +1,286 @@
|
||||
# 银行流水模型补齐占位设计
|
||||
|
||||
## 背景
|
||||
|
||||
当前项目的银行流水打标能力已经具备基础框架，包括：
|
||||
|
||||
- 规则定义表 `ccdi_bank_tag_rule`
|
||||
- 结果表 `ccdi_bank_statement_tag_result`
|
||||
- 任务表 `ccdi_bank_tag_task`
|
||||
- 规则执行入口 `CcdiBankTagServiceImpl`
|
||||
- 技术口径 SQL `CcdiBankTagAnalysisMapper.xml`
|
||||
|
||||
现阶段仅落地了“大额交易”模型下的 8 条规则。根据 [assets/模型信息.xlsx](../../../assets/模型信息.xlsx)，其余模型规则尚未补齐到现有打标框架中，导致规则元数据、执行分发、XML SQL 坑位与参数配置之间不完整。
|
||||
|
||||
本次需求是基于现有银行流水模型打标能力，补齐尚未添加的模型规则，并自动填充必要字段。由于这些规则的正式 SQL 尚未准备好，本期先在 XML 中预留规则级 SQL 位置，并使用恒不命中的假 SQL 保证执行时不报错。
|
||||
|
||||
## 目标
|
||||
|
||||
- 按 `assets/模型信息.xlsx` 补齐现有缺失的模型规则
|
||||
- 保证新增规则进入现有打标执行框架，可被统一调度执行
|
||||
- 对每条新增规则预留独立的 XML SQL 坑位，便于后续逐条替换为真实 SQL
|
||||
- 在缺少正式 SQL 的阶段，保证规则执行返回空结果，不影响现有任务稳定性
|
||||
- 自动补齐规则初始化所需的最小字段，减少手工维护成本
|
||||
|
||||
## 非目标
|
||||
|
||||
- 本期不编写真实业务 SQL
|
||||
- 本期不调整现有 8 条“大额交易”规则的编码、参数与 SQL 逻辑
|
||||
- 本期不新增前端页面或结果展示逻辑
|
||||
- 本期不为 Excel 中缺少英文指标名的规则补充参数配置
|
||||
- 本期不引入动态 SQL 配置能力
|
||||
|
||||
## 现状分析
|
||||
|
||||
### 现有规则实现范围
|
||||
|
||||
当前 `CcdiBankTagServiceImpl` 仅实现以下规则分发：
|
||||
|
||||
- `HOUSE_OR_CAR_EXPENSE`
|
||||
- `TAX_EXPENSE`
|
||||
- `SINGLE_LARGE_INCOME`
|
||||
- `CUMULATIVE_INCOME`
|
||||
- `ANNUAL_TURNOVER`
|
||||
- `LARGE_CASH_DEPOSIT`
|
||||
- `FREQUENT_CASH_DEPOSIT`
|
||||
- `LARGE_TRANSFER`
|
||||
|
||||
这些规则均属于 `LARGE_TRANSACTION` 模型。
|
||||
|
||||
### 现有参数配置范围
|
||||
|
||||
当前默认参数脚本中已经包含以下模型：
|
||||
|
||||
- `LARGE_TRANSACTION`
|
||||
- `SUSPICIOUS_PART_TIME`
|
||||
- `SUSPICIOUS_FOREIGN_EXCHANGE`
|
||||
- `ABNORMAL_BEHAVIOR`
|
||||
- `SUSPICIOUS_GAMBLING`
|
||||
|
||||
但其中多数模型只补了参数，尚未补规则元数据和打标执行入口。
|
||||
|
||||
### Excel 规则范围
|
||||
|
||||
`assets/模型信息.xlsx` 共 33 条规则，其中：
|
||||
|
||||
- 已落地 8 条
|
||||
- 待补齐 25 条
|
||||
|
||||
涉及以下模型组：
|
||||
|
||||
- 异常交易
|
||||
- 疑似赌博
|
||||
- 可疑关系
|
||||
- 可疑兼职
|
||||
- 可疑财产
|
||||
- 可疑外汇交易
|
||||
- 可疑付息
|
||||
- 可疑采购
|
||||
- 异常行为
|
||||
|
||||
## 方案对比
|
||||
|
||||
### 方案一：仅补规则初始化 SQL
|
||||
|
||||
优点：
|
||||
|
||||
- 改动最少
|
||||
|
||||
缺点：
|
||||
|
||||
- Java 分发与 XML 坑位仍然缺失
|
||||
- 后续接入真实 SQL 时仍需再次补完整链路
|
||||
- 无法满足“先留好位置”的目标
|
||||
|
||||
### 方案二：补规则元数据、Java 分发与 XML 占位 SQL
|
||||
|
||||
优点：
|
||||
|
||||
- 与现有大额交易模型实现方式一致
|
||||
- 每条规则都有独立执行入口与独立 SQL 坑位
|
||||
- 后续替换真实 SQL 时只需改对应 XML 或局部参数映射
|
||||
- 风险可控，不会产生误命中数据
|
||||
|
||||
缺点：
|
||||
|
||||
- 本期一次性需要补齐较多占位方法与规则定义
|
||||
|
||||
### 方案三：新增统一空实现兜底
|
||||
|
||||
优点：
|
||||
|
||||
- 代码量更少
|
||||
|
||||
缺点：
|
||||
|
||||
- 规则边界不清晰
|
||||
- 后续逐条补 SQL 时定位成本更高
|
||||
- 不利于维护和评审
|
||||
|
||||
## 最终方案
|
||||
|
||||
采用方案二：
|
||||
|
||||
- 补齐规则元数据
|
||||
- 补齐 `CcdiBankTagAnalysisMapper` 方法定义
|
||||
- 补齐 `CcdiBankTagServiceImpl` 的规则分发
|
||||
- 在 `CcdiBankTagAnalysisMapper.xml` 中为每条新规则增加单独的占位 SQL
|
||||
- 对缺少正式 SQL 的规则统一返回空结果，保证执行成功但不命中
|
||||
|
||||
## 编码设计
|
||||
|
||||
### 模型编码映射
|
||||
|
||||
新增模型统一映射为稳定的 `model_code`：
|
||||
|
||||
- `异常交易` -> `ABNORMAL_TRANSACTION`
|
||||
- `疑似赌博` -> `SUSPICIOUS_GAMBLING`
|
||||
- `可疑关系` -> `SUSPICIOUS_RELATION`
|
||||
- `可疑兼职` -> `SUSPICIOUS_PART_TIME`
|
||||
- `可疑财产` -> `SUSPICIOUS_PROPERTY`
|
||||
- `可疑外汇交易` -> `SUSPICIOUS_FOREIGN_EXCHANGE`
|
||||
- `可疑付息` -> `SUSPICIOUS_INTEREST_PAYMENT`
|
||||
- `可疑采购` -> `SUSPICIOUS_PURCHASE`
|
||||
- `异常行为` -> `ABNORMAL_BEHAVIOR`
|
||||
|
||||
已在参数表中使用的模型编码保持不变，避免后续参数关联断裂。
|
||||
|
||||
### 规则编码生成
|
||||
|
||||
规则编码采用以下优先级：
|
||||
|
||||
1. 已有现存规则编码的，保持不变
|
||||
2. Excel 提供了明确英文指标名且适合复用为规则编码的，直接使用英文指标名
|
||||
3. Excel 未提供英文指标名的，使用稳定占位编码
|
||||
|
||||
占位编码格式：
|
||||
|
||||
- `<MODEL_CODE>_<两位序号>`
|
||||
|
||||
示例：
|
||||
|
||||
- `ABNORMAL_TRANSACTION_01`
|
||||
- `SUSPICIOUS_PROPERTY_03`
|
||||
|
||||
这样可确保编码稳定、可批量生成、可回溯到 Excel 顺序，同时避免为无英文名规则主观造词。
|
||||
|
||||
### 自动补齐字段规则
|
||||
|
||||
- `model_code`：由中文模型名映射生成
|
||||
- `model_name`：使用 Excel 中的模型名称
|
||||
- `rule_code`：按上述规则生成
|
||||
- `rule_name`：使用“核心异常点（展示在前端页面）”
|
||||
- `indicator_code`：有英文指标名则写入，无则留空
|
||||
- `business_caliber`：使用 Excel 中“业务口径”
|
||||
- `result_type`：
|
||||
- `可疑结果返回` 包含“流水明细” -> `STATEMENT`
|
||||
- 其他返回形式 -> `OBJECT`
|
||||
- `risk_level`：
|
||||
- `高风险` -> `HIGH`
|
||||
- `一般` -> `GENERAL`
|
||||
- 空值 -> `NULL`
|
||||
|
||||
## 参数配置策略
|
||||
|
||||
只为 Excel 中明确给出英文指标名、且明显属于阈值参数的规则补默认参数。
|
||||
|
||||
处理原则：
|
||||
|
||||
- 有英文指标名且已存在默认参数的，保持现状
|
||||
- 有英文指标名但默认参数缺失的，补充默认参数初始化数据
|
||||
- 无英文指标名的，不新增参数记录
|
||||
- `BankTagRuleConfigResolver` 仅补需要参数解析的规则映射
|
||||
|
||||
本期默认假设：
|
||||
|
||||
- 无英文指标名规则不依赖参数配置
|
||||
- 其 `indicator_code` 可为空
|
||||
|
||||
## 占位 SQL 设计
|
||||
|
||||
### 设计原则
|
||||
|
||||
- 每条规则拥有单独 `<select>`，不共用通用 SQL
|
||||
- SQL 必须可被 MyBatis 正常解析和执行
|
||||
- SQL 必须返回与结果映射一致的字段结构
|
||||
- SQL 必须恒不命中，避免生成伪造结果
|
||||
|
||||
### STATEMENT 规则占位模板
|
||||
|
||||
对流水级结果使用如下结构：
|
||||
|
||||
```sql
|
||||
select
|
||||
bs.bank_statement_id AS bankStatementId,
|
||||
bs.group_id AS groupId,
|
||||
bs.batch_id AS logId,
|
||||
'占位SQL，待补充真实规则' AS reasonDetail
|
||||
from ccdi_bank_statement bs
|
||||
where 1 = 0
|
||||
```
|
||||
|
||||
### OBJECT 规则占位模板
|
||||
|
||||
对对象级结果使用如下结构：
|
||||
|
||||
```sql
|
||||
select
|
||||
'STAFF_ID_CARD' AS objectType,
|
||||
'' AS objectKey,
|
||||
'占位SQL，待补充真实规则' AS reasonDetail
|
||||
from dual
|
||||
where 1 = 0
|
||||
```
|
||||
|
||||
如果数据库兼容性不适合 `dual`，则改为从现有业务表取空结果，核心要求是不报错且字段齐全。
|
||||
|
||||
## 详细变更范围
|
||||
|
||||
### 后端代码
|
||||
|
||||
需要修改以下文件：
|
||||
|
||||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiBankTagAnalysisMapper.java`
|
||||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankTagServiceImpl.java`
|
||||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/BankTagRuleConfigResolver.java`
|
||||
- `ccdi-project/src/main/resources/mapper/ccdi/project/CcdiBankTagAnalysisMapper.xml`
|
||||
|
||||
### SQL 脚本
|
||||
|
||||
需要修改以下文件：
|
||||
|
||||
- `sql/2026-03-16-bank-tagging.sql`
|
||||
- `sql/ccdi_model_param.sql`
|
||||
- `sql/2026-03-16-update-ccdi-model-param-defaults.sql`
|
||||
|
||||
## 兼容性与风险控制
|
||||
|
||||
- 现有 8 条大额交易规则不改编码、不改 SQL、不改参数映射
|
||||
- 新增规则即使被执行，也只会返回空结果
|
||||
- 不会写入脏数据到 `ccdi_bank_statement_tag_result`
|
||||
- 不会因为找不到 Mapper 方法或 XML 语句导致任务失败
|
||||
- 无参数规则不会加入必填参数集合，避免产生无意义缺参告警
|
||||
|
||||
## 验证方案
|
||||
|
||||
最小验证包括：
|
||||
|
||||
- 编译通过，确保 Java 接口与 XML 绑定一致
|
||||
- 触发打标任务时，不出现 `Invalid bound statement` 或参数解析异常
|
||||
- 现有 8 条规则仍保持原有执行行为
|
||||
- 新增占位规则执行后返回空结果，不新增命中数据
|
||||
|
||||
建议执行：
|
||||
|
||||
- `mvn -pl ccdi-project -am test`
|
||||
- 如测试范围过大，至少执行 `mvn -pl ccdi-project -am compile`
|
||||
|
||||
## 实施边界
|
||||
|
||||
本期完成后，系统将具备“规则骨架完整、真实 SQL 待补”的状态。后续每补一条真实规则时，只需要：
|
||||
|
||||
1. 替换对应 XML 占位 SQL
|
||||
2. 如需阈值参数，再补 `BankTagRuleConfigResolver` 映射或默认参数
|
||||
3. 按规则粒度补测试
|
||||
|
||||
无需再次调整规则框架、结果表、任务调度和规则定义结构。
|
||||
BIN
logs/spring.log.2026-03-17.0.gz
Normal file
BIN
logs/spring.log.2026-03-17.0.gz
Normal file
Binary file not shown.
Reference in New Issue
Block a user