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`](../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，纳入内部介质分发策略。
- **策略维度**：当前库表 **无「仅广发」机构字段**；跨部门验收等价验证「同一租户策略」。