278 lines
9.6 KiB
Markdown
278 lines
9.6 KiB
Markdown
# LSFX Mock 大额交易命中样本设计
|
||
|
||
## 背景
|
||
|
||
当前 `lsfx-mock-server` 的银行流水接口会返回完全随机的流水数据，但后端银行流水打标中的大额交易模型依赖摘要关键词、收支方向、金额阈值、交易日期，以及 `cretNo` 与员工/家属身份关系的匹配。仅有随机金额和随机摘要不足以稳定命中后端规则，导致联调时即使接口返回成功，后端打标结果仍可能为空。
|
||
|
||
本设计用于调整 Mock 流水生成策略，使其在保留随机噪声数据的同时，稳定产出可命中后端大额交易 8 条规则的样本流水。
|
||
|
||
## 目标
|
||
|
||
- 更新 `lsfx-mock-server` 的银行流水生成逻辑。
|
||
- 每个 `logId` 首次生成流水时，稳定包含可命中大额交易 8 条规则的样本。
|
||
- 在命中样本之外继续混入普通随机流水，保持 Mock 数据的随机感和分页场景。
|
||
- 不修改后端打标实现，以后端现有 SQL 口径作为唯一准绳。
|
||
|
||
## 范围
|
||
|
||
### In Scope
|
||
|
||
- `lsfx-mock-server` 获取银行流水接口的生成逻辑。
|
||
- 大额交易 8 条规则所需的命中样本模板。
|
||
- 对应的 Mock 单元测试与接口测试。
|
||
- 本次改动的实施记录文档。
|
||
|
||
### Out of Scope
|
||
|
||
- 后端 `CcdiBankTagAnalysisMapper.xml` 或打标 Service 逻辑调整。
|
||
- 其他模型组规则的 Mock 命中样本。
|
||
- Mock 服务接入主系统数据库或动态读取后端参数。
|
||
|
||
## 后端规则现状
|
||
|
||
后端当前已实际实现并可命中的大额交易规则为：
|
||
|
||
1. `HOUSE_OR_CAR_EXPENSE`
|
||
2. `TAX_EXPENSE`
|
||
3. `SINGLE_LARGE_INCOME`
|
||
4. `CUMULATIVE_INCOME`
|
||
5. `ANNUAL_TURNOVER`
|
||
6. `LARGE_CASH_DEPOSIT`
|
||
7. `FREQUENT_CASH_DEPOSIT`
|
||
8. `LARGE_TRANSFER`
|
||
|
||
这些规则的关键命中条件总结如下：
|
||
|
||
- 房车消费、税务支出：依赖 `userMemo` 或 `customerName` 的关键词命中，且 `drAmount > 0`。
|
||
- 单笔大额收入、累计收入、年流水、大额转账：依赖员工身份、对手方名称、收支方向、阈值及排除条件。
|
||
- 大额存现、单日多次存现：依赖 `cashType`、`userMemo`、`customerName` 与 `crAmount` 的联合条件。
|
||
- 多条规则要求 `cretNo` 能在后端库中关联到员工或家属，否则规则不会命中。
|
||
|
||
## 关键前提
|
||
|
||
Mock 必须复用一组后端环境中真实可识别的身份证号，否则仅靠金额和摘要无法满足后端 `exists staff/relation` 条件。
|
||
|
||
本次默认复用现有文档中已用于大额交易验证的身份池：
|
||
|
||
- 员工：`330101198801010011`
|
||
- 家属：`330101199001010022`
|
||
- 员工：`330101198802020033`
|
||
- 家属：`330101199202020044`
|
||
|
||
这些身份已在既有大额交易验证文档与种子 SQL 中使用，可作为 Mock 默认命中身份池。若后续目标环境不存在这些身份，需要在样本配置中同步替换。
|
||
|
||
## 设计概览
|
||
|
||
将现有“逐条完全随机生成”的策略调整为“两段式生成”：
|
||
|
||
1. 先生成固定数量的规则命中样本。
|
||
2. 再补充普通随机噪声流水。
|
||
3. 合并后统一排序/洗牌，写入当前 `logId` 缓存。
|
||
4. 分页接口继续基于缓存返回，保证同一 `logId` 多次请求结果一致。
|
||
|
||
## 组件设计
|
||
|
||
### 1. 普通随机流水生成器
|
||
|
||
保留现有随机生成能力，继续负责生成非命中噪声数据。其职责仅限于提供分页场景和背景数据，不承担命中保障。
|
||
|
||
### 2. 大额交易样本生成器
|
||
|
||
新增专用样本生成层，负责生成 8 条规则所需的流水组合。建议拆为独立模块，例如：
|
||
|
||
- `services/statement_rule_samples.py`
|
||
|
||
该模块维护：
|
||
|
||
- 默认身份池
|
||
- 默认阈值常量
|
||
- 每条规则的样本构造函数
|
||
- 公共流水字段构造辅助函数
|
||
|
||
### 3. 汇总与缓存层
|
||
|
||
`statement_service.py` 负责：
|
||
|
||
- 调用大额交易样本生成器获取命中样本
|
||
- 生成指定数量的噪声流水
|
||
- 为所有记录补齐唯一 `bankStatementId`、`bankTrxNumber`、`uploadSequnceNumber`
|
||
- 合并、打乱顺序并缓存
|
||
- 按页返回 `bankStatementList`
|
||
|
||
## 样本组织方案
|
||
|
||
为避免只为单一规则生成孤立流水，8 条规则拆为 5 组样本簇：
|
||
|
||
### A. 房车消费支出样本
|
||
|
||
- 1 至 2 条支出流水
|
||
- `drAmount > 0`
|
||
- `userMemo` 含 `购买房产首付款`、`购车首付款` 等关键词
|
||
- 或 `customerName` 命中 `房地产`、`贝壳`、`汽车销售`、`4S店` 等关键词
|
||
- `cretNo` 使用员工或家属身份证
|
||
|
||
### B. 税务支出样本
|
||
|
||
- 1 至 2 条支出流水
|
||
- `drAmount > 0`
|
||
- `userMemo` 或 `customerName` 命中 `税务`、`税款`、`税务局`、`国库`
|
||
- `cretNo` 使用员工或家属身份证
|
||
|
||
### C. 大额收入样本簇
|
||
|
||
使用同一员工身份证与同一非亲属对手方生成多条收入流水，复用命中：
|
||
|
||
- `SINGLE_LARGE_INCOME`
|
||
- `CUMULATIVE_INCOME`
|
||
- `ANNUAL_TURNOVER`
|
||
|
||
约束如下：
|
||
|
||
- 至少 1 条 `crAmount` 大于 `SINGLE_TRANSACTION_AMOUNT`
|
||
- 多条累计 `crAmount` 大于 `CUMULATIVE_TRANSACTION_AMOUNT`
|
||
- 再叠加大额收入/支出，使近一年累计交易额大于 `ANNUAL_TURNOVER`
|
||
- `leName != customerName`
|
||
- `customerName` 不得映射为该员工家属名称
|
||
- 避开工资排除条件，不能使用 `浙江兰溪农村商业银行股份有限公司`，`userMemo` 也不得含 `代发`、`工资`、`奖金`、`薪酬` 等词
|
||
|
||
### D. 大额存现样本簇
|
||
|
||
使用同一身份证、同一天生成 6 条现金存入流水，复用命中：
|
||
|
||
- `LARGE_CASH_DEPOSIT`
|
||
- `FREQUENT_CASH_DEPOSIT`
|
||
|
||
约束如下：
|
||
|
||
- 每条 `crAmount` 大于 `LARGE_CASH_DEPOSIT`
|
||
- 同日条数大于 `FREQUENT_CASH_DEPOSIT`
|
||
- `cashType` / `userMemo` / `customerName` 的组合需满足后端 `cashDepositPredicate`
|
||
- 推荐使用 `现金存款`、`ATM现金存款`、`自助存款现金存入`、`CRS存款`、`本行ATM存款` 等摘要
|
||
|
||
### E. 大额转账支出样本
|
||
|
||
- 1 至 2 条支出流水
|
||
- `drAmount > FREQUENT_TRANSFER`
|
||
- `userMemo` 含 `手机银行转账`、`对外转账`
|
||
- 或 `cashType` / `customerName` 含转账特征
|
||
- `userMemo` 不能包含 `款`，避免被后端排除
|
||
- `leName != customerName`
|
||
|
||
## 默认阈值策略
|
||
|
||
Mock 不接主系统数据库，因此不动态读取项目参数。为保证命中稳定，样本生成器内置与当前系统默认参数一致的阈值常量：
|
||
|
||
- `SINGLE_TRANSACTION_AMOUNT = 1111`
|
||
- `CUMULATIVE_TRANSACTION_AMOUNT = 50000001`
|
||
- `ANNUAL_TURNOVER = 50000001`
|
||
- `LARGE_CASH_DEPOSIT = 2000001`
|
||
- `FREQUENT_CASH_DEPOSIT = 5`
|
||
- `FREQUENT_TRANSFER = 100001`
|
||
|
||
样本金额应显著高于阈值，避免边界值因格式化或比较方式差异导致误判。
|
||
|
||
## 数据生成细节
|
||
|
||
### 字段稳定要求
|
||
|
||
以下字段不得继续完全随机：
|
||
|
||
- `cretNo`
|
||
- `leName`
|
||
- `customerName`
|
||
- `userMemo`
|
||
- `cashType`
|
||
- `trxDate`
|
||
- `crAmount`
|
||
- `drAmount`
|
||
|
||
它们需要按规则模板构造。
|
||
|
||
### 可以继续随机的字段
|
||
|
||
以下字段可保留随机生成或在模板基础上随机化：
|
||
|
||
- `accountMaskNo`
|
||
- `customerAccountMaskNo`
|
||
- `bankTrxNumber`
|
||
- `balanceAmount`
|
||
- `bank`
|
||
- `customerBank`
|
||
- `uploadSequnceNumber`
|
||
|
||
### 日期策略
|
||
|
||
- `ANNUAL_TURNOVER` 相关样本统一放在当前日期前 12 个月内。
|
||
- `FREQUENT_CASH_DEPOSIT` 相关样本统一放在同一天但不同时间点。
|
||
- 其他样本可分布在近一年内，避免全部集中到同一时刻。
|
||
|
||
### 总量策略
|
||
|
||
- 继续沿用当前 `1200-1500` 的总条数范围。
|
||
- 先生成全部命中样本，再以 `totalCount - sampleCount` 的差值补足噪声流水。
|
||
- 若后续命中样本数量增长超过随机总量下限，应自动以命中样本数作为最小总量，避免截断命中数据。
|
||
|
||
### 排序与分页
|
||
|
||
生成完成后统一打乱顺序，再根据请求分页返回。这样：
|
||
|
||
- 前端仍能看到类似真实的随机顺序
|
||
- 同一 `logId` 由于缓存存在，重复请求时顺序稳定
|
||
|
||
## 错误处理
|
||
|
||
- 若大额交易样本构造失败，直接抛出明确异常，不静默降级为纯随机流水。
|
||
- 这样能避免接口返回正常但后端永远打不中的隐性问题。
|
||
- 不新增复杂容错或回退机制，保持 Mock 行为可预测。
|
||
|
||
## 测试设计
|
||
|
||
至少补充两类验证：
|
||
|
||
### 1. 样本生成测试
|
||
|
||
验证大额交易样本生成器输出满足关键特征：
|
||
|
||
- 存在房车消费关键词支出
|
||
- 存在税务关键词支出
|
||
- 存在单笔超阈值收入
|
||
- 存在同一对手方累计超阈值收入
|
||
- 存在近一年累计交易额超阈值样本
|
||
- 存在同日 6 笔以上现金存入
|
||
- 存在单笔存现超阈值
|
||
- 存在单笔转账支出超阈值且摘要不含 `款`
|
||
|
||
### 2. 接口返回测试
|
||
|
||
调用 `getBSByLogId`，验证：
|
||
|
||
- 返回总数正常
|
||
- `bankStatementList` 中能找到各类命中样本特征
|
||
- 同一 `logId` 多次请求返回相同数据
|
||
- 分页拼接后的全量结果仍包含全部命中样本
|
||
|
||
## 成功标准
|
||
|
||
- Mock 每次首次生成流水时都稳定包含大额交易 8 条规则所需样本。
|
||
- 同一 `logId` 多次分页请求数据一致。
|
||
- 在默认身份池存在于目标环境的前提下，后端接入 Mock 返回数据后，现有大额交易 8 条规则可以被正确命中。
|
||
- 普通随机噪声流水仍然存在，不退化为完全固定数据集。
|
||
|
||
## 风险与约束
|
||
|
||
- 默认身份池依赖后端环境已有对应员工/家属数据；若环境不一致，需要替换身份池常量。
|
||
- Mock 使用内置阈值，若后端系统默认参数未来变更，Mock 也需要同步更新。
|
||
- 若后端 SQL 规则继续演进，本设计中的样本关键词和排除词也要同步校准。
|
||
|
||
## 实施输出
|
||
|
||
实施阶段应至少产出：
|
||
|
||
- Mock 代码改动
|
||
- 对应测试用例
|
||
- 一份前端实施计划
|
||
- 一份后端实施计划
|
||
- 一份实施记录文档
|
||
|
||
其中前后端实施计划用于说明联调影响面：本次主要改动在 Mock 服务，但后端计划中需要明确验证路径和命中校验方式。
|