starRiverProperty/docs/superpowers/plans/2026-05-09-guangfa-visitor-floor.md

# 广发基金访客默认28F — 方案A实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 将广发基金访客默认楼层从 28F (单层) 扩展为目标楼层列表, 通过 UPDATE `tenant_visitor_floor_policy.allow_zone_ids` 实现, 零代码变更。

**Architecture:** 纯数据变更。利用 V2 已有的 `tenant_visitor_floor_policy` 表驱动策略架构, 在 `ImgPersonServiceImpl.detail()` L643-648 的策略替代块中自动生效。仅修改 component-organization 库, 电梯侧不参与。

**Tech Stack:** MySQL (component-organization 库), Shell (验证)

---

## 前置确认

实施前需确认目标楼层列表 (zone_id)。当前仅28F:

```
zone_id = 605560545117995008  (28F, code=0x1C)
```

若仅为演示 28F 单层方案, 无需修改数据 (当前已是 28F)。若需扩展到多楼层, 需先确认 zone_id 列表。

---

### Task 1: 确认目标 zone_id 列表 (调研)

**Files:**
- (不修改文件)

- [ ] **Step 1: 查询当前 20 层 zone_id**

```sql
-- 连接: mysql -h 192.168.3.12 -P 3307 -u root -p'123456' cw-elevator-application

SELECT zone_id, zone_name, code, parent_id
FROM code_elevator_area
WHERE parent_id = '605560539791228928'
  AND zone_name NOT LIKE '%B%'
ORDER BY CAST(zone_name AS UNSIGNED) ASC;
```

预期: 返回所有可用楼层, 确认目标 20 层的 zone_id 列表。

- [ ] **Step 2: 记录目标楼层列表**

将 zone_id 列表整理为 JSON 数组格式:
```json
["605560545117995008", "zone_id_2", ..., "zone_id_20"]
```

---

### Task 2: 更新策略数据 (生产库)

**Files:**
- (不修改文件)

- [ ] **Step 1: 备份当前策略**

```sql
-- 连接: component-organization 库
CREATE TABLE tenant_visitor_floor_policy_bak_20260509 AS
SELECT * FROM tenant_visitor_floor_policy
WHERE id = 'gf_vstr_policy_guangfa_fund_001x';
```

预期: `Query OK, 1 row affected`

- [ ] **Step 2: 验证当前策略状态**

```sql
SELECT id, org_id, allow_zone_ids, enabled, policy_version
FROM tenant_visitor_floor_policy
WHERE id = 'gf_vstr_policy_guangfa_fund_001x';
```

预期: `enabled=1, allow_zone_ids='["605560545117995008"]'`

- [ ] **Step 3: 更新 allow_zone_ids**

```sql
-- 以28F单层为例 (若为20层则替换为Task 1确认的列表)
UPDATE tenant_visitor_floor_policy
SET allow_zone_ids = '["605560545117995008"]',
    policy_version = policy_version + 1,
    remark = '广发基金：访客默认28F (2026-05-09 方案A实施)',
    updated_at = UNIX_TIMESTAMP(NOW()) * 1000
WHERE id = 'gf_vstr_policy_guangfa_fund_001x'
  AND enabled = 1;
```

预期: `Query OK, 1 row affected`

- [ ] **Step 4: 验证更新结果**

```sql
SELECT id, org_id, allow_zone_ids, enabled, policy_version, updated_at
FROM tenant_visitor_floor_policy
WHERE id = 'gf_vstr_policy_guangfa_fund_001x';
```

预期: `policy_version` 自增 1, `allow_zone_ids` 为新列表

---

### Task 3: 更新种子 SQL

**Files:**
- Modify: `docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql`

- [ ] **Step 1: 更新广发基金策略种子数据**

找到文件中 `gf_vstr_policy_guangfa_fund_001x` 的 INSERT 语句, 更新 `allow_zone_ids`:

```sql
-- 原内容 (~第 33 行):
  '["605560545117995008"]',

-- 改为:
  '["605560545117995008"]',
```

同步更新 `remark` 字段:

```sql
-- 原内容:
  '广发基金：访客楼层策略（组织库）；默认 28F。',

-- 改为:
  '广发基金：访客楼层策略（组织库）；默认 28F (方案A-20260509)。',
```

