# org_id 策略修复 — 无鉴权验证方案设计

**文档性质**：验证方案设计说明  
**设计日期**：2026-05-01  
**状态**：待评审  
**关联 Spec**：`docs/superpowers/specs/2026-05-01-org-id-policy-fix-design.md`  
**被测应用**：`cw-elevator-application`（V2, port 18081）

---

## 1. 目标

通过无鉴权 HTTP 调用 `POST /elevator/person/add/visitor` 和 `POST /elevator/passRule/image`，验证 org_id 策略修复的 7 个核心场景，确保业务逻辑满足需求。

**不验证**：鉴权正确性、Feign 调用链、图库绑定、Consul 服务发现。

---

## 2. 完整业务流程与接口调用链

### 2.1 业务全景

```
Step 0: 访客邀约（上游，非电梯侧）
  ┌─────────────────────────────────────────────────┐
  │ 第三方业务系统（BFF / intelligent / 登记页）      │
  │   ├── 创建访客人员档案（cw_is_person + 访客标签） │
  │   └── 确定被访人（host personId）                │
  └─────────────────────────────────────────────────┘
  → 访客已存在于组织库中，personId 可用
  → 本方案使用预置测试访客（919900... 号段），跳过此步

Step 1: 设置访客可访问楼层（电梯侧，核心验证目标）
  POST /elevator/person/add/visitor
  ┌──────────────────────────────────────────────────────┐
  │ ① Feign → /component/person/detail                  │
  │    取被访人 floorList + organizationIds              │
  │                                                      │
  │ ② 查 tenant_visitor_floor_policy                     │
  │    WHERE org_id = ?  (从 organizationIds 取)         │
  │                                                      │
  │ ③ 二选一：                                          │
  │    有策略 → effectiveFloors = allow（直接替换）      │
  │    无策略 → effectiveFloors = floorList              │
  │    allow 含无效值 → fail 76260533                    │
  │                                                      │
  │ ④ Feign → /sysetting/zone/page                      │
  │    取楼栋 + 图库 imageStoreId                        │
  │                                                      │
  │ ⑤ 写 image_rule_ref（访客 personId ← visitorId）    │
  │                                                      │
  │ ⑥ Feign → /component/imagestore/person/batchBind    │
  │    访客绑定到楼栋图库                                │
  └──────────────────────────────────────────────────────┘

Step 2: 回读验证（确认楼层写入正确）
  POST /elevator/passRule/image
  Body: { "personId": "<visitorId>" }
  → 返回该访客可访问的 zoneId 列表
  → 与期望楼层比对
```

### 2.2 接口调用细节

#### POST /elevator/person/add/visitor

| 项目 | 值 |
|------|-----|
| Method | POST |
| Path | `/elevator/person/add/visitor` |
| Content-Type | `application/json` |
| 鉴权模式 | noauth-probe（仅 `businessid` 头） |

**请求体：**

```json
{
    "personId": "1060601019894960128",
    "visitorId": "9199000100000000001",
    "floorIds": [],
    "begVisitorTime": 1751319780000,
    "endVisitorTime": 1751406180000
}
```

| 字段 | 必填 | 说明 |
|------|------|------|
| `personId` | 是 | 被访人 ID（决定 floorList 和 org_id 来源） |
| `visitorId` | 是 | 访客 ID（落库 image_rule_ref 的 person_id） |
| `floorIds` | 否 | **空数组**=UC-01 由电梯补全；**非空**=UC-02 调用方指定 |
| `begVisitorTime` | 是 | Unix 毫秒，访客有效期开始 |
| `endVisitorTime` | 是 | Unix 毫秒，访客有效期结束 |

**响应体（成功）：**

```json
{ "success": true, "code": "0", "data": true }
```

**响应体（策略拒绝）：**

```json
{ "success": false, "code": "76260533", "message": "策略配置了被访人无权访问的楼层，请联系管理员" }
```

#### POST /elevator/passRule/image（回读）

| 项目 | 值 |
|------|-----|
| Method | POST |
| Path | `/elevator/passRule/image` |
| Body | `{ "personId": "<visitorId>" }` |

**响应体：**

```json
{
    "success": true,
    "data": {
        "datas": [
            { "zoneId": "605560545117995008", "zoneName": "28F" }
        ]
    }
}
```

### 2.3 策略在流程中的位置

```
add/visitor 请求进入
  │
  ├─ personId → Feign detail() → { floorList, organizationIds }
  │
  ├─ organizationIds[0] → SELECT ... FROM tenant_visitor_floor_policy
  │                        WHERE org_id = ?   ← 新：org_id 粒度
  │                        AND enabled = 1
  │
  ├─ 有策略行 → effectiveFloors = allow          ← 二选一，不求交
  │             allow ⊆ floorList 校验
  │             └─ 不通过 → 76260533
  │
  └─ 无策略行 → effectiveFloors = floorList      ← 默认行为
```

