# 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 看起来合理但后端不命中”的问题 ## 十二、后续计划 本设计确认后，下一步仅进入实施计划编写阶段，不直接扩展其他功能。 按仓库约定，需要继续补充： - 后端实施计划 - 前端实施计划 - 本次改动的实施记录