docs: mark elevator-side tenant policy SQL as deprecated, add guangfa visitor floor design

- Deprecate elevator-side tenant_visitor_floor_policy SQL files (V2 queries only component-organization library) - Add guangfa 28F visitor floor design spec (table-driven approach A) - Add complete database ER diagram (14 DBs, 537 tables) - Add implementation plan for guangfa visitor floor policy - Code walkthrough docs for visitor floor policy analysis
2026-06-09 08:20:31 +08:00 · 2026-05-09 23:56:12 +08:00
parent 721e88dd89
commit 42c4a9fd6b
9 changed files with 2628 additions and 1 deletions
@@ -0,0 +1,249 @@
+# 广发基金访客默认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';
+-- 即刻生效, 无需重启
+```