补充LSFX Mock启动说明文档

docs/reports/implementation/2026-03-22-lsfx-mock-startup-guide-record.md

@@ -0,0 +1,22 @@
+# LSFX Mock 启动说明文档补充记录
+
+## 本次改动
+
+- 新增 LSFX Mock 服务启动说明文档。
+- 文档聚焦普通启动、热重载启动和 `--rule-hit-mode` 参数写法。
+- 同步补充端口占用时的临时启动示例，便于联调时直接参考。
+- 按最新要求将启动说明移动到 `lsfx-mock-server/` 目录，与 `main.py` 保持同级。
+
+## 文档位置
+
+- `lsfx-mock-server/STARTUP.md`
+
+## 覆盖内容
+
+- `main.py` 启动命令
+- `dev.py --reload` 启动命令
+- `--rule-hit-mode subset|all` 参数说明
+- `--reload` 参数说明
+- 推荐使用场景
+- 启动成功后的访问地址
+- 端口冲突时的临时端口示例

lsfx-mock-server/STARTUP.md

@@ -0,0 +1,104 @@
+# LSFX Mock 服务启动说明
+
+## 适用范围
+
+本文说明 `lsfx-mock-server` 的本地启动方式，以及启动参数 `--rule-hit-mode` 的写法。
+
+服务目录：
+
+```bash
+cd lsfx-mock-server
+```
+
+## 普通启动
+
+普通启动入口为 `main.py`。
+
+### 默认随机子集模式
+
+```bash
+python3 main.py --rule-hit-mode subset
+```
+
+### 全部兼容规则命中模式
+
+```bash
+python3 main.py --rule-hit-mode all
+```
+
+## 热重载启动
+
+热重载启动入口为 `dev.py`，不要再直接使用裸 `uvicorn main:app --reload ...` 透传业务参数。
+
+### 默认随机子集模式
+
+```bash
+python3 dev.py --reload --rule-hit-mode subset
+```
+
+### 全部兼容规则命中模式
+
+```bash
+python3 dev.py --reload --rule-hit-mode all
+```
+
+## 启动参数说明
+
+### `--rule-hit-mode`
+
+可选值只有两个：
+
+- `subset`：默认模式。按 `logId` 稳定随机命中每类规则池中的部分规则。
+- `all`：全部兼容规则命中模式。会命中当前已定义的全部可共存规则；如果后续配置了互斥组，会按互斥组优先级保留组内首个规则。
+
+非法值会在启动阶段直接报错退出，例如下面这种写法是不允许的：
+
+```bash
+python3 main.py --rule-hit-mode invalid
+```
+
+### `--reload`
+
+仅 `dev.py` 支持该参数：
+
+```bash
+python3 dev.py --reload --rule-hit-mode subset
+```
+
+含义是开启热重载，适合本地开发联调。
+
+## 推荐用法
+
+### 日常开发
+
+```bash
+python3 dev.py --reload --rule-hit-mode subset
+```
+
+### 规则联调或一次性覆盖更多规则
+
+```bash
+python3 dev.py --reload --rule-hit-mode all
+```
+
+### 稳定复现普通启动行为
+
+```bash
+python3 main.py --rule-hit-mode subset
+```
+
+## 启动成功后的访问地址
+
+- Swagger UI: `http://localhost:8000/docs`
+- ReDoc: `http://localhost:8000/redoc`
+- 健康检查: `http://localhost:8000/health`
+
+## 补充说明
+
+- `RULE_HIT_MODE` 也可以通过环境变量配置，但当前项目推荐优先使用命令行参数，便于直接区分本次启动的命中模式。
+- 如果本机 `8000` 端口已被占用，可以临时通过环境变量覆盖端口，例如：
+
+```bash
+PORT=18000 python3 main.py --rule-hit-mode all
+PORT=18001 python3 dev.py --reload --rule-hit-mode all
+```