diff --git a/docs/superpowers/specs/2026-03-18-bank-tag-model-placeholder-design.md b/docs/superpowers/specs/2026-03-18-bank-tag-model-placeholder-design.md new file mode 100644 index 00000000..419e2680 --- /dev/null +++ b/docs/superpowers/specs/2026-03-18-bank-tag-model-placeholder-design.md @@ -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 未提供英文指标名的,使用稳定占位编码 + +占位编码格式: + +- `_<两位序号>` + +示例: + +- `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 设计 + +### 设计原则 + +- 每条规则拥有单独 `