starRiverProperty/docs/testing/visitor-registration-floor-validation.md

访客注册（派梯开通）与可达楼层验证 — 测试方案与计划

0. 关联文档

• 租户 / 组织 / 人员 / 访客 ER 与表关系：docs/architecture/租户组织人员访客-数据模型与用例.md
• 被访人 / 访客 / 楼层逻辑（源码走查）：docs/testing/visitor-registration-business-flow.md
• 服务层逐步说明与活动图（与 08 同谱系）：maven-cw-elevator-application/cw-elevator-application-service/docs/08-visitor-registration-and-elevator-auth.md
• 租户定制默认楼层 vs 未定义租户隔离边界（流程图/时序图）：docs/testing/tenant-visitor-default-floor-isolation.md

0.1 数据模型（测试矩阵 v3）

• export_settings.employees_per_department：每部门导出员工人数（默认 10），写入快照 host_employees。

• visitor_resolution.pool_limit：访客标签池上限（与 visitor_pool_limit 取大）。

• personId（被访人）：员工；导出按部门取最多 N 人写入 host_employees[]（N 见矩阵 employees_per_department）。

• visitorId（访客）：访客档案（「访客」标签）；导出为 每名员工 分配 visitor_for_api（全局槽位轮询）；test_matrix.json 中部门级 visitor_person_id 可令该部门全部员工共用同一访客。

---

1. 背景与范围

1.1 业务链路（电梯应用）

• 接口：POST /elevator/person/add/visitor，请求体 floorIds 为空时，服务内部：
  1. Feign 调用组织组件 **/component/person/detail，取被访人 **floorList（雪花 zone_id 字符串列表）。
  2. 查询 **tenant_visitor_floor_policy**（租户默认策略，business_id = 登录上下文机构）。
  3. 策略为 **INTERSECT_ALLOWLIST** 且启用时：生效楼层 = floorList ∩ allow_zone_ids（顺序保留被访人顺序）。
  4. 交集为空 → 业务码 **76260532**；否则按生效楼层写 **image_rule_ref** 并绑图库。
• 回读验收：POST /elevator/passRule/image，personId = 访客 ID，从 **data[]** 读取 zoneId / zoneName。

1.2 当前库内策略现状（重要）

• **tenant_visitor_floor_policy** 按 **business_id** 维度生效；现场 **cw-elevator-application** 中为租户 **2524639890ba4f2cba9ba1a4eeaa4015**（与组织库 **cw_is_organization.BUSINESS_ID** 一致）配置了广发接待层 28F 对应 **zone_id**。
• 含义：凡使用该 **business_id** 登录的星河湾/星中心主体（含非「广发」名字的部门），在未显式传 floorIds 时同样适用「与 allowlist 求交」——验收与风险评估时需写明该前提；若产品上要「仅广发主体生效」，需另行产品设计（如楼栋/机构维度策略扩展），不在本脚本假定范围内。

1.3 现场组织库事实（component-organization）

• **BUSINESS_ID = 2524639890ba4f2cba9ba1a4eeaa4015：根机构 **星河湾中心，其下含 [28-38F]广发基金管理有限公司 及其 9 个子部门（合计 10 个节点：1 公司 + 9 部门），为本方案 「广发基金套件」 覆盖对象。
• **BUSINESS_ID = 9f19a307b3ea4854bf2d7dafe69649c9：仅 **默认根节点；现场 **cw_is_person** 侧未见该租户人员——联调用例若依赖在职被访人，可能无法执行；保留为「策略缺失对照」说明项。
• 命名：文中「星河湾中心」为现场 cw_is_organization 根节点 NAME 示例；口语「星河湾集团」等与库内节点全称不一定一一对应，请以现场 NAME/ID 为准。租户 / 组织 / 人员 / 访客 ER 与术语见 docs/architecture/租户组织人员访客-数据模型与用例.md。

---

2. 测试层级定义

层级	名称	手段	产出
L0	数据导出	MySQL 读组织、策略、样例人员	catalog_snapshot.json
L1	静态一致性	校验导出 JSON 内 suite 与策略字段口径	控制台 / 报告一节
L2	联机楼层验收	调用 **add/visitor（floorIds=[]）+ **passRule/image	Markdown 报告
L3	可选扩展	对接组件 **/component/person/detail** 预计算交集（需另行网关/脚本权限）	未默认启用

说明：被访人 floorList 不可仅从电梯库推导（以组件为准），故 L2 以「开通结果 + 回读楼层」为权威验收；若需预知交集，须 L3 或人工查组件。

---

3. 测试套件与用例矩阵（摘要）

3.1 guangfa_fund_10 — 广发基金管理有限公司 subtree（10）

