399 lines
13 KiB
Markdown
399 lines
13 KiB
Markdown
# 兰溪流水 Mock 随机命中规则设计文档
|
||
|
||
**模块**: `lsfx-mock-server`
|
||
**日期**: 2026-03-20
|
||
|
||
## 一、背景
|
||
|
||
当前 `lsfx-mock-server` 已接通以下主链路：
|
||
|
||
1. `getJZFileOrZjrcuFile` 创建 `logId` 并保存主绑定、员工及亲属身份范围
|
||
2. `getBSByLogId` 按 `logId` 生成流水并分页返回
|
||
3. 同一 `logId` 首次生成的流水结果会缓存，后续分页查询保持稳定
|
||
|
||
现有问题有两类：
|
||
|
||
1. 大额交易命中样本当前为固定全量注入，不符合“随机命中一部分”的联调需求
|
||
2. 第一期新增真实规则虽然已在主项目后端落地，但 `lsfx-mock-server` 还没有对应的随机命中样本，导致“获取流水列表并存储到兰溪本地”这条链路无法稳定覆盖新增规则
|
||
|
||
本次需求要求：
|
||
|
||
1. 大额交易和新增第一期规则都改为随机命中一部分
|
||
2. 随机结果对同一个 `logId` 必须稳定，不能每次查询重新变化
|
||
3. `getJZFileOrZjrcuFile -> getBSByLogId` 生成出的流水可以被兰溪本地接口正确存储
|
||
4. 必要时允许直接修改关联数据库最小量数据，使新增模型可以正确打标
|
||
|
||
## 二、目标
|
||
|
||
本次设计目标如下：
|
||
|
||
1. 将 `lsfx-mock-server` 的固定全量命中样本改造成“按 `logId` 稳定随机命中规则子集”
|
||
2. 保持现有 `FileService -> StatementService -> cache` 主链路不变
|
||
3. 将样本职责拆到“规则命中计划”和“规则样本拼装”两个层次，避免随机逻辑散落
|
||
4. 让大额交易模型与第一期新增规则都具备“随机命中一部分”的流水样本
|
||
5. 对无法通过银行流水接口伪造的规则，采用最小数据库基线补齐，不增加兼容性补丁链路
|
||
|
||
## 三、范围
|
||
|
||
### 3.1 本次范围
|
||
|
||
- 修改 `lsfx-mock-server/services/file_service.py`
|
||
- 修改 `lsfx-mock-server/services/statement_service.py`
|
||
- 修改 `lsfx-mock-server/services/statement_rule_samples.py`
|
||
- 修改 `lsfx-mock-server` 相关单元测试与集成测试
|
||
- 按最小范围调整关联数据库中的基线业务数据，使非流水表规则可被正确打标
|
||
- 补充设计文档与后续实施计划文档
|
||
|
||
### 3.2 不在本次范围
|
||
|
||
- 不新增新的 Mock 服务模块
|
||
- 不把 Mock 服务改造成实时从数据库拼装整套流水
|
||
- 不改造主项目银行流水打标架构
|
||
- 不引入兼容性双轨逻辑
|
||
- 不为前端新增页面或交互
|
||
|
||
## 四、现状分析
|
||
|
||
### 4.1 Mock 服务现状
|
||
|
||
当前 `lsfx-mock-server` 中：
|
||
|
||
- `FileService.fetch_inner_flow()` 负责生成 `logId`、主绑定、日期范围和员工亲属身份
|
||
- `StatementService._generate_statements()` 会混入固定大额交易命中样本，再补随机噪声流水
|
||
- `StatementService.get_bank_statement()` 首次生成后缓存 200 条流水，同一 `logId` 分页结果稳定
|
||
|
||
这套结构已经满足“同一 `logId` 查询稳定”的基础要求，但样本生成仍是“默认全量命中”，不满足当前需求。
|
||
|
||
### 4.2 主项目规则现状
|
||
|
||
根据 [docs/plans/backend/2026-03-20-bank-tag-real-rule-phase1-backend-implementation.md](/Users/wkc/Desktop/ccdi/ccdi/docs/plans/backend/2026-03-20-bank-tag-real-rule-phase1-backend-implementation.md) 与 [docs/design/2026-03-20-bank-tag-real-rule-two-phase-design.md](/Users/wkc/Desktop/ccdi/ccdi/docs/design/2026-03-20-bank-tag-real-rule-two-phase-design.md)，第一期真实规则已覆盖：
|
||
|
||
- `GAMBLING_SENSITIVE_KEYWORD`
|
||
- `SPECIAL_AMOUNT_TRANSACTION`
|
||
- `SUSPICIOUS_INCOME_KEYWORD`
|
||
- `FOREX_BUY_AMT`
|
||
- `FOREX_SELL_AMT`
|
||
- `LARGE_PURCHASE_TRANSACTION`
|
||
- `STOCK_TFR_LARGE`
|
||
- `LARGE_STOCK_TRADING`
|
||
- `WITHDRAW_CNT`
|
||
|
||
其中：
|
||
|
||
- `GAMBLING_SENSITIVE_KEYWORD`
|
||
- `SPECIAL_AMOUNT_TRANSACTION`
|
||
- `SUSPICIOUS_INCOME_KEYWORD`
|
||
- `FOREX_BUY_AMT`
|
||
- `FOREX_SELL_AMT`
|
||
- `STOCK_TFR_LARGE`
|
||
- `LARGE_STOCK_TRADING`
|
||
- `WITHDRAW_CNT`
|
||
|
||
都可以通过 Mock 银行流水直接构造命中条件。
|
||
|
||
但 `LARGE_PURCHASE_TRANSACTION` 的真实 SQL 查询的是 `ccdi_purchase_transaction`，不是 `ccdi_bank_statement`，因此不适合伪造成银行流水命中。
|
||
|
||
### 4.3 本次关键约束
|
||
|
||
用户已明确确认以下约束：
|
||
|
||
1. 大额交易和新增第一期规则都改为随机命中一部分，而不是固定全量命中
|
||
2. 随机结果采用“同一个 `logId` 首次生成时随机决定，后续保持不变”
|
||
|
||
因此本次设计必须同时满足：
|
||
|
||
- 有随机性
|
||
- 可复现
|
||
- 可测试
|
||
- 不因重复查询导致结果漂移
|
||
|
||
## 五、方案对比
|
||
|
||
### 5.1 方案 A：按规则包稳定随机命中，推荐
|
||
|
||
做法：
|
||
|
||
- 把“大额交易”和“第一期新增规则”拆成多个独立规则包
|
||
- `fetch_inner_flow()` 生成 `logId` 时，基于 `logId` 计算一份稳定的规则命中计划
|
||
- `getBSByLogId` 首次查该 `logId` 时，根据命中计划拼装命中样本并补噪声流水
|
||
|
||
优点：
|
||
|
||
- 同一 `logId` 结果稳定
|
||
- 不同 `logId` 命中子集不同，随机性自然
|
||
- 可以按规则粒度精确控制命中范围
|
||
- 测试可以直接断言“规则命中计划稳定”
|
||
|
||
缺点：
|
||
|
||
- 需要把现有固定全量样本生成器改造成可按规则装配的结构
|
||
|
||
### 5.2 方案 B：按场景模板随机命中
|
||
|
||
做法：
|
||
|
||
- 预置若干整套场景模板，如“偏大额交易”“偏新增规则”“混合命中”
|
||
- 每个 `logId` 只随机选择一套模板
|
||
|
||
优点：
|
||
|
||
- 实现快
|
||
|
||
缺点：
|
||
|
||
- 随机粒度粗
|
||
- 容易出现某些规则长期捆绑命中，不够贴近真实联调需求
|
||
|
||
### 5.3 方案 C：重度依赖数据库动态拼装流水
|
||
|
||
做法：
|
||
|
||
- 先写大量数据库测试数据
|
||
- Mock 服务每次从数据库读取对象关系与业务记录，再动态拼装流水
|
||
|
||
优点：
|
||
|
||
- 表面上更接近生产链路
|
||
|
||
缺点：
|
||
|
||
- 耦合高，调试成本大
|
||
- 超出本次最短路径要求
|
||
- 会把 Mock 服务从“可控样本生成器”变成“数据库依赖型服务”
|
||
|
||
### 5.4 结论
|
||
|
||
采用方案 A。
|
||
|
||
## 六、总体设计
|
||
|
||
### 6.1 设计原则
|
||
|
||
1. 随机决策只在 `FileService` 做一次
|
||
2. 流水生成只在 `StatementService` 做一次并缓存
|
||
3. 样本模板只在 `statement_rule_samples.py` 维护
|
||
4. 不新增新的服务层或中间模块
|
||
5. 对不能通过银行流水构造的规则，使用最小数据库基线补齐
|
||
|
||
### 6.2 数据流
|
||
|
||
改造后的数据流如下：
|
||
|
||
1. `getJZFileOrZjrcuFile` 调用 `FileService.fetch_inner_flow()`
|
||
2. `FileService` 创建 `FileRecord` 时，基于 `logId` 生成并保存规则命中计划
|
||
3. `getBSByLogId` 调用 `StatementService.get_bank_statement()`
|
||
4. `StatementService` 首次查询该 `logId` 时，从 `FileRecord` 读取命中计划
|
||
5. `statement_rule_samples.py` 根据命中计划生成对应规则样本
|
||
6. `StatementService` 再补足噪声流水到固定 200 条
|
||
7. 首次生成的结果缓存到内存，后续分页继续复用同一份流水
|
||
|
||
### 6.3 规则命中计划设计
|
||
|
||
规则命中计划按两大类保存：
|
||
|
||
- `largeTransactionHitRules`
|
||
- `phase1HitRules`
|
||
|
||
规则命中计划保存的是规则代码集合，不保存具体流水明细。
|
||
|
||
同一个 `logId` 的命中计划由固定种子生成，例如：
|
||
|
||
- `Random("rule-plan:{logId}")`
|
||
|
||
由此保证：
|
||
|
||
- 同一个 `logId` 命中子集稳定
|
||
- 不同 `logId` 命中子集大概率不同
|
||
|
||
### 6.4 职责划分
|
||
|
||
#### `FileService`
|
||
|
||
职责：
|
||
|
||
- 创建 `logId`
|
||
- 绑定主体、账号、员工及亲属身份
|
||
- 生成并保存规则命中计划
|
||
|
||
不负责：
|
||
|
||
- 生成具体流水明细
|
||
- 执行规则样本拼装
|
||
|
||
#### `StatementService`
|
||
|
||
职责：
|
||
|
||
- 首次读取 `logId` 时，根据规则命中计划生成流水
|
||
- 补足噪声流水
|
||
- 分页返回并缓存结果
|
||
|
||
不负责：
|
||
|
||
- 决定本次命中哪些规则
|
||
|
||
#### `statement_rule_samples.py`
|
||
|
||
职责：
|
||
|
||
- 按规则代码生成对应命中样本
|
||
- 提供统一入口，按命中计划拼装样本集合
|
||
|
||
不负责：
|
||
|
||
- 随机选择规则
|
||
- 缓存或分页
|
||
|
||
## 七、规则包设计
|
||
|
||
### 7.1 大额交易规则包
|
||
|
||
保留现有已实现的大额交易命中样本，但改为按规则粒度单独开关，不再默认全量注入。
|
||
|
||
每条规则对应一个独立样本 builder，由命中计划决定是否加入。
|
||
|
||
### 7.2 第一期新增规则包
|
||
|
||
本次通过银行流水构造的第一期规则包为：
|
||
|
||
- `GAMBLING_SENSITIVE_KEYWORD`
|
||
- `SPECIAL_AMOUNT_TRANSACTION`
|
||
- `SUSPICIOUS_INCOME_KEYWORD`
|
||
- `FOREX_BUY_AMT`
|
||
- `FOREX_SELL_AMT`
|
||
- `STOCK_TFR_LARGE`
|
||
- `LARGE_STOCK_TRADING`
|
||
- `WITHDRAW_CNT`
|
||
|
||
每个规则包只生成命中该规则所需的最小流水集合，不附带额外未请求逻辑。
|
||
|
||
### 7.3 `LARGE_PURCHASE_TRANSACTION` 边界
|
||
|
||
`LARGE_PURCHASE_TRANSACTION` 不放入 Mock 银行流水规则包中，原因如下：
|
||
|
||
1. 主项目真实 SQL 查询来源是 `ccdi_purchase_transaction`
|
||
2. `getBSByLogId` 返回的是银行流水，无法自然映射采购业务表
|
||
3. 若将其伪造成银行流水命中，会偏离真实打标逻辑
|
||
|
||
因此该规则采用“数据库最小基线补齐”的方式处理，不强行混入 Mock 流水。
|
||
|
||
## 八、随机策略设计
|
||
|
||
### 8.1 随机约束
|
||
|
||
为避免“完全不命中”或“一次性全命中”的极端情况，本次采用有边界的随机策略：
|
||
|
||
- 大额交易规则包：随机命中 2 到 4 条
|
||
- 第一期新增流水规则包：随机命中 2 到 4 条
|
||
- 两大类都至少命中 1 条
|
||
- `WITHDRAW_CNT` 允许独立命中，不要求与明细型规则绑定
|
||
|
||
未命中的规则不生成伪样本，只保留普通噪声流水。
|
||
|
||
### 8.2 稳定性要求
|
||
|
||
同一个 `logId`：
|
||
|
||
- 首次生成命中计划后固定不变
|
||
- 首次生成流水后缓存结果固定不变
|
||
- 后续分页查询不得重新随机
|
||
|
||
## 九、数据库基线设计
|
||
|
||
### 9.1 可直接复用的数据
|
||
|
||
继续复用当前 `StaffIdentityRepository` 从真实数据库读取的：
|
||
|
||
- 员工身份证
|
||
- 有效亲属身份证
|
||
|
||
这部分已经满足 `SPECIAL_AMOUNT_TRANSACTION`、`WITHDRAW_CNT` 等规则的对象关系基础。
|
||
|
||
### 9.2 需要最小补齐的数据
|
||
|
||
只补齐真实打标必需、但无法通过 Mock 流水自然构造的最小数据：
|
||
|
||
1. 若被选中的员工缺少足够的亲属关系区分数据，则补齐最小亲属关系记录，确保能区分“配偶/子女”和“非配偶子女”
|
||
2. 为 `LARGE_PURCHASE_TRANSACTION` 补最小量 `ccdi_purchase_transaction` 业务数据，使真实 SQL 可命中
|
||
|
||
### 9.3 明确不做的事
|
||
|
||
- 不大规模预置 `ccdi_bank_statement`
|
||
- 不让 Mock 服务实时依赖数据库生成整套流水
|
||
- 不为数据库不存在的业务链路追加补丁式兼容方案
|
||
|
||
## 十、错误处理
|
||
|
||
1. 若数据库中无法读取员工及亲属身份，保持现有失败语义，直接暴露错误
|
||
2. 若某次规则命中计划生成异常，不写入 `FileRecord`
|
||
3. 若 `getBSByLogId` 首次生成流水失败，不写入缓存，避免脏缓存
|
||
4. 若某类规则本次未被随机命中，不视为错误，只是本次子集未覆盖
|
||
5. `LARGE_PURCHASE_TRANSACTION` 不因未出现在 Mock 流水中而报错，其命中依赖数据库基线数据
|
||
|
||
## 十一、测试设计
|
||
|
||
### 11.1 `tests/test_file_service.py`
|
||
|
||
验证：
|
||
|
||
- `fetch_inner_flow()` 会生成并保存规则命中计划
|
||
- 同一 `logId` 的命中计划稳定
|
||
- 命中计划中同时包含大额交易与第一期新增规则两类结果
|
||
|
||
### 11.2 `tests/test_statement_service.py`
|
||
|
||
验证：
|
||
|
||
- 按命中计划只生成对应规则子集样本，而不是固定全量命中
|
||
- 同一 `logId` 重复查询时结果不漂移
|
||
- 不同 `logId` 大概率得到不同命中子集
|
||
- 命中规则对应的样本字段能被主项目真实 SQL 识别
|
||
|
||
### 11.3 `tests/integration/test_full_workflow.py`
|
||
|
||
验证：
|
||
|
||
- `getJZFileOrZjrcuFile -> getBSByLogId` 主链路可正常返回
|
||
- 返回结果既包含随机命中样本，也包含普通噪声流水
|
||
- 上传状态与流水接口仍共享同一主绑定信息
|
||
|
||
### 11.4 数据库基线验证
|
||
|
||
对 `LARGE_PURCHASE_TRANSACTION` 单独验证：
|
||
|
||
- 基线业务数据补齐后，主项目真实规则 SQL 可命中
|
||
- 不将该规则混入 Mock 流水命中断言
|
||
|
||
## 十二、实施与文档要求
|
||
|
||
后续进入实施计划阶段时，本次仅产出后端实施计划文档：
|
||
|
||
1. 后端实施计划：`docs/plans/backend/`
|
||
|
||
原因如下：
|
||
|
||
- 本次改造范围仅涉及 `lsfx-mock-server`、相关测试与最小数据库基线补齐
|
||
- 不涉及前端页面、接口封装、交互或展示调整
|
||
- 用户已明确要求本次只需要后端实施计划
|
||
|
||
后端实施计划需覆盖：
|
||
|
||
- `lsfx-mock-server` 随机命中规则改造
|
||
- 单元测试与集成测试调整
|
||
- `LARGE_PURCHASE_TRANSACTION` 相关数据库基线补齐
|
||
- 实施记录与验证记录沉淀
|
||
|
||
同时补充实施记录文档，记录本次具体改动内容与验证结果。
|
||
|
||
## 十三、结论
|
||
|
||
本次采用“按 `logId` 稳定随机命中规则包”的方式改造 `lsfx-mock-server`：
|
||
|
||
- 保留现有主链路
|
||
- 不新增模块
|
||
- 不引入补丁式兼容方案
|
||
- 让大额交易和第一期新增规则都能随机命中一部分
|
||
- 对同一个 `logId` 保持稳定、可复现、可联调
|
||
|
||
对无法通过银行流水自然构造的 `LARGE_PURCHASE_TRANSACTION`，采用最小数据库基线补齐，不伪造银行流水，以确保整个方案逻辑正确并与主项目真实打标链路一致。
|