feat: add service config templates and extraction script

Former-commit-id: 1de24b7eb79676d1aba9d799a58c5a753290cf52

maven-cw-elevator-application/tools/visitor_floor_verification/README.md

@@ -0,0 +1,106 @@
+# 访客楼层验证工具链
+
+完整测试方案与计划见：`docs/testing/visitor-registration-floor-validation.md`  
+
+**被访人（员工）与访客 ID、`personId`/`visitorId` 含义及楼层求交逻辑**：`docs/testing/visitor-registration-business-flow.md`  
+
+**租户定制默认楼层与未配置租户隔离（业务边界 + 流程图）**：`docs/testing/tenant-visitor-default-floor-isolation.md`
+
+## 一键验收（V2 程序）
+
+需能访问 **MySQL**（组织库 + 电梯库）。联机时脚本会先检测 V2 是否可达；不可达则尝试自动启动 **Maven V2 电梯应用**（`cw-elevator-application-starter`）。
+
+在同一目录创建 **`.env.visitor_verify`**（仅此文件名），填入 **`MYSQL_*`、`ELEVATOR_VERIFY_BASE`**，以及联机所需的 **`ELEVATOR_HEADER_AUTHORIZATION`**（等网关要求）；**`ELEVATOR_HEADER_BUSINESSID` 可不写**——未设置时程序会从 `config/test_matrix.json` 的 **`tenant_primary_business_id`** 自动注入 HTTP 头 `businessid`。测**第二租户**时请加 **`--tenant secondary`**，或 **`--suite tenant_secondary_placeholder`**，或在 `.env` 中手写 `ELEVATOR_HEADER_BUSINESSID`。也可不设文件而在 shell 中 `export`。
+
+**不同租户是否不同**：是。每个租户有独立的 **`business_id`**（组织/策略/人员数据隔离）。本矩阵中广发套件 `guangfa_fund_10` 与星河湾套件 `xinghewan_star_center` 当前配置为**同一** `business_id`（与 `tenant_primary_business_id` 一致）；对照套件 **`tenant_secondary_placeholder`** 使用 **`tenant_secondary_business_id`**，与主租户不同。
+
+一键脚本会优先加载 **`VISITOR_VERIFY_ENV_FILE`**（若设置），否则加载 **`./.env.visitor_verify`**。
+
+| CLI / 环境 | 作用 |
+|------------|------|
+| （未设 `ELEVATOR_HEADER_BUSINESSID`） | 自动使用矩阵 **`tenant_primary_business_id`** |
+| **`--tenant primary`** / **`secondary`** | 显式使用矩阵顶层主/次租户 ID |
+| **`--suite <suites[].id>`** 或 **`VISITOR_SUITE_ID`** | 按套件取该行的 **`business_id`**（适合只验某一业务块） |
+
+```bash
+cd maven-cw-elevator-application/tools/visitor_floor_verification
+chmod +x run_v2_visitor_default_floor_verify.sh
+./run_v2_visitor_default_floor_verify.sh
+```
+
+`.env.visitor_verify` 请保存为 **LF** 换行；若在 Windows 记事本编辑产生 CRLF，脚本已改为加载时自动剥除 `\r`，亦可在本目录执行 `sed -i 's/\r$//' .env.visitor_verify` 修复。
+
+脚本顺序：`**export_catalog.py`** → `**run_visitor_floor_suite.py --phase all**`（静态校验 + 联机注册与 `passRule/image` 回读），报告写入 `report/visitor-floor-suite-*.md`。
+
+若出现 **`Can't connect to MySQL server on '127.0.0.1'`**：说明未连上库（本机无 MySQL 或 `.env` 未加载）。请设置可达的 `MYSQL_HOST`/`MYSQL_PORT`，或已有快照时用 **`./run_v2_visitor_default_floor_verify.sh --skip-export`** 仅联机验证。
+
+**部门员工不足 10 人**：静态报告仅**提示**；联机阶段对**该部门已有全部员工**逐人测试（仍受 `--max-employees-per-department` 上限约束）。**无员工**的部门会记为失败并 SKIP 联机。
+
+
+| 脚本选项            | 含义                                     |
+| --------------- | -------------------------------------- |
+| `--skip-export` | 不跑导出，沿用现有 `data/catalog_snapshot.json` |
+| `--report-only` | 仅导出 + 静态 report，无联机（不需起 V2）            |
+| `--smoke`       | 联机极简：`--register-only` 且每部门 1 人        |
+| `--no-auto-start` | 关闭自动启动 V2（仅做探测，不拉起） |
+
+
+环境变量：`**VISITOR_SKIP_HEALTH_PROBE**`、`**VISITOR_REQUIRE_HEALTH**`、`**VISITOR_SKIP_PIP_INSTALL**` 见 `run_v2_visitor_default_floor_verify.sh` 内注释。联机阶段若出现 **`Connection refused`**：默认会先尝试自动启动 V2。自动启动命令可用 `VISITOR_V2_START_CMD` 覆盖（默认 `mvn -pl cw-elevator-application-starter -am spring-boot:run -Dspring-boot.run.profiles=access-control`），等待上限 `VISITOR_V2_START_MAX_WAIT_SEC`（默认 180s），日志 `VISITOR_V2_START_LOG`。完全关闭自动拉起可用 `--no-auto-start` 或 `VISITOR_AUTO_START_V2=0`。`**VISITOR_SKIP_LIVE_PREFLIGHT=1**` 可跳过 `run_visitor_floor_suite` 的 TCP 预检（仍会在首条业务请求失败；默认开启预检以免报告刷屏）。
+
+联机参数：`**--max-employees-per-department**`（默认 10；冒烟可设为 **1** 减少 API 次数）。
+
+**验收口径（与业务一致）**
+
+- `POST /elevator/person/add/visitor`：完成访客派梯登记；请求里 `floorIds: []` 时由服务端取被访人 `floorList` 并与 `tenant_visitor_floor_policy` 求交后落库。  
+- **HTTP 响应为 `Boolean`，不含允许楼层列表**；要对「注册后实际可访问楼层」做断言，须在注册成功后用 `**POST /elevator/passRule/image`**（`personId` = 访客 `visitorId`）回读 zone 列表。这是与 `tools/elevator_api_parity/scripts/verify_gf_visitor_default_floor.py` 同一套验收路径。  
+- 若只做连通性/业务码冒烟（不测楼层）：`**--register-only`**（不回读 passRule）。
+
+## 目录
+
+
+| 路径                                       | 说明                                                               |
+| ---------------------------------------- | ---------------------------------------------------------------- |
+| `config/test_matrix.json`                | 套件与组织节点（广发10 + 星河湾/星中心代表 + 第二租户占位）                               |
+| `data/catalog_snapshot.json`             | `scripts/export_catalog.py` 生成，含每部门样例被访人 ID                      |
+| `scripts/export_catalog.py`              | 从 MySQL 拉取策略、人员锚点，合并矩阵                                           |
+| `run_v2_visitor_default_floor_verify.sh` | **一键**：导出 catalog + `--phase all`（推荐）                            |
+| `scripts/run_visitor_floor_suite.py`     | `report` / `live` / `**all`**（静态 + 联机合并报告）；`--register-only` 仅注册 |
+| `report/`                                | 运行后 Markdown 报告（默认生成于此）                                          |
+
+
+## 依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+联机阶段复用对拍请求头：`ELEVATOR_HEADER_BUSINESSID`、`ELEVATOR_HEADER_AUTHORIZATION` 等（见 `elevator_api_parity`）。
+
+## 典型命令
+
+```bash
+export MYSQL_HOST=192.168.3.12 MYSQL_PORT=3307 MYSQL_USER=root MYSQL_PASSWORD='***'
+export ELEVATOR_HEADER_BUSINESSID=2524639890ba4f2cba9ba1a4eeaa4015
+export ELEVATOR_HEADER_AUTHORIZATION='Bearer ...'
+export VISITOR_TEST_PERSON_ID='<测试访客 personId>'
+
+# 推荐：一键（等同 export + --phase all；businessId 默认取矩阵主租户）
+./run_v2_visitor_default_floor_verify.sh
+
+# 第二租户联机（businessId 取自 tenant_secondary_business_id；透传给 Python）
+./run_v2_visitor_default_floor_verify.sh --tenant secondary
+
+python scripts/export_catalog.py
+python scripts/run_visitor_floor_suite.py --phase report --snapshot data/catalog_snapshot.json
+# 静态 + 联机合并为一份报告
+python scripts/run_visitor_floor_suite.py --phase all --base-url http://127.0.0.1:18081 \
+  --visitor-person-id "$VISITOR_TEST_PERSON_ID"
+python scripts/run_visitor_floor_suite.py --phase live --base-url http://127.0.0.1:18081 \
+  --visitor-person-id "$VISITOR_TEST_PERSON_ID"
+
+# 仅访客注册（不测楼层明细）
+python scripts/run_visitor_floor_suite.py --phase live --base-url http://127.0.0.1:18081 \
+  --register-only --max-employees-per-department 1
+```
+
+第二租户联机需切换 `ELEVATOR_HEADER_BUSINESSID`（若现场无人员则套件自动 SKIP）。