补充Mock命中模式后端实施与验证记录

docs/reports/implementation/2026-03-22-lsfx-rule-hit-mode-backend-record.md

@@ -0,0 +1,40 @@
+# LSFX Mock 规则命中模式后端实施记录
+
+## 修改范围
+- `lsfx-mock-server/config/settings.py`
+- `lsfx-mock-server/main.py`
+- `lsfx-mock-server/dev.py`
+- `lsfx-mock-server/services/file_service.py`
+- `lsfx-mock-server/tests/test_startup.py`
+- `lsfx-mock-server/tests/test_file_service.py`
+- `lsfx-mock-server/README.md`
+
+## 本次改动
+- 为 Mock 服务新增统一配置项 `RULE_HIT_MODE`，默认值为 `subset`。
+- 在 `main.py` 中新增 `parse_args()` 与启动前模式注入逻辑，支持 `--rule-hit-mode subset|all`。
+- 新增项目级热重载入口 `dev.py`，支持 `python dev.py --reload --rule-hit-mode ...`。
+- 在 `FileService` 中将规则命中计划拆分为：
+  - `subset` 模式：沿用按 `logId` 稳定随机命中子集
+  - `all` 模式：返回全部兼容规则命中计划
+- 新增显式互斥组入口 `RULE_CONFLICT_GROUPS`，当前实现默认为空列表，仅预留结构与裁剪逻辑。
+
+## 规则命中模式语义
+- 默认模式保持为 `subset`，不传参数时仍按同一 `logId` 生成稳定随机子集。
+- `all` 的准确语义是“全部兼容规则命中”，不是无约束全量命中。
+- 当前四类规则池在 `all` 模式下会返回各自全集，再经过互斥组裁剪。
+- 当前互斥组配置为空列表，因此默认不会额外裁剪任何规则；后续若新增互斥组，将按组内顺序保留首个规则。
+
+## 启动入口调整
+- 普通启动入口更新为：
+  - `python main.py --rule-hit-mode subset`
+  - `python main.py --rule-hit-mode all`
+- 热重载入口统一改为项目脚本：
+  - `python dev.py --reload --rule-hit-mode subset`
+  - `python dev.py --reload --rule-hit-mode all`
+- README 已同步改为“全部兼容规则命中”口径，不再使用“全部规则命中”。
+
+## 实施结果
+- `FileService -> StatementService -> FileRecord 缓存` 主链路保持不变。
+- 默认随机子集行为未回归。
+- `all` 模式已支持通过启动参数显式切换。
+- 热重载启动不再依赖裸 `uvicorn main:app --reload ...` 透传业务参数。

docs/tests/records/2026-03-22-lsfx-rule-hit-mode-backend-verification.md

@@ -0,0 +1,41 @@
+# LSFX Mock 规则命中模式后端验证记录
+
+## 执行命令
+
+```bash
+cd lsfx-mock-server
+python3 -m pytest tests/test_startup.py tests/test_file_service.py -k "rule_hit_plan or parse_args" -v
+
+PORT=18000 python3 main.py --rule-hit-mode all > /tmp/lsfx_main_18000.log 2>&1 &
+sleep 3
+kill <main-pid>
+
+PORT=18001 python3 dev.py --reload --rule-hit-mode all > /tmp/lsfx_dev_18001.log 2>&1 &
+sleep 5
+kill <dev-pid>
+```
+
+## 测试结果
+- 2026-03-22 执行：
+  `python3 -m pytest tests/test_startup.py tests/test_file_service.py -k "rule_hit_plan or parse_args" -v`
+- 结果：`10 passed, 5 deselected, 1 warning in 0.27s`
+- warning 为现有 `pydantic` 弃用提示，本次改动未引入失败或 error。
+
+## 启动验证结果
+- 普通启动验证：
+  - 使用临时端口 `18000` 执行 `python3 main.py --rule-hit-mode all`
+  - 日志显示 `Uvicorn running on http://0.0.0.0:18000`
+  - 结束后日志显示正常 shutdown，进程已清理
+- 热重载启动验证：
+  - 使用临时端口 `18001` 执行 `python3 dev.py --reload --rule-hit-mode all`
+  - 日志显示 reloader 进程与 server 进程均成功启动
+  - 结束后日志显示 server process 与 reloader process 已停止
+
+## 进程清理结果
+- 启动验证结束后，针对本次工作树路径再次执行进程扫描。
+- `main.py --rule-hit-mode all` 无残留进程。
+- `dev.py --reload --rule-hit-mode all` 无残留进程。
+
+## 说明
+- 原计划默认使用 `8000` 端口进行烟测。
+- 验证时发现本机已有独立 `Python main.py` 进程占用 `8000`，为避免影响现有环境，本次改用临时端口 `18000/18001` 完成等价验证。

lsfx-mock-server/README.md

@@ -22,15 +22,20 @@ pip install -r requirements.txt
 ### 2. 启动服务
 
 ```bash
-python main.py
+python main.py --rule-hit-mode subset
+python main.py --rule-hit-mode all
 ```
 
-或使用 uvicorn（支持热重载）：
+热重载启动请使用项目脚本入口：
 
 ```bash
-uvicorn main:app --reload --host 0.0.0.0 --port 8000
+python dev.py --reload --rule-hit-mode subset
+python dev.py --reload --rule-hit-mode all
 ```
 
+- `subset`：默认模式，按 `logId` 稳定随机命中部分规则
+- `all`：全部兼容规则命中模式，会命中当前可共存的全部规则
+
 ### 3. 访问 API 文档
 
 - **Swagger UI**: http://localhost:8000/docs
@@ -135,6 +140,7 @@ PORT=8000
 # 模拟配置
 PARSE_DELAY_SECONDS=4
 MAX_FILE_SIZE=10485760
+RULE_HIT_MODE=subset
 ```
 
 ### 响应模板