---

## 3. 测试环境

| 项目 | 值 |
|------|-----|
| 电梯服务 | `http://127.0.0.1:18081` |
| MySQL 组织库 | `192.168.3.12:3307 / component-organization` |
| MySQL 电梯库 | `192.168.3.12:3307 / cw-elevator-application` |
| 租户 | `businessId = 2524639890ba4f2cba9ba1a4eeaa4015` |
| 调用方式 | noauth-probe（仅 businessid 头，无鉴权 token） |

---

## 4. 测试矩阵（7 个用例）

### 4.1 测试数据

| 实体 | ID |
|------|-----|
| 1403艾斯 org | `72fb65ec5de94201b909a98b8bae1892` |
| 1405一博环保 org | `2095de3d541f44eba686c78fda68336f` |
| 星中心物业 org | `f216235e54ca42bfa0379e69b3754aff` |
| 广发基金 org | `488b8ad049bb43408a6fbcc50bcb89ac` |
| 陈国辉（1403+星中心） | `1060601019894960128` |
| 王姣（1405） | `1090779433129840640` |
| 秦夏（广发基金） | `1072908835884208128` |
| 28F zone | `605560545117995008` |
| 6F zone | `605560541473144832` |

### 4.1.1 访客数据

测试使用开发库中已预置的**专用测试访客**（号段 `9199000100000000001`~`9199000100000000020`，均已标注"访客"标签 `LABEL_ID = ed2dbab6d6234a7287106b80857c819e`）。这些是测试专用人员，非真实业务访客。

`add/visitor` 写入 `image_rule_ref` 时以 `visitorId` 为键，为避免同一访客的多次写入相互干扰，每个用例轮换使用不同测试访客。

| 用例 | visitorId | 访客标识 |
|------|-----------|----------|
| T1 | `9199000100000000001` | 测试访客AUTO-01 |
| T2 | `9199000100000000002` | 测试访客AUTO-02 |
| T3 | `9199000100000000003` | 测试访客AUTO-03 |
| T4 | `9199000100000000004` | 测试访客AUTO-04 |
| T5 | `9199000100000000005` | 测试访客AUTO-05 |
| T6 | `9199000100000000006` | 测试访客AUTO-06 |
| T7 | `9199000100000000007` | 测试访客AUTO-07 |

### 4.2 用例

| ID | 场景 | 被访人 | 策略 org | allow | enabled | 期望 |
|----|------|--------|----------|-------|---------|------|
| T1 | 有策略→allow 替换 floorList | 陈国辉 | 1403 | [28F] | 1 | passRule 返回仅 [28F] |
| T2 | 无策略→floorList | 王姣 | 1405 | 无 | — | passRule 返回 floorList 全集 |
| T3 | allow 含无效zone→拒绝 | 陈国辉 | 1403 | [28F, 99F] | 1 | code=76260533 |
| T4 | 多组织命中第一个策略 | 陈国辉 | 1403+星中心 | 1403有,星中心无 | 1 | 命中1403→[28F] |
| T5 | enabled=0 等同无策略 | 陈国辉 | 1403 | [28F] | 0 | passRule 返回 floorList 全集 |
| T6 | UC-02 策略优先 | 陈国辉 | 1403 | [28F] | 1 | 传floorIds被忽略→[28F] |
| T7 | 广发基金迁移验证 | 秦夏 | 广发基金 | [28F] | 1 | 迁移后→仅 [28F] |

---

## 5. 脚本结构

**文件**：`maven-cw-elevator-application/tools/visitor_floor_verification/scripts/verify_org_policy_fix.py`

```
verify_org_policy_fix.py
  │
  ├── Phase 0: health_check()
  │   GET /actuator/health
  │
  ├── Phase 1: prepare_test_data()
  │   ① INSERT policy_t1_1403 (org=1403, allow=[28F], enabled=1)
  │   ② INSERT policy_t3_invalid (org=1403, allow=[28F,99F], enabled=1)
  │   ③ INSERT policy_t5_disabled (org=1403, allow=[28F], enabled=0)
  │   ④ UPDATE 广发基金 SET org_id='488b8adb...' WHERE id='gf_vstr_...'
  │
  ├── Phase 2: run_all_cases()
  │   每个用例:
  │     POST add/visitor → 检查 HTTP 200 + code + success
  │     成功 → POST passRule/image → 比对 zoneIds
  │     失败 → 检查 code == 期望错误码
  │
  ├── Phase 3: cleanup_test_data()
  │   ① DELETE 测试策略行
  │   ② UPDATE 广发基金 SET org_id=NULL
  │
  └── Phase 4: print_report()
      输出 JSON 报告到 report/org-policy-fix-verify-{timestamp}.json
```

### 5.1 HTTP 请求格式（noauth-probe）

