# 兰溪流水 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`，采用最小数据库基线补齐，不伪造银行流水，以确保整个方案逻辑正确并与主项目真实打标链路一致。
