mirror of
https://github.com/hpd840321/starRiverProperty.git
synced 2026-06-09 16:30:29 +08:00
Initial commit: reorganized source tree
- backend/: 13 Maven modules (cw-elevator-application, cloudwalk-cloud, intelligent-cwoscomponent, ninca-crk, etc.) - frontend/: 4 Vue projects (elevator-front, cwos-portal, alarm-front, front_acs) + decompiled + scripts - scripts/: build, test-env, tools (Docker Compose, service templates, API parity) - docs/: AGENTS.md, superpowers specs, architecture docs - .gitignore: standard Java/Maven exclusions Moved from legacy maven-*/ root layout to backend/ organized structure.
This commit is contained in:
hpd840321
@@ -0,0 +1,151 @@
|
||||
# 访客注册（派梯开通）与可达楼层验证 — 测试方案与计划
|
||||
|
||||
## 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，纳入内部介质分发策略。
|
||||
- **策略维度**：当前库表 **无「仅广发」机构字段**；跨部门验收等价验证「同一租户策略」。
|
||||
Reference in New Issue
Block a user