286 lines
9.0 KiB
Markdown
286 lines
9.0 KiB
Markdown
# LSFX Mock Server 异常账户命中流水设计文档
|
||
|
||
**模块**: `lsfx-mock-server`
|
||
**日期**: 2026-03-31
|
||
|
||
## 一、背景
|
||
|
||
当前仓库中的异常账户模型已经在主系统后端完成规则接入，包含以下两条对象型规则：
|
||
|
||
- `SUDDEN_ACCOUNT_CLOSURE`
|
||
- `DORMANT_ACCOUNT_LARGE_ACTIVATION`
|
||
|
||
根据已落地的后端实施计划与实现结果，这两条规则的命中依赖两类事实：
|
||
|
||
1. 账户事实：来自 `ccdi_account_info` 的账户状态、开户日、销户日、账户归属人
|
||
2. 流水事实：来自 `ccdi_bank_statement` 的账号维度交易时间与交易金额
|
||
|
||
当前 [lsfx-mock-server](/Users/wkc/Desktop/ccdi/ccdi/lsfx-mock-server) 已具备以下能力：
|
||
|
||
- `FileService` 为每个 `logId` 生成稳定的规则命中计划
|
||
- `StatementService` 根据命中计划拼接规则样本流水
|
||
- `/watson/api/project/getBSByLogId` 返回分页流水列表
|
||
|
||
但 Mock 服务现阶段尚未支持异常账户模型对应的“账户事实 + 命中流水”闭环，因此后端即使接入了真实规则 SQL，也无法通过现有 Mock 数据稳定命中异常账户规则。
|
||
|
||
本次目标是在不改动现有接口协议的前提下，为 `lsfx-mock-server` 补齐异常账户规则的最小闭环造数能力，让同一个 `logId` 下既有可命中后端 SQL 的账户事实，也有与之匹配的流水样本。
|
||
|
||
## 二、目标
|
||
|
||
- 在现有 Mock 规则计划体系中新增异常账户命中计划。
|
||
- 为每个命中异常账户规则的 `logId` 生成稳定的异常账户事实。
|
||
- 按后端 SQL 口径生成两条规则对应的流水样本。
|
||
- 保持现有 `/watson/api/project/getBSByLogId` 返回结构不变。
|
||
- 保持现有 `FileService -> StatementService` 主链路不变，不引入平行造数机制。
|
||
- 补充测试，确保命中计划、账户事实和流水样本三者一致。
|
||
|
||
## 三、非目标
|
||
|
||
- 不新增异常账户独立接口。
|
||
- 不修改现有上传、拉取行内流水、查询流水接口的请求参数与响应结构。
|
||
- 不对外直接返回异常账户事实列表。
|
||
- 不模拟 `ccdi_account_info` 全字段，只保留两条规则所需最小字段。
|
||
- 不扩展异常账户详情页、分页查询或导出链路。
|
||
- 不引入动态配置平台、DSL 或补丁式兼容逻辑。
|
||
|
||
## 四、方案对比
|
||
|
||
### 4.1 方案一：并入现有 `rule_hit_plan` 体系
|
||
|
||
做法：
|
||
|
||
- 在 `FileRecord` 中新增异常账户命中计划与账户事实
|
||
- 在 `build_seed_statements_for_rule_plan(...)` 中接入异常账户样本生成
|
||
- `StatementService` 继续统一补噪声、编号、分页
|
||
|
||
优点：
|
||
|
||
- 完全复用当前 Mock 主链路
|
||
- 同一个 `logId` 下规则计划、账户事实、流水样本天然一致
|
||
- 实现路径最短，后续联调稳定
|
||
|
||
缺点：
|
||
|
||
- 需要在 `FileRecord` 中增加一层最小账户事实建模
|
||
|
||
### 4.2 方案二：仅在 `StatementService` 中硬编码异常账户流水样本
|
||
|
||
优点：
|
||
|
||
- 改动最少，实现最快
|
||
|
||
缺点：
|
||
|
||
- 命中流水和账户事实分离
|
||
- 后续若需要调试命中原因或扩展账户事实，维护成本较高
|
||
|
||
### 4.3 方案三：新增独立异常账户服务模块
|
||
|
||
优点：
|
||
|
||
- 抽象边界更清晰
|
||
|
||
缺点：
|
||
|
||
- 对当前 Mock 项目来说偏重
|
||
- 超出最短路径实现要求
|
||
|
||
## 五、结论
|
||
|
||
采用方案一。
|
||
|
||
原因如下：
|
||
|
||
- 与当前 Mock 服务的规则计划机制完全一致
|
||
- 不新增接口、不增加平行数据流
|
||
- 能以最小改动实现“账户事实 + 命中流水”的稳定闭环
|
||
- 后续若主系统还需要继续扩展 Mock 规则样本，可以沿用同一套结构
|
||
|
||
## 六、总体设计
|
||
|
||
### 6.1 新增命中计划维度
|
||
|
||
在现有规则计划结构上新增：
|
||
|
||
- `abnormal_account_hit_rules`
|
||
|
||
规则池固定为：
|
||
|
||
- `SUDDEN_ACCOUNT_CLOSURE`
|
||
- `DORMANT_ACCOUNT_LARGE_ACTIVATION`
|
||
|
||
`FileService` 在为 `logId` 生成规则计划时，继续沿用现有“稳定随机且可复现”的逻辑，把异常账户规则作为平级维度一起生成并回填到 `FileRecord`。
|
||
|
||
### 6.2 新增最小账户事实
|
||
|
||
`FileRecord` 新增以下字段：
|
||
|
||
- `abnormal_account_hit_rules: List[str]`
|
||
- `abnormal_accounts: List[AbnormalAccountFact]`
|
||
|
||
其中 `AbnormalAccountFact` 仅保留两条规则需要的最小字段：
|
||
|
||
- `account_no`
|
||
- `owner_id_card`
|
||
- `account_name`
|
||
- `status`
|
||
- `effective_date`
|
||
- `invalid_date`
|
||
|
||
说明：
|
||
|
||
- 本次不复制主系统 `ccdi_account_info` 全量结构
|
||
- 只保留命中 SQL 真正会用到的事实，避免过度设计
|
||
|
||
### 6.3 样本流水接入位置
|
||
|
||
现有 `StatementService` 已通过 `build_seed_statements_for_rule_plan(...)` 生成规则样本流水。
|
||
|
||
本次改造保持该入口不变，仅在其内部追加异常账户规则样本构造：
|
||
|
||
- `build_sudden_account_closure_samples(...)`
|
||
- `build_dormant_account_large_activation_samples(...)`
|
||
|
||
生成出的异常账户样本与其他规则样本一起组成 `seeded_statements`，之后继续复用现有逻辑：
|
||
|
||
1. 补足噪声流水
|
||
2. 统一分配流水编号
|
||
3. 打乱顺序
|
||
4. 分页返回
|
||
|
||
## 七、规则口径设计
|
||
|
||
### 7.1 `SUDDEN_ACCOUNT_CLOSURE`
|
||
|
||
Mock 口径必须与后端 SQL 对齐：
|
||
|
||
- 账户状态为 `2`
|
||
- `invalid_date` 非空
|
||
- 流水账号与账户事实中的 `account_no` 一致
|
||
- 所有命中样本流水时间都落在 `[invalid_date - 30天, invalid_date)` 区间内
|
||
|
||
样本策略：
|
||
|
||
- 为单个命中账户生成 2 到 3 笔流水
|
||
- 同时覆盖收入和支出，便于后端聚合 `windowTotalAmount`
|
||
- 保证存在明确的最后交易日，便于推导 `lastTxDate`
|
||
- 保证存在稳定的单笔最大金额，便于推导 `windowMaxSingleAmount`
|
||
|
||
### 7.2 `DORMANT_ACCOUNT_LARGE_ACTIVATION`
|
||
|
||
Mock 口径必须与后端 SQL 对齐：
|
||
|
||
- 账户状态为 `1`
|
||
- `effective_date` 非空
|
||
- 首笔流水日期 `>= effective_date + 6个月`
|
||
- 启用后流水满足：
|
||
- `windowTotalAmount >= 500000`
|
||
- 或 `windowMaxSingleAmount >= 100000`
|
||
|
||
样本策略：
|
||
|
||
- 首笔流水明确落在开户满 6 个月以后
|
||
- 为避免边界漂移，直接让累计金额和单笔最大金额同时满足阈值
|
||
- 启用后生成 2 笔以上流水，保证累计口径稳定
|
||
|
||
### 7.3 未命中规则时的处理
|
||
|
||
当某个 `logId` 的 `abnormal_account_hit_rules` 中不包含某条规则时：
|
||
|
||
- 不生成该规则的账户事实
|
||
- 不生成该规则的流水样本
|
||
- 不制造“接近命中但未命中”的灰度样本
|
||
|
||
这样可以避免误命中，保证 Mock 语义清晰。
|
||
|
||
## 八、数据流设计
|
||
|
||
本次改造后的数据流如下：
|
||
|
||
1. `FileService.fetch_inner_flow(...)` 或上传链路创建 `FileRecord`
|
||
2. `FileService` 生成四类命中计划：
|
||
- `large_transaction_hit_rules`
|
||
- `phase1_hit_rules`
|
||
- `phase2_statement_hit_rules`
|
||
- `abnormal_account_hit_rules`
|
||
3. `FileService` 根据异常账户命中计划生成 `abnormal_accounts`
|
||
4. `StatementService._generate_statements(...)` 读取 `FileRecord`
|
||
5. `build_seed_statements_for_rule_plan(...)` 依据异常账户命中计划拼接对应样本流水
|
||
6. 服务层继续补噪声并返回现有结构的流水列表
|
||
|
||
结论：
|
||
|
||
- 内部多了一层异常账户事实
|
||
- 对外接口保持不变
|
||
|
||
## 九、模块与职责
|
||
|
||
### 9.1 `lsfx-mock-server/services/file_service.py`
|
||
|
||
职责调整：
|
||
|
||
- 扩展 `FileRecord`
|
||
- 生成并保存 `abnormal_account_hit_rules`
|
||
- 按命中规则生成对应 `abnormal_accounts`
|
||
- 保证同一 `logId` 下账户事实稳定可复现
|
||
|
||
### 9.2 `lsfx-mock-server/services/statement_rule_samples.py`
|
||
|
||
职责调整：
|
||
|
||
- 新增异常账户事实结构
|
||
- 新增两类异常账户样本构造器
|
||
- 在统一种子流水构造入口中接入异常账户样本
|
||
|
||
### 9.3 `lsfx-mock-server/services/statement_service.py`
|
||
|
||
职责保持不变，仅消费新增计划与样本：
|
||
|
||
- 读取 `FileRecord` 中的异常账户计划
|
||
- 调用种子样本生成器
|
||
- 继续完成补噪声、编号、缓存、分页返回
|
||
|
||
## 十、测试设计
|
||
|
||
测试分为三层：
|
||
|
||
### 10.1 计划层测试
|
||
|
||
验证点：
|
||
|
||
- `FileRecord` 能保存 `abnormal_account_hit_rules`
|
||
- 生成的异常账户计划稳定、可复现
|
||
- 命中计划与账户事实数量、规则类型一致
|
||
|
||
### 10.2 样本层测试
|
||
|
||
验证点：
|
||
|
||
- `SUDDEN_ACCOUNT_CLOSURE` 样本流水日期全部处于销户前 30 天窗口内
|
||
- `DORMANT_ACCOUNT_LARGE_ACTIVATION` 首笔流水日期晚于开户满 6 个月
|
||
- 休眠账户样本的累计金额和单笔最大金额达到后端 SQL 阈值
|
||
|
||
### 10.3 服务层测试
|
||
|
||
验证点：
|
||
|
||
- `StatementService._generate_statements(...)` 能把异常账户样本混入返回流水
|
||
- 未命中的异常账户规则不会污染其他 `logId`
|
||
- 同一个 `logId` 重复查询时缓存结果保持稳定
|
||
|
||
## 十一、风险与约束
|
||
|
||
- 本次不改协议，因此异常账户事实仅在 Mock 服务内部使用
|
||
- 由于不新增独立接口，联调时仍需通过现有流水接口间接触发后端规则命中
|
||
- 样本日期和金额必须严格贴后端 SQL 口径，避免出现“Mock 看起来合理但后端不命中”的问题
|
||
|
||
## 十二、后续计划
|
||
|
||
本设计确认后，下一步仅进入实施计划编写阶段，不直接扩展其他功能。
|
||
|
||
按仓库约定，需要继续补充：
|
||
|
||
- 后端实施计划
|
||
- 前端实施计划
|
||
- 本次改动的实施记录
|