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

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 ... 透传业务参数。