# 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`。

整体链路如下：

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

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

### 5.2 配置设计

在 `config/settings.py` 中新增：

- `RULE_HIT_MODE: str = "subset"`

可选值仅允许：

- `subset`
- `all`

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

### 5.3 启动设计

保留两类启动方式：

#### 普通启动

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

#### 热重载启动

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

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

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

### 5.4 规则计划编排设计

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

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

在 `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` 模式下不会同时出现已定义互斥规则
- 所有相关测试通过，且无残留测试进程