#	组织 ID（节选）	名称
1	488b8ad049bb43408a6fbcc50bcb89ac	[28-38F]广发基金管理有限公司
2～10	其子部门（含 32F-广发外包、信息技术部、公司领导 等共 9 个）	见 config/test_matrix.json

每条用例：同一租户上下文（Header businessid）下，指定 被访人 personId（从该部门导出 1 名在职人员）、访客 personId（测试账号）、访客有效期；不传 **floorIds**。

期望类型（L2）：

• 成功路径：add/visitor 返回成功码；passRule/image 中 **zoneName 均落在策略允许集合对应的楼层展示名**（现场允清单示例：28F，正则可在脚本中用 --allowed-zone-name-regex 约束）。
• 失败路径：若组件返回的被访人 **floorList** 与 **allow_zone_ids** 无交集 → **76260532**，记为 EXPECTED_FAIL，断言业务码而非楼层列表。

3.2 xinghewan_star_center — 星河湾 / 星中心代表部门（非广发字样）

从 **星河湾中心** 根下选取包含 「星河湾」「星中心」 语义的部门若干（示例：星河湾集团总部、星中心物管公司），每部门 1 名被访人样例。

期望：与 3.1 相同租户策略下，仍应按「求交」结果开通或失败（不得以「非广发」跳过策略）。

3.3 tenant_secondary — 第二 BUSINESS_ID（对照）

• 目的：无 **tenant_visitor_floor_policy** 行时，行为应与「未收窄」一致（以组件 **floorList** 为准）；现场若无人员，标记 SKIP。

---

4. 测试数据约定

数据项	来源	说明
business_id	Header **businessid**	与 DB **tenant_visitor_floor_policy.business_id**、组织 **BUSINESS_ID** 一致
被访人 personId	MySQL cw_is_person + cw_is_person_organization_ref	导出脚本按 **ORG_ID** 取 每部门 1 人
访客 personId	测试环境固定账号	环境变量 VISITOR_TEST_PERSON_ID（或脚本参数）；勿用生产真实访客随意写入
访客有效期	begVisitorTime / endVisitorTime	毫秒时间戳；避免重叠冲突可调脚本 --window-days
允许楼层参照	tenant_visitor_floor_policy.allow_zone_ids + cw_is_area（cwos_portal）	展示名校验用 **zoneName**（如 28F）

详细字段级快照见仓库 **maven-cw-elevator-application/tools/visitor_floor_verification/data/**（导出生成）。

---

5. 准入 / 准出标准

准入

• 电梯服务可访问（BASE_URL）；网关鉴权头 **ELEVATOR_HEADER_*** 已配置；
• MySQL 可从运行脚本环境访问（导出阶段）；
• 已书面确认：租户级策略 对全体使用该 business_id 的主体生效。

准出

• catalog_snapshot.json 生成成功且含三类套件定义；
• L2 报告：通过率 / SKIP / FAIL 可区分；失败附 **code** 与响应摘要；
• 对 **EXPECTED_FAIL**（交集为空）类用例，业务码符合 **76260532**。

---

6. 执行顺序建议

1. python scripts/export_catalog.py → 刷新快照（依赖 DB）。
2. 复核快照内 **sample_host_person_id** 是否为在职账号。
3. python scripts/run_visitor_floor_suite.py --phase report（仅导出校验）或 **--phase live**（联机）。
4. 归档报告 **report/visitor-floor-suite-<timestamp>.md**。

---

7. 仓库内工件路径（索引）

工件	路径
测试方案与计划（本文档）	docs/testing/visitor-registration-floor-validation.md
套件矩阵（广发10 + 星河湾/星中心 + 第二租户占位）	maven-cw-elevator-application/tools/visitor_floor_verification/config/test_matrix.json
导出快照（建议纳入变更或由内网生成）	.../tools/visitor_floor_verification/data/catalog_snapshot.json
导出脚本	.../scripts/export_catalog.py
报告 / 联机执行脚本	.../scripts/run_visitor_floor_suite.py
报告输出目录	.../tools/visitor_floor_verification/report/

策略初始化 SQL（广发 28F allowlist）见 docs/sql/tenant_visitor_floor_policy_init_guangfa_fund.sql。

---

8. 风险与限制

• 重复开通：同一访客短期内多次 add/visitor 可能叠加规则或触发远端校验失败；建议使用 专用测试访客 或拉长有效期区间。
• 环境与生产：口令与 URL 勿提交仓库；快照 JSON 若含真实 ID，纳入内部介质分发策略。
• 策略维度：当前库表 无「仅广发」机构字段；跨部门验收等价验证「同一租户策略」。