wkc/ccdi

Fork 0

Files

wkc ad88dc4c47 补充 lsfx 命中模式切换设计文档

2026-03-22 12:40:03 +08:00

6.6 KiB

Raw Blame History

lsfx Mock 规则命中模式切换设计

1. 背景

lsfx-mock-server 当前在生成流水命中计划时，默认按 log_id 稳定随机抽取规则子集。现需要在保持默认行为不变的前提下，支持通过启动命令切换到“全部兼容规则命中”模式，便于联调时一次性覆盖更多规则。

本次设计仅面向 Mock 服务，不涉及主 Java 工程、前端页面或真实规则引擎逻辑调整。

2. 目标与范围

2.1 目标

默认启动时继续使用现有“随机子集命中”逻辑
支持通过命令行参数切换命中模式
普通启动与热重载启动都支持命中模式切换
在“全部兼容规则命中”模式下，避免互斥规则同时出现
保持现有流水生成、命中计划持久化、基线补齐链路不变

2.2 非目标

不修改任意规则编码、样本构造规则、流水拼装顺序
不新增第三种命中模式
不兼容原生 uvicorn main:app ... 直接附带自定义业务参数的形式
不改前端、不改主系统后端接口

3. 术语定义

3.1 `subset`

默认模式。沿用当前逻辑，按 log_id 稳定随机抽取每类规则池中的部分规则，保证同一 log_id 结果稳定。

3.2 `all`

“全部兼容规则命中”模式。该模式不是字面意义上的“无条件命中全部规则”，而是：

优先命中当前已实现的全部可共存规则
若存在显式定义的互斥规则组，则每个互斥组仅保留一个固定代表规则
最终返回的命中计划必须稳定、可解释、可测试

对外文案统一使用“全部兼容规则命中”，避免误解为无约束全开。

4. 现状分析

当前规则命中计划由 services/file_service.py 中的 _build_rule_hit_plan(log_id) 负责生成：

使用 random.Random(f"rule-plan:{log_id}") 保证稳定性
分别为四类规则池抽取 2 到 4 条规则
生成结果写入 FileRecord
后续流水样本生成与第二期基线补齐均消费这份 rule_plan

当前启动入口 main.py 未解析业务命令行参数，配置由 config/settings.py 基于 BaseSettings 读取。

5. 设计方案

5.1 总体思路

将“规则命中模式”收敛为统一配置，由启动层负责解析命令行参数并注入配置，由规则计划编排层根据模式生成最终 rule_plan。

整体链路如下：

启动命令读取 --rule-hit-mode
启动层将模式值写入进程配置
settings 暴露统一的 RULE_HIT_MODE
FileService 根据模式生成规则命中计划
后续流水生成、基线补齐继续复用该计划

这样只改变“命中计划如何生成”，不改变“命中计划如何被使用”。

5.2 配置设计

在 config/settings.py 中新增：

RULE_HIT_MODE: str = "subset"

可选值仅允许：

subset
all

非法值在启动阶段直接报错并退出，不做自动兜底。

5.3 启动设计

保留两类启动方式：

普通启动

python main.py --rule-hit-mode all

热重载启动

新增项目级启动脚本，例如：

python dev.py --reload --rule-hit-mode all

设计上不再要求裸命令 uvicorn main:app --reload ... 直接支持业务参数。README 中将明确推荐项目脚本作为热重载入口。

5.4 规则计划编排设计

规则计划生成逻辑拆分为两层：

基础规则池定义
模式对应的计划编排

在 subset 模式下：

完全沿用当前按 log_id 稳定抽样逻辑

在 all 模式下：

默认取四类规则池当前已实现规则的全集
再应用显式互斥组裁剪
输出“全部兼容规则命中”计划

5.5 互斥规则处理

为避免“全部命中”时出现语义自相矛盾的测试数据，引入显式互斥组定义。

互斥组处理规则：

互斥关系必须通过常量显式维护，不允许散落在样本 builder 内隐式判断
每个互斥组按固定优先级保留一个代表规则
未被声明为互斥的规则，默认视为可共存

第一版实现中，若现有规则样本已能共存，则允许互斥组为空；但结构必须预留，确保后续新增互斥规则时不破坏 all 模式语义。

5.6 对现有样本的兼容判断

根据当前样本实现与测试约束：

SALARY_QUICK_TRANSFER 与 SALARY_UNUSED 已通过不同主体拆分，可共存
大额交易、一期规则、二期流水规则目前主要通过不同对手方、不同时间或不同主体构造，未发现必须立即裁剪的硬冲突
二期基线规则可继续按命中计划幂等写入

因此，第一版预计“互斥组定义为空或极少数”，但仍要通过独立常量与测试明确这一口径。

6. 代码改动边界

本次设计预期改动集中在以下位置：

lsfx-mock-server/config/settings.py
lsfx-mock-server/main.py
lsfx-mock-server/services/file_service.py
lsfx-mock-server/README.md
lsfx-mock-server/tests/
新增热重载启动脚本

不触碰规则样本库的大规模重构，不改接口协议。

7. 测试设计

7.1 单元测试

subset 模式下同一 log_id 仍返回稳定子集
all 模式下返回四类规则池的兼容全集
若存在互斥组，验证不会同时出现同组规则
启动参数仅允许 subset|all

7.2 集成测试

普通启动时可切换到 all
热重载入口可切换到 all
all 模式生成的 rule_plan 会被正确写入 FileRecord
后续流水查询与第二期基线补齐继续消费同一份计划

7.3 回归重点

默认不传参数时行为不变
现有随机子集链路测试不回归
已有规则样本生成顺序与分页查询稳定性不回归

8. 风险与控制

8.1 风险

“全部规则命中”表述容易被误解为无条件全开
热重载启动若继续依赖裸 uvicorn main:app，无法自然接入业务参数
后续新增规则若存在互斥关系，可能破坏 all 模式语义

8.2 控制措施

文档与 README 统一使用“全部兼容规则命中”
热重载统一走项目级启动脚本
互斥组通过显式常量维护，并由测试守护

9. 预期交付

设计文档 1 份
后续实施计划 2 份：
- 后端实施计划
- 前端实施计划（明确本次无需前端代码改动）
Mock 服务代码、README 与测试更新

10. 验收标准

默认启动仍为随机子集命中
显式传入命令行参数后可切换至“全部兼容规则命中”
普通启动与热重载启动均可切换
all 模式下不会同时出现已定义互斥规则
所有相关测试通过，且无残留测试进程

6.6 KiB Raw Blame History