starRiverProperty/backend/cw-elevator-application/tools/visitor_floor_verification

访客楼层验证工具链

完整测试方案与计划见：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（适合只验某一业务块）

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 报告（默认生成于此）

依赖

pip install -r requirements.txt

联机阶段复用对拍请求头：ELEVATOR_HEADER_BUSINESSID、ELEVATOR_HEADER_AUTHORIZATION 等（见 elevator_api_parity）。

典型命令

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）。