- [ ] **Step 2: 验证种子文件一致性**

确认 `org_id = '488b8ad049bb43408a6fbcc50bcb89ac'` 与生产库一致, `policy_type = 'INTERSECT_ALLOWLIST'` 不变。

---

### Task 4: 标记电梯侧 SQL 为废弃

**Files:**
- Modify: `docs/sql/tenant_visitor_floor_policy_init_guangfa_fund.sql`

- [ ] **Step 1: 添加废弃注释**

在文件头部添加:

```sql
-- @deprecated 2026-05-09: V2 架构中策略仅在 component-organization 库维护。
-- cw-elevator-application 不再查询此表 (PersonRuleServiceImpl.addVisitor() 
-- 已移除策略代码)。此文件保留仅供历史参考。
```

- [ ] **Step 2: 同样标记物业策略文件**

修改 `docs/sql/tenant_visitor_floor_policy_init_property_mgmt_6f.sql`:

```sql
-- @deprecated 2026-05-09: 同上。物业策略由 organization_tenant_visitor_floor_policy_init_tenants.sql 维护。
```

---

### Task 5: 功能验证

**Files:**
- (不修改文件)

- [ ] **Step 1: 验证 detail() floorList 策略生效**

```bash
# 广发基金被访人 1072908835884208128
curl -s -X POST http://127.0.0.1:18081/elevator/person/add/visitor \
  -H 'Content-Type: application/json' \
  -d '{
    "personId": "1072908835884208128",
    "businessId": "2524639890ba4f2cba9ba1a4eeaa4015",
    "visitorName": "test_28f_verify",
    "begVisitorTime": "2026-05-09 00:00:00",
    "endVisitorTime": "2026-12-31 23:59:59"
  }' | python3 -m json.tool
```

预期: 返回 `success: true`, 不返回 `76260531` (无楼层错误)。

- [ ] **Step 2: 验证 image_rule_ref 写入**

```sql
-- 使用上一步返回的 visitorId
SELECT zone_id, zone_name, person_id, parent_rule
FROM image_rule_ref
WHERE person_id = '<visitor_id_from_step1>';
```

预期: 写入行数等于 `allow_zone_ids` 中 zone 数量 (当前为 1 行, zone_name=28F)。

- [ ] **Step 3: 验证物业公司不受影响**

```bash
# 物业公司被访人 (使用不同的 personId)
curl -s -X POST http://127.0.0.1:18081/elevator/person/add/visitor \
  -H 'Content-Type: application/json' \
  -d '{
    "personId": "<物业员工personId>",
    "businessId": "2524639890ba4f2cba9ba1a4eeaa4015",
    "visitorName": "test_pm_verify",
    "begVisitorTime": "2026-05-09 00:00:00",
    "endVisitorTime": "2026-12-31 23:59:59"
  }' | python3 -m json.tool
```

预期: 返回 `success: true`, 物业访客仍获 40F 或 6F (取决于 org 归属)。

- [ ] **Step 4: 日志验证 — 确认 [GF-28F] 策略命中**

```bash
# 检查 component-org 日志 (detail 中的策略替代)
grep "POLICY\|replacementZoneIds\|allow_zone_ids" <component-org-log> | tail -5
```

预期: 日志中出现 `[POLICY] entry orgIds=[488b8ad...]` 和 allow_zone_ids 解析结果。

---

### Task 6: Commit

- [ ] **Step 1: 提交种子 SQL 变更**

```bash
git add docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql
git add docs/sql/tenant_visitor_floor_policy_init_guangfa_fund.sql
git add docs/sql/tenant_visitor_floor_policy_init_property_mgmt_6f.sql
git commit -m "docs: mark elevator-side tenant policy SQL as deprecated (V2 only queries component-org)"
```

---

## 回滚方案

```sql
-- 恢复到 28F 单层
UPDATE tenant_visitor_floor_policy
SET allow_zone_ids = '["605560545117995008"]',
    policy_version = policy_version + 1,
    remark = '广发基金：访客默认28F（回滚）',
    updated_at = UNIX_TIMESTAMP(NOW()) * 1000
WHERE id = 'gf_vstr_policy_guangfa_fund_001x';
-- 即刻生效, 无需重启
```