# 银行流水模型补齐占位设计

## 背景

当前项目的银行流水打标能力已经具备基础框架，包括：

- 规则定义表 `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_CUSTOMER_TRANSACTION`
- `TAX_ASSET_REGISTRATION_MISMATCH`

这样可确保编码既稳定可读，又能直接体现规则指标语义，避免仅靠数字序号区分规则。

### 自动补齐字段规则

- `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. 按规则粒度补测试

无需再次调整规则框架、结果表、任务调度和规则定义结构。