```python
headers = {
    "Content-Type": "application/json",
    "businessid": "2524639890ba4f2cba9ba1a4eeaa4015"
}

# add/visitor
POST /elevator/person/add/visitor
{
    "personId": "1060601019894960128",
    "visitorId": "<轮换访客ID>",
    "floorIds": [],
    "begVisitorTime": <now_ms>,
    "endVisitorTime": <now_ms + 86400000>
}

# passRule/image（回读）
POST /elevator/passRule/image
{
    "personId": "<visitorId>"
}
```

---

## 6. 数据准备与清理

### 6.1 准备 SQL

```sql
-- T1/T4/T6 共用
INSERT INTO tenant_visitor_floor_policy
(id, org_id, business_id, policy_type, allow_zone_ids, building_id, enabled, policy_version, created_at, updated_at)
VALUES ('policy_t1_1403', '72fb65ec5de94201b909a98b8bae1892', NULL, 'INTERSECT_ALLOWLIST',
 '["605560545117995008"]', NULL, 1, 1, UNIX_TIMESTAMP(NOW())*1000, UNIX_TIMESTAMP(NOW())*1000);

-- T3
INSERT INTO tenant_visitor_floor_policy
(id, org_id, business_id, policy_type, allow_zone_ids, building_id, enabled, policy_version, created_at, updated_at)
VALUES ('policy_t3_invalid', '72fb65ec5de94201b909a98b8bae1892', NULL, 'INTERSECT_ALLOWLIST',
 '["605560545117995008","605560540000000000"]', NULL, 1, 1, UNIX_TIMESTAMP(NOW())*1000, UNIX_TIMESTAMP(NOW())*1000);

-- T5
INSERT INTO tenant_visitor_floor_policy
(id, org_id, business_id, policy_type, allow_zone_ids, building_id, enabled, policy_version, created_at, updated_at)
VALUES ('policy_t5_disabled', '72fb65ec5de94201b909a98b8bae1892', NULL, 'INTERSECT_ALLOWLIST',
 '["605560545117995008"]', NULL, 0, 1, UNIX_TIMESTAMP(NOW())*1000, UNIX_TIMESTAMP(NOW())*1000);

-- T7: 广发基金迁移
UPDATE tenant_visitor_floor_policy
SET org_id = '488b8ad049bb43408a6fbcc50bcb89ac'
WHERE id = 'gf_vstr_policy_guangfa_fund_001x';
```

### 6.2 清理 SQL

```sql
DELETE FROM tenant_visitor_floor_policy WHERE id IN ('policy_t1_1403','policy_t3_invalid','policy_t5_disabled');
UPDATE tenant_visitor_floor_policy SET org_id = NULL WHERE id = 'gf_vstr_policy_guangfa_fund_001x';
```

### 6.3 执行顺序

```text
prepare:
  INSERT policy_t1_1403           (T1/T4/T6 使用)
  INSERT policy_t3_invalid        (T3 使用)
  INSERT policy_t5_disabled       (T5 使用)
  UPDATE 广发基金 SET org_id      (T7 使用)

execute:
  T1: 陈国辉 + policy_t1_1403     → allow=[28F]
  T3: 陈国辉 + policy_t3_invalid  → 76260533（需先改1403的org_id或先DELETE T1再切换）
  T4: 陈国辉(多组织) + policy_t1  → allow=[28F]
  T5: 陈国辉 + policy_t5_disabled → floorList全集
  T2: 王姣(无策略)                → floorList全集
  T6: 陈国辉(UC-02) + policy_t1   → allow=[28F]
  T7: 秦夏 + 广发基金策略          → allow=[28F]

cleanup:
  DELETE 测试行
  UPDATE 广发基金 SET org_id=NULL
```

> T3 执行前需确保 policy_t1_1403 不生效（相同 org_id 只能有一条启用策略）。方案：T3 前 DELETE policy_t1_1403，T3 后恢复 INSERT。

---

## 7. 验证判定规则

| 判定项 | 通过条件 |
|--------|----------|
| HTTP 状态 | `add/visitor` 返回 200 |
| 业务成功 | `response.success == true` |
| 业务失败 | `response.code == "76260533"` |
| 楼层匹配 | `passRule/image` 返回的 zoneId 集合 == 期望集合（顺序无关） |
| 脱敏 | 报告中不出现 PII（姓名/手机号） |

---

## 8. 输出

```
report/org-policy-fix-verify-{timestamp}.json
```

包含：每个用例的请求/响应摘要、passRule 结果、期望 vs 实际对比、通过/失败汇总。

---

## 9. 文件清单

| 文件 | 操作 | 说明 |
|------|------|------|
| `tools/visitor_floor_verification/scripts/verify_org_policy_fix.py` | 新增 | 主验证脚本 |
| `tools/visitor_floor_verification/report/` | — | 报告输出目录（已有） |

---

*本设计说明待评审，通过后转入 implementation。*