From a7f068b3096e5c9d368cc7e08d9156bd13121b8f Mon Sep 17 00:00:00 2001
From: wkc <978997012@qq.com>
Date: Fri, 20 Mar 2026 12:04:41 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E9=93=B6=E8=A1=8C=E6=B5=81?=
 =?UTF-8?q?=E6=B0=B4=E6=A8=A1=E5=9E=8B=E7=9C=9F=E5=AE=9E=E8=A7=84=E5=88=99?=
 =?UTF-8?q?=E4=B8=A4=E9=98=B6=E6=AE=B5=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...-20-bank-tag-real-rule-two-phase-design.md | 359 ++++++++++++++++++
 1 file changed, 359 insertions(+)
 create mode 100644 docs/design/2026-03-20-bank-tag-real-rule-two-phase-design.md

diff --git a/docs/design/2026-03-20-bank-tag-real-rule-two-phase-design.md b/docs/design/2026-03-20-bank-tag-real-rule-two-phase-design.md
new file mode 100644
index 00000000..2180dc6a
--- /dev/null
+++ b/docs/design/2026-03-20-bank-tag-real-rule-two-phase-design.md
@@ -0,0 +1,359 @@
+# 银行流水模型真实规则两阶段落地设计文档
+
+**模块**: 银行流水打标
+**日期**: 2026-03-20
+
+## 一、背景
+
+当前项目已经具备银行流水打标基础链路：
+
+- 规则元数据表 `ccdi_bank_tag_rule`
+- 结果表 `ccdi_bank_statement_tag_result`
+- 任务表 `ccdi_bank_tag_task`
+- 规则执行入口 `CcdiBankTagServiceImpl`
+- SQL 承载文件 `CcdiBankTagAnalysisMapper.xml`
+- 参数解析器 `BankTagRuleConfigResolver`
+
+其中“大额交易”模型下的首批规则已经具备真实 SQL，其余不少规则虽然已经补齐了：
+
+- `rule_code`
+- `model_code`
+- Service 分发入口
+- Mapper 方法签名
+- XML `select`
+
+但当前 XML 仍是 `where 1 = 0` 的占位 SQL，尚未产生真实命中结果。
+
+根据 [assets/模型信息.xlsx](/Users/wkc/Desktop/ccdi/ccdi/assets/模型信息.xlsx) 当前整理结果，现有未真实实现、且在本环境中已判定可直接执行 SQL 的银行流水模型共 19 条。本次需求是将这 19 条规则从“占位规则”替换为“真实规则”。
+
+## 二、目标
+
+本次设计目标如下：
+
+1. 将 19 条未真实实现的银行流水模型接入现有真实打标链路。
+2. 保持现有规则式架构不变，不新增平行模块或兼容性补丁链路。
+3. 将真实命中逻辑统一收敛到 `CcdiBankTagAnalysisMapper.xml`。
+4. 补齐规则执行所需的参数映射、初始化 SQL 与验证测试。
+5. 为控制改动规模，将 19 条规则拆成两期实施，并分别产出前后端实施计划。
+
+## 三、范围
+
+### 3.1 本次范围
+
+- `CcdiBankTagAnalysisMapper.xml` 中 19 条占位规则替换为真实 SQL
+- `CcdiBankTagServiceImpl` 中对应规则的真实执行分发校准
+- `BankTagRuleConfigResolver` 中新增规则参数映射补齐
+- `sql/` 下与本次规则相关的初始化脚本或增量脚本调整
+- 单元测试、结构测试与回归测试补齐
+- 新增 1 份设计文档、2 份后端实施计划、2 份前端实施计划
+
+### 3.2 不在本次范围
+
+- 不新增前端页面字段、交互或展示组件
+- 不引入动态规则引擎、脚本注册中心或 DSL
+- 不新增数据库表结构
+- 不处理 `xlsx` 中当前环境不可直接执行的规则
+- 不改造“大额交易”已真实落地的 8 条规则逻辑
+
+## 四、现状分析
+
+### 4.1 当前实现结构
+
+当前银行流水打标流程为：
+
+1. `CcdiBankTagServiceImpl.rebuildProject(...)` 加载启用规则。
+2. 按 `rule_code` 分发到 `executeStatementRule / executeObjectRule`。
+3. 通过 `CcdiBankTagAnalysisMapper` 调用 XML 中的具体 SQL。
+4. 将命中结果组装为 `CcdiBankTagResult` 后批量入库。
+5. 刷新项目风险人数，供结果总览等后续页面使用。
+
+### 4.2 当前核心问题
+
+19 条目标规则目前已具备“入口”，但不具备“真实命中能力”：
+
+- `ccdi_bank_tag_rule` 中已有规则元数据
+- `CcdiBankTagServiceImpl` 中已有大部分分发分支
+- `CcdiBankTagAnalysisMapper.java` 中已有对应方法
+- `CcdiBankTagAnalysisMapper.xml` 中对应 `<select>` 仍为占位 SQL
+
+因此当前的主要缺口不是“补骨架”，而是“把占位 SQL 换成真实规则 SQL，并补齐参数映射与测试”。
+
+### 4.3 当前环境可直接落地的 19 条规则
+
+#### 第一期
+
+- `GAMBLING_SENSITIVE_KEYWORD`
+- `SPECIAL_AMOUNT_TRANSACTION`
+- `SUSPICIOUS_INCOME_KEYWORD`
+- `SINGLE_PURCHASE_AMOUNT`
+- `SINGLE_SETTLEMENT_AMOUNT`
+- `LARGE_PURCHASE_TRANSACTION`
+- `STOCK_TFR_LARGE`
+- `LARGE_STOCK_TRADING`
+- `WITHDRAW_CNT`
+
+#### 第二期
+
+- `LOW_INCOME_RELATIVE_LARGE_TRANSACTION`
+- `MULTI_PARTY_GAMBLING_TRANSFER`
+- `MONTHLY_FIXED_INCOME`
+- `FIXED_COUNTERPARTY_TRANSFER`
+- `HOUSE_REGISTRATION_MISMATCH`
+- `PROPERTY_FEE_REGISTRATION_MISMATCH`
+- `TAX_ASSET_REGISTRATION_MISMATCH`
+- `SUPPLIER_CONCENTRATION`
+- `SALARY_QUICK_TRANSFER`
+- `SALARY_UNUSED`
+
+## 五、方案对比
+
+### 5.1 方案一：一次性直接替换 19 条占位 SQL
+
+优点：
+
+- 最短路径
+- 架构最稳定
+- 规则口径统一落地后可立即进入现有结果链路
+
+缺点：
+
+- 单次改动面较大
+- SQL、参数、测试回归压力集中
+
+### 5.2 方案二：按模型组拆成多轮交付
+
+优点：
+
+- 单次改动更小
+
+缺点：
+
+- 一部分规则真实、一部分规则仍占位，阶段内口径不完整
+- 和本次“一次性纳入两批规划”的目标不一致
+
+### 5.3 方案三：改造成更通用的动态规则架构
+
+优点：
+
+- 长期可维护性表面上更统一
+
+缺点：
+
+- 明显超出本次需求
+- 会把风险扩大到 Service、Mapper、配置、测试结构整体重构
+
+### 5.4 结论
+
+采用方案一，但执行层面拆成两期实施：
+
+- 总体架构保持不变
+- 设计一次性定稿
+- 实施按“先易后难”拆成两期
+
+## 六、总体设计
+
+### 6.1 架构原则
+
+本次遵循以下原则：
+
+1. 不引入新模块
+2. 不新增兼容性双轨逻辑
+3. 不在 Java Service 层补业务口径判断
+4. 所有真实命中逻辑统一落在 `CcdiBankTagAnalysisMapper.xml`
+5. 参数解析仍通过 `BankTagRuleConfigResolver`
+
+### 6.2 数据流
+
+真实规则执行链路保持为：
+
+1. `CcdiBankTagServiceImpl.rebuildProject(...)` 发起重算。
+2. `ruleMapper.selectEnabledRules(modelCode)` 获取启用规则。
+3. `BankTagRuleConfigResolver.resolve(projectId, rule)` 解析项目有效参数。
+4. `executeStatementRule / executeObjectRule` 依据 `rule_code` 分发。
+5. `CcdiBankTagAnalysisMapper.xml` 执行真实 SQL，返回 `STATEMENT` 或 `OBJECT` 命中结果。
+6. Service 将命中结果组装为 `CcdiBankTagResult` 并批量入库。
+7. 调用 `projectOverviewService.refreshProjectRiskCounts(projectId, operator)` 刷新项目风险人数。
+
+### 6.3 规则落地边界
+
+#### 流水明细型规则
+
+输出：
+
+- `bankStatementId`
+- `groupId`
+- `logId`
+- `reasonDetail`
+
+代表规则包括：
+
+- `GAMBLING_SENSITIVE_KEYWORD`
+- `SPECIAL_AMOUNT_TRANSACTION`
+- `SUSPICIOUS_INCOME_KEYWORD`
+- `HOUSE_REGISTRATION_MISMATCH`
+- `PROPERTY_FEE_REGISTRATION_MISMATCH`
+- `TAX_ASSET_REGISTRATION_MISMATCH`
+- `LARGE_PURCHASE_TRANSACTION`
+- `STOCK_TFR_LARGE`
+- `LARGE_STOCK_TRADING`
+- 外汇购汇/结汇规则
+
+#### 对象型规则
+
+输出：
+
+- `objectType`
+- `objectKey`
+- `reasonDetail`
+
+对象维度统一使用员工主键口径：
+
+- `objectType = STAFF_ID_CARD`
+- `objectKey = 员工身份证号`
+
+代表规则包括：
+
+- `LOW_INCOME_RELATIVE_LARGE_TRANSACTION`
+- `MULTI_PARTY_GAMBLING_TRANSFER`
+- `MONTHLY_FIXED_INCOME`
+- `FIXED_COUNTERPARTY_TRANSFER`
+- `SUPPLIER_CONCENTRATION`
+- `WITHDRAW_CNT`
+- `SALARY_QUICK_TRANSFER`
+- `SALARY_UNUSED`
+
+### 6.4 参数策略
+
+参数只通过现有 `ccdi_model_param` 获取，不新增第二参数源。
+
+本次需要补齐的规则参数映射包括：
+
+- `MULTI_PARTY_GAMBLING_TRANSFER` -> `MULTI_PARTY_AMT_MIN`、`MULTI_PARTY_AMT_MAX`
+- `FIXED_COUNTERPARTY_TRANSFER` -> `FIXED_COUNTERPARTY_TRANSFER_MIN`、`FIXED_COUNTERPARTY_TRANSFER_MAX`
+- `SINGLE_PURCHASE_AMOUNT` 对应购汇类单值阈值
+- `SINGLE_SETTLEMENT_AMOUNT` 对应结汇类单值阈值
+- `WITHDRAW_CNT` 对应提现频次阈值
+- `STOCK_TFR_LARGE`、`LARGE_STOCK_TRADING` 等单值阈值按现有参数脚本统一校准
+
+对本身不依赖阈值的规则，不强行补充虚假参数。
+
+### 6.5 错误处理策略
+
+本次不增加补丁式兜底逻辑：
+
+- 真实 SQL 报错：整次打标任务按现有逻辑失败
+- 规则无命中：任务正常成功，命中数为 0
+- 参数缺失：按现有解析结果暴露问题，并通过脚本与测试补齐
+
+## 七、两期拆分设计
+
+### 7.1 第一期设计目标
+
+优先替换依赖简单、回归范围可控的规则，形成第一批真实命中能力。
+
+第一期规则：
+
+- `GAMBLING_SENSITIVE_KEYWORD`
+- `SPECIAL_AMOUNT_TRANSACTION`
+- `SUSPICIOUS_INCOME_KEYWORD`
+- `SINGLE_PURCHASE_AMOUNT`
+- `SINGLE_SETTLEMENT_AMOUNT`
+- `LARGE_PURCHASE_TRANSACTION`
+- `STOCK_TFR_LARGE`
+- `LARGE_STOCK_TRADING`
+- `WITHDRAW_CNT`
+
+第一期特点：
+
+- 单表筛选为主
+- 依赖关系较少
+- 参数映射简单
+- 适合先完成真实 SQL 替换和基础回归
+
+### 7.2 第二期设计目标
+
+完成跨表比对、对象聚合和窗口口径更复杂的规则。
+
+第二期规则：
+
+- `LOW_INCOME_RELATIVE_LARGE_TRANSACTION`
+- `MULTI_PARTY_GAMBLING_TRANSFER`
+- `MONTHLY_FIXED_INCOME`
+- `FIXED_COUNTERPARTY_TRANSFER`
+- `HOUSE_REGISTRATION_MISMATCH`
+- `PROPERTY_FEE_REGISTRATION_MISMATCH`
+- `TAX_ASSET_REGISTRATION_MISMATCH`
+- `SUPPLIER_CONCENTRATION`
+- `SALARY_QUICK_TRANSFER`
+- `SALARY_UNUSED`
+
+第二期特点：
+
+- 跨表比对较多
+- 聚合口径更复杂
+- 对交易时间、关系人口径、资产登记口径更敏感
+
+## 八、测试设计
+
+### 8.1 XML 结构测试
+
+在 `CcdiBankTagAnalysisMapperXmlTest` 中补充：
+
+- 目标规则不再使用 `where 1 = 0`
+- 新增真实 SQL 仍满足 XML 结构合法
+- `STATEMENT` 规则仍返回完整命中字段
+- `OBJECT` 规则仍返回完整命中字段
+
+### 8.2 参数解析测试
+
+在 `BankTagRuleConfigResolverTest` 中补充：
+
+- 新增规则参数映射断言
+- 双阈值规则参数完整性断言
+- 无参数规则仍返回空参数集
+
+### 8.3 Service 分发测试
+
+在 `CcdiBankTagServiceImplTest` 中补充：
+
+- 每条新增规则都能命中正确 Mapper 方法
+- 不再落入默认空分支
+- 真实规则空命中时任务仍可成功结束
+
+### 8.4 受影响链路回归
+
+至少覆盖：
+
+- `CcdiBankTagAnalysisMapperXmlTest`
+- `BankTagRuleConfigResolverTest`
+- `CcdiBankTagServiceImplTest`
+- 受影响的项目风险人数回写与结果总览后端测试
+
+## 九、文档产物
+
+按仓库规范，本次输出以下文档：
+
+1. 本设计文档：
+   - `docs/design/2026-03-20-bank-tag-real-rule-two-phase-design.md`
+2. 第一期后端实施计划：
+   - `docs/plans/backend/2026-03-20-bank-tag-real-rule-phase1-backend-implementation.md`
+3. 第一期前端实施计划：
+   - `docs/plans/frontend/2026-03-20-bank-tag-real-rule-phase1-frontend-implementation.md`
+4. 第二期后端实施计划：
+   - `docs/plans/backend/2026-03-20-bank-tag-real-rule-phase2-backend-implementation.md`
+5. 第二期前端实施计划：
+   - `docs/plans/frontend/2026-03-20-bank-tag-real-rule-phase2-frontend-implementation.md`
+
+其中前端实施计划用于明确边界：
+
+- 本期无前端代码改造
+- 前端仅做依赖说明和联调预期记录
+
+## 十、结论
+
+本方案采用“现有架构内真实替换占位 SQL”的最短路径设计，并将 19 条目标规则拆成两期实施：
+
+- 第一期先处理依赖少、风险低的 9 条规则
+- 第二期再处理聚合与跨表逻辑更重的 10 条规则
+
+这样既满足“一次性完成完整设计”的要求，又能在实施阶段有效控制改动规模和回归风险，不会偏离当前项目既有技术路线。