From 42c4a9fd6b31d82be6af43484dff79bb3b4f86b9 Mon Sep 17 00:00:00 2001 From: hpd840321 Date: Sat, 9 May 2026 23:56:12 +0800 Subject: [PATCH] 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 --- ...nant_visitor_floor_policy_init_tenants.sql | 3 +- ...visitor_floor_policy_init_guangfa_fund.sql | 6 + ...tor_floor_policy_init_property_mgmt_6f.sql | 3 + .../plans/2026-05-09-guangfa-visitor-floor.md | 249 ++++++ .../specs/2026-05-09-database-er-diagram.md | 715 ++++++++++++++++++ ...2026-05-09-guangfa-visitor-floor-design.md | 524 +++++++++++++ ...2026-05-09-guangfa-28f-hardcoded-design.md | 296 ++++++++ ...026-05-09-guangfa-hardcoded-feasibility.md | 243 ++++++ ...026-05-09-visitor-floor-policy-analysis.md | 590 +++++++++++++++ 9 files changed, 2628 insertions(+), 1 deletion(-) create mode 100644 docs/superpowers/plans/2026-05-09-guangfa-visitor-floor.md create mode 100644 docs/superpowers/specs/2026-05-09-database-er-diagram.md create mode 100644 docs/superpowers/specs/2026-05-09-guangfa-visitor-floor-design.md create mode 100644 docs/superpowers/walkthroughs/2026-05-09-guangfa-28f-hardcoded-design.md create mode 100644 docs/superpowers/walkthroughs/2026-05-09-guangfa-hardcoded-feasibility.md create mode 100644 docs/superpowers/walkthroughs/2026-05-09-visitor-floor-policy-analysis.md diff --git a/docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql b/docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql index c00e0348..d725bf44 100644 --- a/docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql +++ b/docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql @@ -1,6 +1,7 @@ -- 组织库 component-organization：广发基金 + 物业管理相关组织 — 访客楼层策略种子数据 -- 表：tenant_visitor_floor_policy（须已执行 organization_tenant_visitor_floor_policy.sql） --- 语义：组织服务按 org_id 命中；allow_zone_ids 为替代用 zoneId 列表（与电梯库种子同源）。 +-- 语义：组织服务按 org_id 命中；allow_zone_ids 为替代用 zoneId 列表。 +-- V2 策略唯一维护点：电梯侧 tenant_visitor_floor_policy 表已废弃 (V2 电梯不查询此表)。 -- -- 执行示例： -- mysql -h HOST -P PORT -u USER -p < organization_tenant_visitor_floor_policy_init_tenants.sql diff --git a/docs/sql/tenant_visitor_floor_policy_init_guangfa_fund.sql b/docs/sql/tenant_visitor_floor_policy_init_guangfa_fund.sql index 4f7a71a9..a0e8f0ad 100644 --- a/docs/sql/tenant_visitor_floor_policy_init_guangfa_fund.sql +++ b/docs/sql/tenant_visitor_floor_policy_init_guangfa_fund.sql @@ -1,3 +1,9 @@ +-- @deprecated 2026-05-09: V2 架构中策略仅在 component-organization 库维护。 +-- cw-elevator-application 不再查询此表 (PersonRuleServiceImpl.addVisitor() +-- 已移除策略代码, V2 使用 detail() 中的 TenantVisitorFloorPolicyService 替代语义)。 +-- 此文件保留仅供历史参考, 活跃策略种子见: +-- docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql +-- -- 广发基金租户：访客默认楼层策略初始化（电梯库 cw-elevator-application） -- 组织库 component-organization 同源种子：organization_tenant_visitor_floor_policy_init_tenants.sql -- diff --git a/docs/sql/tenant_visitor_floor_policy_init_property_mgmt_6f.sql b/docs/sql/tenant_visitor_floor_policy_init_property_mgmt_6f.sql index b89635db..35f25496 100644 --- a/docs/sql/tenant_visitor_floor_policy_init_property_mgmt_6f.sql +++ b/docs/sql/tenant_visitor_floor_policy_init_property_mgmt_6f.sql @@ -1,3 +1,6 @@ +-- @deprecated 2026-05-09: V2 策略仅维护 component-organization 库, 电梯侧已废弃。 +-- 活跃策略种子见: docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql +-- -- 物业公司租户：访客默认楼层策略初始化（电梯库 cw-elevator-application） -- 组织库 component-organization 同源种子：organization_tenant_visitor_floor_policy_init_tenants.sql -- allow_zone_ids：28F + 6F（JSON 顺序先 28 后 6），便于前端展示；语义仍以组织侧替代 floorList 为准。 diff --git a/docs/superpowers/plans/2026-05-09-guangfa-visitor-floor.md b/docs/superpowers/plans/2026-05-09-guangfa-visitor-floor.md new file mode 100644 index 00000000..cc479cf0 --- /dev/null +++ b/docs/superpowers/plans/2026-05-09-guangfa-visitor-floor.md @@ -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 = ''; +``` + +预期: 写入行数等于 `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" | 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'; +-- 即刻生效, 无需重启 +``` diff --git a/docs/superpowers/specs/2026-05-09-database-er-diagram.md b/docs/superpowers/specs/2026-05-09-database-er-diagram.md new file mode 100644 index 00000000..4421cecc --- /dev/null +++ b/docs/superpowers/specs/2026-05-09-database-er-diagram.md @@ -0,0 +1,715 @@ +# 星河湾星中星平台 — 完整数据库架构与 ER 关系文档 + +**日期**: 2026-05-09 +**MySQL**: 192.168.3.12:3307 (root/123456) +**状态**: 完整梳理 + +--- + +## 目录 + +1. [数据库总览](#1-数据库总览) +2. [核心库 1: component-organization](#2-component-organization-组织人员库) +3. [核心库 2: cw-elevator-application](#3-cw-elevator-application-电梯应用库) +4. [核心库 3: ninca_common](#4-ninca_common-公共组件库) +5. [辅助库: cwos_portal](#5-cwos_portal-门户管理库) +6. [辅助库: cwos_manager](#6-cwos_manager-运维管理库) +7. [辅助库: alarm_deploy](#7-alarm_deploy-报警服务库) +8. [其他库汇总](#8-其他数据库) +9. [跨库关系图 (ER)](#9-跨库关系图) +10. [访客邀约+派梯完整数据流](#10-访客邀约派梯完整数据流) + +--- + +## 1. 数据库总览 + +| # | 数据库 | 表数 | 用途 | 所属服务 | +|---|--------|------|------|---------| +| 1 | `component-organization` | 40 | 组织/人员/标签/策略 | ninca-common-component-organization | +| 2 | `cw-elevator-application` | 33 | 电梯规则/识别/记录 | cw-elevator-application | +| 3 | `ninca_common` | 38 | 区域/设备/消息/文件 | ninca-common (共享服务) | +| 4 | `cwos_portal` | 155 | 设备/图库/鉴权/账号 | cwos-portal, cwos-system-api | +| 5 | `cwos_manager` | 33 | 运维/部署/配置 | cwos-manager | +| 6 | `alarm_deploy` | 49 | 报警/布控/识别记录 | ninca-qk-alarm | +| 7 | `person_file` | 56 | 人像档案 | ninca-person-file | +| 8 | `snap_deploy` | 1 | 抓拍部署配置 | snap-app | +| 9 | `cloudwalk_device_thirdparty` | 5 | 第三方设备网关 | device-auth | +| 10 | `g` | 1 | (shard) | — | +| 11 | `ods` | 59 | 运营数据仓库 | — | +| 12 | `p` | 4 | (shard) | — | +| 13 | `xqconfig` | 59 | CRK 引擎配置 (Hash) | ninca-crk-std | +| 14 | `xqfacerecog` | 4 | CRK 人脸识别结果 | ninca-crk-std | + +**访客邀约+派梯核心链路涉及**: `component-organization` ↔ `cw-elevator-application` ↔ `ninca_common` + +--- + +## 2. component-organization (组织人员库) + +**服务**: `ninca-common-component-organization` +**连接**: `jdbc:mysql://192.168.3.12:3307/component-organization` + +### 2.1 表清单 (40 张) + +| 表名 | 用途 | 关键外键 | +|------|------|---------| +| `cw_is_person` | 人员主表 | — | +| `cw_is_person_label_ref` | 人员↔标签关联 | PERSON_ID → cw_is_person.ID, LABEL_ID → cw_is_label.ID | +| `cw_is_label` | 标签主表 | — | +| `cw_is_organization` | 组织架构主表 | PARENT_ID → cw_is_organization.ID | +| `cw_is_person_organization_ref` | 人员↔组织关联 | PERSON_ID → cw_is_person.ID, ORG_ID → cw_is_organization.ID | +| `org_floor` | 组织↔楼层关联 | org_id → cw_is_organization.ID | +| `tenant_visitor_floor_policy` | 租户访客楼层策略 | org_id → cw_is_organization.ID | +| `cw_is_group_person_ref` | 图库↔人员关联 | PERSON_ID → cw_is_person.ID, IMAGE_STORE_ID → cw_is_device_image_store.ID | +| `cw_is_device_image_store` | 图库主表 | — | +| `cw_is_image_store_associated_ref` | 图库↔组织/标签关联 | IMAGE_STORE_ID → cw_is_device_image_store.ID | +| `cw_is_device_person` | 设备人员同步 | — | +| `cw_is_device_person_sync_log` | 同步日志 | — | +| `cw_is_person_properties` | 人员属性定义 | — | +| `cw_is_person_properties_switch` | 属性开关 | — | +| `cw_is_person_audit` | 人员审核记录 | — | +| `cw_is_person_registry` | 人员注册 | — | +| `cw_is_person_registry_device` | 注册设备 | — | +| `cw_is_person_registry_properties` | 注册属性 | — | +| `cw_is_person_batch_import` | 批量导入主表 | — | +| `cw_is_person_batch_detail` | 批量导入明细 | — | +| `cw_is_organization_extend` | 组织扩展 | — | +| `cw_is_organization_extend_detail` | 组织扩展明细 | — | +| `cw_is_organization_type` | 组织类型 | — | +| `cw_is_organization_type_properties` | 组织类型属性 | — | +| `cw_is_organization_area_ref` | 组织↔区域关联 | — | +| `cw_is_organization_image_store` | 组织图库 | — | +| `cw_operation_log` | 操作日志 | — | +| `cw_task_job_everytime_details` | 定时任务 | — | +| `QRTZ_*` (11 张) | Quartz 调度表 | — | + +### 2.2 核心表 DDL + +#### cw_is_person (人员主表) + +```sql +CREATE TABLE `cw_is_person` ( + `ID` varchar(32) NOT NULL COMMENT '主键ID', + `BUSINESS_ID` varchar(32) NOT NULL COMMENT '企业ID (tenant)', + `PERSON_CODE` varchar(64) DEFAULT NULL COMMENT '人员CODE', + `NAME` varchar(64) DEFAULT NULL COMMENT '姓名', + `USER_NAME` varchar(255) DEFAULT NULL COMMENT '用户名', + `PHONE` varchar(64) DEFAULT NULL COMMENT '联系电话', + `EMAIL` varchar(64) DEFAULT NULL COMMENT '邮箱', + `STATUS` smallint(2) DEFAULT NULL COMMENT '人员状态(0有效 1无效)', + `EXPIRY_BEGIN_DATE` decimal(20,0) DEFAULT NULL COMMENT '有效期开始(时间戳)', + `EXPIRY_END_DATE` decimal(20,0) DEFAULT NULL COMMENT '有效期结束(时间戳)', + `SHOW_PICTURE` varchar(255) DEFAULT NULL COMMENT '展示照', + `COMPARE_PICTURE` text COMMENT '比对照', + `IMAGE_ID` varchar(255) DEFAULT NULL COMMENT '识别照', + `IS_DEL` smallint(2) DEFAULT NULL COMMENT '0未删除 1已删除', + `CREATE_TIME` decimal(20,0) DEFAULT NULL, + `CREATE_USER_ID` varchar(32) DEFAULT NULL, + `LAST_UPDATE_TIME` decimal(20,0) DEFAULT NULL, + `LAST_UPDATE_USER_ID` varchar(32) DEFAULT NULL, + -- EXT1~EXT40 (40个扩展字段) + `SOURCE` smallint(1) NOT NULL DEFAULT '1' COMMENT '1页面管理 2抓拍', + `IC_CARD_NO` varchar(255) DEFAULT NULL COMMENT 'IC卡号', + `IC_CARD_TYPE` varchar(255) DEFAULT NULL COMMENT 'IC卡类型', + `DEFAULT_FLOOR` varchar(255) DEFAULT NULL COMMENT '★默认楼层zone_id', + `CHOOSE_FLOOR` text COMMENT '★选中的楼层(被访人可访问楼层)', + PRIMARY KEY (`ID`), + KEY `IDX_IP_PAGE` (`IS_DEL`,`BUSINESS_ID`,`LAST_UPDATE_TIME`,`ID`,`SOURCE`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='人员信息表'; +``` + +#### cw_is_label (标签主表) + +```sql +CREATE TABLE `cw_is_label` ( + `ID` varchar(32) NOT NULL COMMENT '唯一标识', + `NAME` varchar(64) DEFAULT NULL COMMENT '标签名(如"访客")', + `CODE` varchar(64) NOT NULL COMMENT '编码(访客标签CODE="1")', + `BUSINESS_ID` varchar(32) DEFAULT NULL, + `IS_DEL` smallint(2) DEFAULT NULL COMMENT '0未删 1已删', + `ADD_TYPE` smallint(2) DEFAULT NULL COMMENT '0手动 1应用初始 2应用创建', + PRIMARY KEY (`ID`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; +``` + +#### cw_is_person_label_ref (人员↔标签关联) + +```sql +CREATE TABLE `cw_is_person_label_ref` ( + `ID` varchar(32) NOT NULL, + `PERSON_ID` varchar(32) NOT NULL COMMENT '→ cw_is_person.ID', + `LABEL_ID` varchar(32) NOT NULL COMMENT '→ cw_is_label.ID', + PRIMARY KEY (`ID`), + KEY `IDX_PERSON` (`PERSON_ID`), + KEY `IDX_LABEL` (`LABEL_ID`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='人员标签关联表'; +``` + +#### cw_is_organization (组织架构主表) + +```sql +CREATE TABLE `cw_is_organization` ( + `ID` varchar(32) NOT NULL, + `NAME` varchar(60) DEFAULT NULL COMMENT '如"[28-38F]广发基金管理有限公司"', + `PARENT_ID` varchar(32) DEFAULT NULL COMMENT '→ 自身.ID (树形)', + `BUSINESS_ID` varchar(32) DEFAULT NULL, + `TYPE_ID` varchar(32) DEFAULT NULL, + `ORDER_BY` int(2) DEFAULT NULL, + `IS_DEL` smallint(2) DEFAULT NULL, + `IS_VALID` int(2) DEFAULT NULL COMMENT '0禁用 1启用', + PRIMARY KEY (`ID`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; +``` + +#### cw_is_person_organization_ref (人员↔组织关联) + +```sql +CREATE TABLE `cw_is_person_organization_ref` ( + `ID` varchar(32) NOT NULL, + `PERSON_ID` varchar(32) NOT NULL COMMENT '→ cw_is_person.ID', + `ORG_ID` varchar(32) NOT NULL COMMENT '→ cw_is_organization.ID', + PRIMARY KEY (`ID`), + KEY `IDX_PERSON` (`PERSON_ID`), + KEY `IDX_ORG` (`ORG_ID`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='人员组织关联表'; +``` + +#### org_floor (组织↔楼层映射) + +```sql +CREATE TABLE `org_floor` ( + `org_id` varchar(64) NOT NULL COMMENT '→ cw_is_organization.ID', + `zone_id` varchar(64) DEFAULT NULL COMMENT '楼层zone_id', + `is_all` smallint(2) NOT NULL COMMENT '0-全部 1-非全部', + `zone_name` varchar(100) DEFAULT NULL COMMENT '楼层名' +) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='机构楼层对应表'; +``` + +#### tenant_visitor_floor_policy (访客楼层策略) + +```sql +CREATE TABLE `tenant_visitor_floor_policy` ( + `id` varchar(32) NOT NULL, + `business_id` varchar(64) DEFAULT NULL COMMENT 'DEPRECATED: 历史字段', + `org_id` varchar(32) DEFAULT NULL COMMENT '→ cw_is_organization.ID (★隔离键)', + `policy_type` varchar(32) NOT NULL DEFAULT 'INTERSECT_ALLOWLIST' COMMENT '策略类型(历史命名;语义为替代)', + `allow_zone_ids` text COMMENT '★ JSON数组 zoneId列表', + `building_id` varchar(64) DEFAULT NULL, + `enabled` tinyint(1) NOT NULL DEFAULT '1' COMMENT '1启用 0停用', + `policy_version` bigint(20) NOT NULL DEFAULT '1', + `remark` varchar(256) DEFAULT NULL, + PRIMARY KEY (`id`), + UNIQUE KEY `uk_org_building` (`org_id`,`building_id`), + KEY `idx_org_enabled` (`org_id`,`enabled`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='租户访客楼层策略(组织库;detail/访客列表替代floorList)'; +``` + +**当前数据 (广发基金)**: +- `id` = `gf_vstr_policy_guangfa_fund_001x` +- `org_id` = `488b8ad049bb43408a6fbcc50bcb89ac` +- `allow_zone_ids` = `["605560545117995008"]` (仅 28F) +- `enabled` = 1 + +#### cw_is_group_person_ref (图库↔人员) + +```sql +CREATE TABLE `cw_is_group_person_ref` ( + `ID` varchar(32) NOT NULL, + `IMAGE_STORE_ID` varchar(32) DEFAULT NULL COMMENT '→ 图库', + `PERSON_ID` varchar(32) DEFAULT NULL COMMENT '→ cw_is_person.ID', + `EXPIRY_BEGIN_DATE` decimal(20,0) DEFAULT NULL, + `EXPIRY_END_DATE` decimal(20,0) DEFAULT NULL, + `STATUS` smallint(2) DEFAULT '0' COMMENT '-1删除 0正常 1失效', + `GROUP_STATUS` smallint(1) DEFAULT NULL COMMENT '0未建模 1建模中 2完成 3失败', + PRIMARY KEY (`ID`), + KEY `IDX_IGPR_PERSON` (`IMAGE_STORE_ID`,`PERSON_ID`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; +``` + +### 2.3 组织库 ER 关系图 + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ component-organization │ +│ │ +│ ┌─────────────────┐ ┌───────────────────┐ │ +│ │ cw_is_person │ │ cw_is_label │ │ +│ │ ID (PK) │ │ ID (PK) │ │ +│ │ BUSINESS_ID │ │ NAME ("访客") │ │ +│ │ NAME │ │ CODE ("1") │ │ +│ │ DEFAULT_FLOOR │ └────────┬──────────┘ │ +│ │ CHOOSE_FLOOR │ │ │ +│ └──┬──────┬───────┘ │ │ +│ │ │ │ │ +│ │ │ ┌───────────────────┴──────────┐ │ +│ │ │ │ cw_is_person_label_ref │ │ +│ │ │ │ PERSON_ID → cw_is_person │ │ +│ │ │ │ LABEL_ID → cw_is_label │ │ +│ │ │ └──────────────────────────────┘ │ +│ │ │ │ +│ │ └────────────────────────────┐ │ +│ │ │ │ +│ │ ┌─────────────────────────────────┴──────────┐ │ +│ │ │ cw_is_person_organization_ref │ │ +│ │ │ PERSON_ID → cw_is_person │ │ +│ │ │ ORG_ID → cw_is_organization │ │ +│ │ └────────────┬───────────────────────────────┘ │ +│ │ │ │ +│ │ ┌────────────┴────────────────┐ │ +│ │ │ cw_is_organization │ │ +│ │ │ ID (PK) │ │ +│ │ │ NAME │ │ +│ │ │ PARENT_ID → 自身 (树形) │ │ +│ │ └──┬─────────────┬────────────┘ │ +│ │ │ │ │ +│ │ │ ┌─────────┴──────────────┐ │ +│ │ │ │ org_floor │ │ +│ │ │ │ org_id → organization │ │ +│ │ │ │ zone_id │ │ +│ │ │ └────────────────────────┘ │ +│ │ │ │ +│ │ │ ┌──────────────────────────────┐ │ +│ │ │ │ tenant_visitor_floor_policy │ │ +│ │ │ │ org_id → organization (★) │ │ +│ │ │ │ allow_zone_ids (JSON) │ │ +│ │ │ │ enabled (0/1) │ │ +│ │ │ └──────────────────────────────┘ │ +│ │ │ │ +│ │ ┌──┴──────────────────────────────┐ │ +│ │ │ cw_is_group_person_ref │ │ +│ └──│ PERSON_ID → cw_is_person │ │ +│ │ IMAGE_STORE_ID → 图库 │ │ +│ └──────────────────────────────────┘ │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +**关键关联链 (访客邀约)**: +``` +PersonService.detail(personId) + → cw_is_person + cw_is_person_organization_ref → 获取 organizationIds + → cw_is_person_label_ref → 获取 labelIds + → tenant_visitor_floor_policy (按 org_id) → allow_zone_ids (替代 floorList) + → 返回 PersonResult { floorList, labelIds, organizationIds } +``` + +--- + +## 3. cw-elevator-application (电梯应用库) + +**服务**: `cw-elevator-application` +**连接**: ShardingSphere → `jdbc:mysql://mysql_01:3306/cw-elevator-application` +**特征**: 识别/电梯记录表按**年份分表** (2020-2030) + +### 3.1 表清单 (33 张) + +| 表名 | 用途 | 分区 | +|------|------|------| +| `image_rule_ref` | ★通行规则(核心) — 人员/标签/组织↔楼层 | — | +| `code_elevator_area` | 电梯区号与编码对照 | — | +| `it_acs_pass_rule` | 通行规则主表 | — | +| `it_acs_recog_record` | 识别记录 | 按年: `_2020` ~ `_2030` | +| `it_acs_elevator_record` | 电梯乘坐记录 | 按年: `_2020` ~ `_2030` | +| `elevator_device` | 电梯设备 | — | +| `device_image_store` | 设备图库关联 | — | +| `it_acs_device_task` | 设备任务 | — | +| `send_record_time` | 发送记录时间 | — | +| `send_record_timebak` | 发送记录时间备份 | — | +| `tenant_visitor_floor_policy` | ⚠️ V1历史遗留 (V2不查询) | — | + +### 3.2 核心表 DDL + +#### image_rule_ref (★通行规则 — 最核心) + +```sql +CREATE TABLE `image_rule_ref` ( + `id` varchar(32) NOT NULL, + `zone_id` varchar(64) NOT NULL COMMENT '★楼层zone_id → code_elevator_area.zone_id', + `zone_name` varchar(64) DEFAULT NULL COMMENT '楼层名(如28F)', + `name` varchar(64) DEFAULT NULL COMMENT '规则名', + `person_id` varchar(64) DEFAULT NULL COMMENT '★人员id → cw_is_person.ID', + `include_labels` varchar(64) DEFAULT NULL COMMENT '★包含标签ID(单值) → cw_is_label.ID', + `include_organizations` varchar(64) DEFAULT NULL COMMENT '★包含组织ID(单值) → cw_is_organization.ID', + `exclude_labels` varchar(64) DEFAULT NULL COMMENT '排除标签ID', + `is_default` tinyint(1) DEFAULT '0' COMMENT '是否默认规则', + `start_time` bigint(20) DEFAULT NULL, + `end_time` bigint(20) DEFAULT NULL, + `create_time` bigint(20) DEFAULT NULL, + `last_update_time` bigint(20) DEFAULT NULL, + `business_id` varchar(64) DEFAULT NULL COMMENT '企业id', + `parent_rule` varchar(64) DEFAULT NULL COMMENT '归属规则id → it_acs_pass_rule.ID', + `person_delete` tinyint(1) DEFAULT '0' COMMENT '人员是否已删除', + PRIMARY KEY (`id`), + KEY `image_rule_ref_include_labels_IDX` (`include_labels`), + KEY `image_rule_ref_include_organizations_IDX` (`include_organizations`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='通行规则信息表(★访客权限核心)'; +``` + +**关键查询** (`listByPersonInfo` — 决定楼层访问): +```sql +SELECT DISTINCT zone_id, zone_name +FROM image_rule_ref +WHERE person_id = #{personId} AND person_delete = 0 + OR include_labels IN (...) + OR include_organizations IN (...) +ORDER BY CAST(zone_name as signed) ASC +``` + +#### code_elevator_area (电梯区号编码) + +```sql +CREATE TABLE `code_elevator_area` ( + `zone_id` varchar(64) NOT NULL COMMENT '★电梯编码(如 605560545117995008)', + `code` varchar(64) NOT NULL COMMENT '地区编码(如 0x1C=28F)', + `create_time` bigint(13) DEFAULT NULL, + `last_update_time` bigint(13) DEFAULT NULL, + `is_first` tinyint(4) DEFAULT NULL COMMENT '是否首层', + `parent_id` varchar(64) DEFAULT NULL COMMENT '父级id(楼栋)', + PRIMARY KEY (`zone_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='电梯编码'; +``` + +**已知 zone_id**: +| zone_id | zone_name | code | parent_id (楼栋) | +|---------|-----------|------|-------------------| +| 605560547135455232 | 40F | — | 605560539791228928 | +| 605560541473144832 | 6F | — | 605560539791228928 | +| 605560545117995008 | 28F | 0x1C | 605560539791228928 | +| 605560539791228928 | (楼栋) | — | — | + +#### it_acs_pass_rule (通行规则主表) + +```sql +CREATE TABLE `it_acs_pass_rule` ( + `ID` varchar(32) NOT NULL, + `BUSINESS_ID` varchar(32) NOT NULL, + `ZONE_ID` varchar(32) NOT NULL COMMENT '楼层ID', + `ZONE_NAME` varchar(100) DEFAULT NULL, + `NAME` varchar(200) NOT NULL COMMENT '通行规则名称', + `IMAGE_STORE_ID` varchar(32) NOT NULL COMMENT '图库id', + `IS_DEFAULT` tinyint(1) DEFAULT '0', + PRIMARY KEY (`ID`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='通行规则表'; +``` + +#### it_acs_recog_record (识别记录 — 按年分表) + +```sql +CREATE TABLE `it_acs_recog_record` ( + `ID` varchar(32) NOT NULL, + `PERSON_ID` varchar(64) DEFAULT NULL, + `PERSON_NAME` varchar(64) DEFAULT NULL, + `BUSINESS_ID` varchar(32) NOT NULL, + `DEVICE_ID` varchar(64) DEFAULT NULL, + `DEVICE_CODE` varchar(64) NOT NULL, + `RECOGNITION_RESULT` tinyint(1) DEFAULT NULL COMMENT '1成功 2失败', + `RECOGNITION_TIME` bigint(255) NOT NULL, + `PERSON_LABEL_IDS` text COMMENT '★人员标签ID列表(用于MQTT访客判断)', + `SCORE` decimal(10,6) NOT NULL COMMENT '识别分数', + PRIMARY KEY (`ID`), + KEY `it_acs_recog_record_PERSON_ID_IDX` (`PERSON_ID`,`DEVICE_ID`,`RECOGNITION_TIME`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='识别记录表'; +``` + +**分表策略**: `it_acs_recog_record_2020` ~ `it_acs_recog_record_2030` (11 张) + +#### elevator_device (电梯设备) + +```sql +CREATE TABLE `elevator_device` ( + `ID` bigint(20) NOT NULL AUTO_INCREMENT, + `device_id` varchar(64) DEFAULT NULL, + `device_name` varchar(64) NOT NULL COMMENT '设备名称', + `current_floor_id` varchar(64) DEFAULT NULL COMMENT '当前楼层zone_id', + `current_floor` varchar(64) DEFAULT NULL COMMENT '当前楼层名', + `elevator_floor_list` varchar(255) DEFAULT NULL COMMENT '★派梯楼层(逗号分隔)', + `elevator_floor_id_list` varchar(1000) DEFAULT NULL COMMENT '★派梯楼层ID', + `business_id` varchar(32) NOT NULL COMMENT '租户id', + PRIMARY KEY (`ID`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='派梯设备'; +``` + +### 3.3 电梯库 ER 关系图 + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ cw-elevator-application │ +│ │ +│ ┌───────────────────────┐ ┌─────────────────────┐ │ +│ │ it_acs_pass_rule │ │ code_elevator_area │ │ +│ │ ID (PK) │ │ zone_id (PK) │ │ +│ │ ZONE_ID │──┐ │ code │ │ +│ │ ZONE_NAME │ │ │ parent_id(楼栋) │ │ +│ │ IMAGE_STORE_ID │ │ └──────────┬──────────┘ │ +│ └───────────┬───────────┘ │ │ │ +│ │ │ │ │ +│ ┌───────────┴──────────────┴───────────────┴───────┐ │ +│ │ image_rule_ref (★核心) │ │ +│ │ zone_id ← code_elevator_area.zone_id │ │ +│ │ person_id ← cw_is_person.ID │ │ +│ │ include_labels ← cw_is_label.ID (单值) │ │ +│ │ include_organizations ← cw_is_organization.ID │ │ +│ │ parent_rule ← it_acs_pass_rule.ID │ │ +│ │ is_default (0/1) │ │ +│ └───────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────┐ ┌─────────────────────┐ │ +│ │ elevator_device │ │ it_acs_recog_record │ │ +│ │ device_id │ │ PERSON_LABEL_IDS │ │ +│ │ elevator_floor_list │ │ RECOGNITION_TIME │ │ +│ │ elevator_floor_id_list│ │ (按年分表 2020-2030)│ │ +│ └───────────────────────┘ └─────────────────────┘ │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +**image_rule_ref 三种访问模式**: +``` +1. person_id 直连: WHERE person_id = X AND person_delete = 0 +2. 标签关联: WHERE include_labels = X (人员标签匹配此标签) +3. 组织关联: WHERE include_organizations = X (人员组织匹配此组织) +``` + +--- + +## 4. ninca_common (公共组件库) + +**服务**: `ninca-common` (共享服务, 通过 Feign 调用) +**连接**: `jdbc:mysql://mysql_01:3306/ninca_common` (推测) + +### 4.1 关键表 + +| 表名 | 用途 | +|------|------| +| `cw_qz_zone` | ★区域/楼层定义表 — zone_id 的主数据源 | +| `cw_qz_zone_unit_ref` | 区域↔单元关联 | +| `cw_qz_zone_type` | 区域类型 | +| `cw_qz_device_area` | 设备区域 | +| `cw_qz_district_map` | 区域地图 | +| `cw_qz_message_*` (7 张) | 消息/通知系统 | +| `cw_qz_file_*` (4 张) | 文件管理 | +| `QRTZ_*` (11 张) | Quartz 调度 | + +#### cw_qz_zone (区域/楼层主数据) + +```sql +CREATE TABLE `cw_qz_zone` ( + `ID` varchar(32) DEFAULT NULL COMMENT 'zone_id', + `CODE` varchar(32) DEFAULT NULL, + `LEVEL` int(11) DEFAULT NULL, + `NAME` varchar(64) DEFAULT NULL COMMENT '区域名(如"28F")', + `PARENT_ID` varchar(32) DEFAULT NULL COMMENT '父级(楼栋)', + `BUSINESS_ID` varchar(32) DEFAULT NULL, + `TYPE_ID` varchar(32) DEFAULT NULL, + PRIMARY KEY ... (无显式PK定义) +) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='区域表'; +``` + +**Feign 接口**: `ZoneFeignClient.findZonelist()` → `POST /sysetting/zone/list` (component-org 通过此接口解析 zone_id → zone_name) + +--- + +## 5. cwos_portal (门户管理库) + +**155 张表** — 平台最大数据库，涵盖: 设备管理、图库管理、鉴权认证、账号系统、识别引擎配置 + +### 5.1 核心模块表 + +| 模块 | 关键表 | 用途 | +|------|--------|------| +| 账号 | `cw_ac_account`, `cw_ac_business` | ★租户/企业账号 | +| 鉴权 | `cw_auth_secret`, `cw_auth_secret_application` | API Key 管理 | +| 图库 | `cw_ag_image_store`, `cw_ag_image`, `cw_ag_image_store_image` | 人脸底库 | +| 设备 | `cw_ge_device`, `cw_ge_device_camera`, `cw_ge_area` | 设备/摄像头/区域 | +| 算法引擎 | `cw_de_group`, `cw_de_service`, `cw_de_sub_group` | CRK 引擎分组 | +| 模型 | `cw_de_model_upgrade_task` | 模型升级 | + +### 5.2 关键关联: 图库系统 + +``` +cw_ag_image_store (图库) + → cw_ag_application_image_store (应用↔图库) + → cw_ag_device_image_store (设备↔图库) + → cw_ag_image_store_image (图库内的图片) + → cw_ag_image (图片) +``` + +--- + +## 6. cwos_manager (运维管理库) + +**33 张表** — 部署/运维管理: 应用、组件、节点、配置、操作日志 + +--- + +## 7. alarm_deploy (报警服务库) + +**49 张表** — 人脸/车辆/行为报警系统 + +### 7.1 核心表 + +| 表名 | 用途 | +|------|------| +| `cw_alarm_control_task` | 布控任务 | +| `cw_alarm_control_task_device` | 布控↔设备关联 | +| `cw_alarm_control_task_group` | 布控↔底库关联 | +| `cw_alarm_blacklist_record` | ★黑名单报警记录 | +| `cw_alarm_stranger_record` | ★陌生人报警 | +| `cw_alarm_face_properties_record` | 人脸属性报警 | +| `cw_alarm_plate_record` | 车牌报警 | +| `three_level_control_record` | ★三级布控记录(含 grab_floor) | + +--- + +## 8. 其他数据库 + +| 数据库 | 表数 | 核心表 | 用途 | +|--------|------|--------|------| +| `person_file` | 56 | 人像档案表 | 抓拍人像存档 | +| `snap_deploy` | 1 | 抓拍配置 | snap-app 部署 | +| `cloudwalk_device_thirdparty` | 5 | `gw_thirdparty_device_*` | 第三方设备网关 | +| `g` | 1 | shard | — | +| `ods` | 59 | 运营数据 | ODS 数据仓库 | +| `p` | 4 | shard | — | +| `xqconfig` | 59 | `hash*` (CRK 引擎配置) | ninca-crk-std | +| `xqfacerecog` | 4 | `recogdbforface*` | CRK 识别结果分片 | + +--- + +## 9. 跨库关系图 (ER) + +### 9.1 平台级 ER 总图 + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 星河湾星中星 平台 ER │ +│ │ +│ ┌─ component-organization ───────────────────────────────────────┐ │ +│ │ │ │ +│ │ cw_is_person ──┬── cw_is_person_label_ref ── cw_is_label │ │ +│ │ │ │ │ +│ │ ├── cw_is_person_organization_ref ── cw_is_organization ││ +│ │ │ ├── org_floor │ │ +│ │ │ └── tenant_visitor_floor_policy (★策略) │ │ +│ │ │ │ │ +│ │ └── cw_is_group_person_ref ── IMAGE_STORE_ID │ │ +│ └──────────────────────┬───────────────────────────────────────────┘ │ +│ │ zone_id (via Feign) │ +│ ┌─ cw-elevator-application ──────────────────────────────────────┐ │ +│ │ │ │ +│ │ code_elevator_area (zone_id, code, parent_id) │ │ +│ │ ▲ │ │ +│ │ │ zone_id │ │ +│ │ image_rule_ref ── person_id ──→ cw_is_person.ID │ │ +│ │ ├── include_labels ──→ cw_is_label.ID │ │ +│ │ ├── include_organizations ──→ cw_is_organization.ID │ │ +│ │ └── parent_rule ──→ it_acs_pass_rule.ID │ │ +│ │ │ │ +│ │ it_acs_recog_record ── PERSON_ID ──→ cw_is_person.ID │ │ +│ │ ── PERSON_LABEL_IDS (★访客判断: "1"=访客) │ │ +│ └──────────────────────┬───────────────────────────────────────────┘ │ +│ │ zone_id (via Feign ZoneFeignClient) │ +│ ┌─ ninca_common ──────────────────────────────────────────────────┐ │ +│ │ cw_qz_zone (★zone主数据: ID, NAME, PARENT_ID) │ │ +│ │ cw_qz_zone_unit_ref │ │ +│ │ cw_qz_device_area │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ cwos_portal ───────────────────────────────────────────────────┐ │ +│ │ cw_ac_business (★BUSINESS_ID主数据) ── cw_ac_account │ │ +│ │ cw_ag_image_store (图库) ── cw_ag_image (图片) │ │ +│ │ cw_ge_device (设备) ── cw_ge_device_camera (摄像头) │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +### 9.2 关键跨库关联 + +| 关联 | 从库 | 从表.字段 | 到库 | 到表.字段 | 类型 | +|------|------|----------|------|----------|------| +| 人员↔楼层规则 | cw-elevator-app | `image_rule_ref.person_id` | component-org | `cw_is_person.ID` | 逻辑外键 | +| 标签↔楼层规则 | cw-elevator-app | `image_rule_ref.include_labels` | component-org | `cw_is_label.ID` | 逻辑外键 | +| 组织↔楼层规则 | cw-elevator-app | `image_rule_ref.include_organizations` | component-org | `cw_is_organization.ID` | 逻辑外键 | +| 楼层编码↔主数据 | cw-elevator-app | `code_elevator_area.zone_id` | ninca_common | `cw_qz_zone.ID` | 逻辑外键 | +| 策略↔组织 | component-org | `tenant_visitor_floor_policy.org_id` | component-org | `cw_is_organization.ID` | ⚠️ 同库 | +| 访客标签判断 | cw-elevator-app | `it_acs_recog_record.PERSON_LABEL_IDS` | component-org | `cw_is_label.CODE = "1"` | 业务规则 | +| 企业ID | component-org | `cw_is_person.BUSINESS_ID` | cwos_portal | `cw_ac_business.ID` | 逻辑外键 | + +--- + +## 10. 访客邀约+派梯完整数据流 + +### 10.1 邀约页加载 + +``` +Step 1: 前端 → POST /component/person/detail + ├─ component-org: cw_is_person WHERE ID = personId + ├─ cw_is_person_label_ref JOIN cw_is_label → labelIds, labelNames + ├─ cw_is_person_organization_ref JOIN cw_is_organization → organizationIds + │ + ├─ ★ 策略检查: tenant_visitor_floor_policy + │ WHERE org_id = ? AND enabled = 1 + │ → allow_zone_ids = ["605560545117995008"] (28F) + │ + ├─ 未命中策略 → Feign: elevator-app POST /elevator/passRule/image + │ → image_rule_ref: SELECT DISTINCT zone_id, zone_name + │ WHERE person_id = X AND person_delete = 0 + │ OR include_labels IN (...) + │ OR include_organizations IN (...) + │ → code_elevator_area: 获取 zone_id 对应的 code + │ + └─ 返回 PersonResult { floorList: [28F_zone_id], labelIds, organizationIds } +``` + +### 10.2 派梯执行 + +``` +Step 2: 前端 → POST /elevator/person/add/visitor + ├─ elevator-app: PersonRuleServiceImpl.addVisitor() + │ + ├─ Feign: component-org POST /component/person/detail (回查) + │ → 返回 floorList = [28F_zone_id] (策略已替代) + │ + ├─ UC-02: floorIds 非空 → effective = param.floorIds = [28F_zone_id] + │ UC-01: floorIds 为空 → effective = detail.floorList = [28F_zone_id] + │ + ├─ ★ 无校验: floorIds 是否是 host floorList 的子集 (V2 不做交集) + │ + ├─ elevator-app: image_rule_ref.getDefaultByZoneId(28F_zone_id) + │ → SELECT * FROM image_rule_ref WHERE zone_id=? AND is_default=1 + │ + ├─ elevator-app: INSERT INTO image_rule_ref + │ (person_id = visitorId, zone_id = 28F, parent_rule = defaultRule.id) + │ + ├─ Feign: component-org POST /component/imagestore/person/batchBind + │ → cw_is_group_person_ref: INSERT (person_id = visitorId, image_store_id = ?) + │ + └─ Feign: updateGroupPersonRef → 更新组人员引用 +``` + +### 10.3 识别派梯 (MQTT 实时) + +``` +Step 3: 人脸识别 → 电梯派梯 (实时) + ├─ it_acs_recog_record: INSERT 识别记录 + │ PERSON_LABEL_IDS = "1" → 判定 isVisitor = true + │ + ├─ MqttServiceImpl: 检查 PERSON_LABEL_IDS.contains("1") + │ → isVisitor = TRUE → 按访客逻辑派梯 + │ + ├─ image_rule_ref: 查询访客的规则行 + │ WHERE person_id = visitorId + │ → zone_id = 28F + │ + └─ elevator_device: 派梯到对应楼层 + elevator_floor_list / elevator_floor_id_list +``` + +### 10.4 关键业务规则 + +| 规则 | 位置 | 说明 | +|------|------|------| +| 访客标签CODE="1" | `cw_is_label.CODE` + `it_acs_recog_record.PERSON_LABEL_IDS` | MQTT 中判断 `isVisitor` | +| 访客列表排除"访客"标签的人 | `ImgPersonServiceImpl.listByPage` L374-377 | `labelNames.contains("访客") → continue` | +| 策略替代 floorList | `tenant_visitor_floor_policy` → `ImgPersonServiceImpl.detail()` L643-648 | org_id 命中 → allow_zone_ids 替换 | +| 40F/6F 硬编码默认 | `ImgPersonServiceImpl.listByPage` L354-370 | xhwId→40F, else→6F | +| addVisitor 无交集校验 | `PersonRuleServiceImpl.addVisitor()` | UC-02 floorIds 任意值均可 | +| addVisitor 无 defaultRule 检查 | `PersonRuleServiceImpl.addVisitor()` L222 | `getDefaultByZoneId` 返回 null → NPE | diff --git a/docs/superpowers/specs/2026-05-09-guangfa-visitor-floor-design.md b/docs/superpowers/specs/2026-05-09-guangfa-visitor-floor-design.md new file mode 100644 index 00000000..1b9ccdad --- /dev/null +++ b/docs/superpowers/specs/2026-05-09-guangfa-visitor-floor-design.md @@ -0,0 +1,524 @@ +# 广发基金访客默认28F — 架构设计文档 + +**日期**: 2026-05-09 +**状态**: 评审通过 (方案A: 表驱动, 单库维护) +**读者**: 架构师 / 技术评审 + +--- + +## 目录 + +1. [架构决策摘要](#1-架构决策摘要) +2. [数据结构关系 — 完整 ER 图](#2-数据结构关系--完整-er-图) +3. [业务数据流 — 访客邀约+派梯全链路](#3-业务数据流--访客邀约派梯全链路) +4. [方案A实现详解](#4-方案a实现详解) +5. [方案合理性论证](#5-方案合理性论证) +6. [附录: 关键表DDL](#6-附录-关键表ddl) + +--- + +## 1. 架构决策摘要 + +| 决策项 | 选择 | 理由 | +|--------|------|------| +| 策略存储 | `tenant_visitor_floor_policy` 表 (component-organization 库) | V2 已实现，代码就绪 | +| 策略语义 | 替代 (Replacement)，非求交 (Intersection) | 产品需求: 策略启用时整表替换 floorList | +| 隔离键 | `org_id` (组织节点) | 多租户共享同一 `business_id`, 需组织级隔离 | +| 策略生效点 | `ImgPersonServiceImpl.detail()` L643-648 | 邀约页初始化 + UC-01 派梯兜底 | +| 数据库维护 | 仅 component-organization | V2 电梯侧不查询此表 | +| 代码变更 | **0 行** | UPDATE 1 条 SQL | + +### 本质认知 + +广发基金 28F 策略**不是一个新需求** — 它是当前 `tenant_visitor_floor_policy` 表驱动架构的**已有实例**。当前生产库中已存在该策略行（`enabled=1`），且 `ImgPersonServiceImpl.detail()` 的 L643-648 已经在执行策略替代逻辑。扩展至 20 层是**纯数据变更**。 + +--- + +## 2. 数据结构关系 — 完整 ER 图 + +### 2.1 涉及三库的核心表 + +``` +┌── component-organization ───────────────────────────────────────────┐ +│ │ +│ cw_is_person cw_is_label │ +│ ├─ ID (PK) ├─ ID (PK) │ +│ ├─ BUSINESS_ID (FK→portal) ├─ NAME ("访客") │ +│ ├─ NAME ├─ CODE ("1") │ +│ ├─ DEFAULT_FLOOR (zone_id) └──────────────────┐ │ +│ └─ CHOOSE_FLOOR (zone_id list) │ │ +│ │ │ │ +│ ├── cw_is_person_label_ref ───────────────────┘ │ +│ │ ├─ PERSON_ID (FK→person) │ +│ │ └─ LABEL_ID (FK→label) │ +│ │ │ +│ ├── cw_is_person_organization_ref │ +│ │ ├─ PERSON_ID (FK→person) │ +│ │ └─ ORG_ID (FK→organization) ──────────┐ │ +│ │ │ │ +│ cw_is_organization │ │ +│ ├─ ID (PK) ◄────────────────────────────────────────┘ │ +│ ├─ NAME ("[28-38F]广发基金管理有限公司") │ +│ ├─ PARENT_ID (FK→自身, 树形) │ +│ ├─ BUSINESS_ID (FK→portal) │ +│ └─ IS_VALID │ +│ │ │ +│ ├── org_floor │ +│ │ ├─ org_id (FK→organization) │ +│ │ └─ zone_id (逻辑FK→code_elevator_area) │ +│ │ │ +│ └── tenant_visitor_floor_policy ★ 策略表 │ +│ ├─ id = 'gf_vstr_policy_guangfa_fund_001x' │ +│ ├─ org_id (FK→organization, UNIQUE) │ +│ ├─ allow_zone_ids (JSON数组 zone_id列表) │ +│ ├─ enabled (0/1) │ +│ └─ policy_version (自增) │ +└───────────────────────────────────────────────────────────────────────┘ + │ + │ zone_id (逻辑外键, 非数据库约束) + ▼ +┌── cw-elevator-application ───────────────────────────────────────────┐ +│ │ +│ code_elevator_area │ +│ ├─ zone_id (PK) ◄──── 所有 zone_id 的权威来源 │ +│ ├─ code (如 0x1C=28F) │ +│ ├─ parent_id (楼栋 building_id) │ +│ └─ is_first (是否首层) │ +│ │ +│ image_rule_ref ★ 通行规则 │ +│ ├─ person_id (逻辑FK→cw_is_person) │ +│ ├─ include_labels (逻辑FK→cw_is_label, 单值) │ +│ ├─ include_organizations (逻辑FK→cw_is_organization, 单值) │ +│ ├─ zone_id (FK→code_elevator_area) │ +│ ├─ zone_name │ +│ ├─ parent_rule (FK→it_acs_pass_rule) │ +│ └─ is_default (0/1) │ +│ │ +│ it_acs_pass_rule │ +│ ├─ ID (PK) ◄─── image_rule_ref.parent_rule │ +│ ├─ ZONE_ID (FK→code_elevator_area) │ +│ └─ IMAGE_STORE_ID (FK→cwos_portal.cw_ag_image_store) │ +└───────────────────────────────────────────────────────────────────────┘ + │ + │ zone_id (逻辑外键, Feign查询) + ▼ +┌── ninca_common ──────────────────────────────────────────────────────┐ +│ │ +│ cw_qz_zone ★ zone 主数据 │ +│ ├─ ID (zone_id) ◄──── Feign: ZoneFeignClient.findZonelist() │ +│ ├─ NAME ("28F") │ +│ ├─ PARENT_ID (楼栋/上级区域) │ +│ ├─ BUSINESS_ID │ +│ └─ LEVEL │ +└───────────────────────────────────────────────────────────────────────┘ +``` + +### 2.2 关键实体关系 + +| 关系 | 类型 | 说明 | +|------|------|------| +| Person → Organization | N:N | `cw_is_person_organization_ref` 关联表 | +| Person → Label | N:N | `cw_is_person_label_ref` 关联表 | +| Organization → Floor (org_floor) | 1:N | 组织可关联多个楼层 | +| Organization → Policy (tenant_visitor_floor_policy) | 1:1 | `uk_org_building` 唯一约束 | +| Policy → Floor (allow_zone_ids) | 1:N | JSON 数组存储 | +| image_rule_ref → Person/Zone | N:1 | 每条规则绑定一个人员+楼层 | +| image_rule_ref → PassRule | N:1 | `parent_rule` 指向默认规则模板 | + +### 2.3 广发基金当前数据快照 + +```sql +-- cw_is_organization (广发基金组织节点) +ID = '488b8ad049bb43408a6fbcc50bcb89ac' +NAME = '[28-38F]广发基金管理有限公司' +BUSINESS_ID = '2524639890ba4f2cba9ba1a4eeaa4015' -- 星河湾中心 + +-- tenant_visitor_floor_policy (当前策略) +id = 'gf_vstr_policy_guangfa_fund_001x' +org_id = '488b8ad049bb43408a6fbcc50bcb89ac' +allow_zone_ids = '["605560545117995008"]' -- 仅 28F +enabled = 1 +policy_version = 1 + +-- code_elevator_area (28F zone) +zone_id = '605560545117995008' +code = 0x1C +parent_id = '605560539791228928' -- 星河湾中心楼栋 +``` + +--- + +## 3. 业务数据流 — 访客邀约+派梯全链路 + +### 3.1 核心业务前提 + +**一个关键事实**: 广发基金和物业公司共享同一个 `BUSINESS_ID = 2524639890ba4f2cba9ba1a4eeaa4015` (星河湾中心)。这意味着: +- 不能使用 `business_id` 做策略隔离 +- 必须使用 `org_id` 做细粒度隔离 +- `tenant_visitor_floor_policy.uk_org_building(org_id, building_id)` 保证了每个组织节点唯一一条策略 + +### 3.2 完整数据流 (6 步骤) + +``` +═══════════════════════════════════════════════════════════════════════════ + Step 1: 前端打开访客邀约页 — 选择被访人(广发员工) +═══════════════════════════════════════════════════════════════════════════ + + 前端 → POST /component/person/detail { id: "广发员工personId" } + │ + ├─ DB: cw_is_person WHERE ID = personId + │ → NAME, PHONE, DEFAULT_FLOOR, CHOOSE_FLOOR + │ + ├─ DB: cw_is_person_organization_ref WHERE PERSON_ID = personId + │ → orgIds = ['488b8ad...'] (广发基金) + │ + ├─ DB: cw_is_person_label_ref WHERE PERSON_ID = personId + │ → labelIds = ['someLabelId', ...] + │ + ├─ Feign → elevator: POST /elevator/passRule/image + │ { personId, includeLabels, includeOrganizations } + │ │ + │ ├─ DB: image_rule_ref + │ │ SELECT DISTINCT zone_id,zone_name + │ │ WHERE person_id=X AND person_delete=0 + │ │ OR include_labels IN (...) + │ │ OR include_organizations IN (...) + │ │ → 返回被访人所有可访问楼层 (如: 28F,...,38F 共11层) + │ │ + │ └─ 返回: [{zone_id:"28F",zone_name:"28F"}, ...] + │ + ├─ ★ 策略替代 (ImgPersonServiceImpl.detail() L643-648): + │ DB: tenant_visitor_floor_policy + │ SELECT * WHERE org_id='488b8ad...' AND enabled=1 + │ → allow_zone_ids = ["28F_zone_id"] + │ + │ floorList = ["28F_zone_id"] ← 替换! 不再是11层 + │ zoneNames = "28F" + │ + └─ 返回: PersonResult { floorList: ["28F_zone_id"], floorNames: "28F" } + + 前端收到 floorList = [28F] → 渲染: ☑ 28F (唯一可选楼层) + +═══════════════════════════════════════════════════════════════════════════ + Step 2: 用户填写访客信息 + 确认楼层 → 提交 +═══════════════════════════════════════════════════════════════════════════ + + 前端 → POST /elevator/person/add/visitor + { personId: "广发员工", visitorId: "新访客", + floorIds: ["28F_zone_id"], begVisitorTime, endVisitorTime } + │ + ├─ Feign → component-org: POST /component/person/detail (回查) + │ → floorList = ["28F_zone_id"] (策略已生效) + │ + ├─ UC-02 判定: param.floorIds 非空 + │ effective = ["28F_zone_id"] + │ + ├─ DB: image_rule_ref + │ SELECT * WHERE zone_id='28F' AND is_default=1 + │ → 获取默认规则模板 (parent_rule, name, zoneName) + │ + ├─ DB: image_rule_ref INSERT + │ (person_id=visitorId, zone_id=28F, parent_rule=defaultRule.id) + │ + ├─ Feign → component-org: POST /component/imagestore/person/batchBind + │ (personId=visitorId, imageStoreId, expiry dates) + │ → DB: cw_is_group_person_ref INSERT + │ + └─ 返回: success + +═══════════════════════════════════════════════════════════════════════════ + Step 3: 访客到达 — 人脸识别 → 自动派梯 +═══════════════════════════════════════════════════════════════════════════ + + 设备识别 → DB: it_acs_recog_record INSERT + { PERSON_ID: visitorId, PERSON_LABEL_IDS: "1", ... } + │ + ├─ MQTT 判定: PERSON_LABEL_IDS.contains("1") → isVisitor = true + │ + ├─ DB: image_rule_ref WHERE person_id = visitorId + │ → zone_id = 28F + │ + └─ 派梯到 28F +``` + +### 3.3 策略替代的精确代码位置 + +```java +// ImgPersonServiceImpl.detail() +// Line 620-626: 调用 elevator 获取被访人原始楼层 +AcsPassRuleImageForm acsPassRuleImageForm = new AcsPassRuleImageForm(); +acsPassRuleImageForm.setPersonId(param.getId()); +acsPassRuleImageForm.setIncludeOrganizations(result.getOrganizationIds()); +acsPassRuleImageForm.setIncludeLabels(result.getLabelIds()); +CloudwalkResult> images = + this.elevatorFeignClient.listByImageId(acsPassRuleImageForm); +// → 返回被访人所有楼层 (标签+组织+个人关联的 zone) + +// Line 632-641: 组装原始 floorList (全量) +for (AcsPassRuleImageResultDto dto : images.getData()) { + floorList.add(dto.getZoneId()); +} + +// ★ Line 643-648: 策略替代 — 就是这个位置 +Optional> replacementFloors = + this.tenantVisitorFloorPolicyService.replacementZoneIdsIfPolicyActive( + result.getOrganizationIds()); +if (replacementFloors.isPresent()) { + floorList = new ArrayList<>(replacementFloors.get()); // 完全替换! + zoneNames = buildCommaSeparatedFloorNames(businessId, floorList); +} + +// Line 650-651: 写入 PersonResult +result.setFloorList(floorList); +``` + +### 3.4 策略查询链 + +``` +TenantVisitorFloorPolicyService.replacementZoneIdsIfPolicyActive(orgIds) + │ + ├─ 遍历 orgIds, 对每个 orgId: + │ + └─ TenantVisitorFloorPolicyMapper.selectEnabledByOrgId(orgId) + │ + └─ SQL: + SELECT * FROM tenant_visitor_floor_policy + WHERE org_id = #{orgId} + AND enabled = 1 + AND (building_id IS NULL OR building_id = '') + LIMIT 1 + │ + └─ 返回第一行命中 → 解析 allow_zone_ids JSON → 返回 zone_id 列表 + + ↓ 如果任意 orgId 命中策略 → 返回 Optional.of(allow_zone_ids) + ↓ 如果所有 orgId 都未命中 → 返回 Optional.empty() + → ImgPersonServiceImpl.detail() 保留 listByImageId 原始结果 +``` + +### 3.5 listByPage (访客列表) 的并行路径 + +``` +listByPage(isVisitor=true) 的策略处理 (L326-333): + + P1: tenantVisitorFloorPolicyService.replacementZoneIdsIfPolicyActive(orgIds) + ├─ 命中 → 直接使用 allow_zone_ids 构建 floorInfoList + │ 设置 defaultChooseFloor = allow_zone_ids[0] + │ 设置 isAcrossDay = 0 + │ 跳过 P2 (包括跳过 40F/6F 硬编码块) + │ + └─ 未命中 → P2: listByImageId + XHW硬编码块 (L336-371) + ├─ orgIds.contains(xhwId) → 40F + └─ else → 6F +``` + +**40F/6F 硬编码与策略表的关系**: 策略命中时，硬编码逻辑被**完全跳过**。两者互斥，不冲突。 + +--- + +## 4. 方案A实现详解 + +### 4.1 实现步骤 + +| # | 步骤 | 操作 | 数据库 | +|---|------|------|--------| +| 1 | 确认 zone_id 列表 | `SELECT zone_id,zone_name,code FROM cw-elevator-app.code_elevator_area WHERE parent_id='605560539791228928' AND zone_id BETWEEN ? AND ?` | elevator | +| 2 | 更新策略 | `UPDATE component-org.tenant_visitor_floor_policy SET allow_zone_ids='["z1",...,"z20"]' WHERE id='gf_vstr_policy_guangfa_fund_001x'` | component-org | +| 3 | 更新种子SQL | 修改 `organization_tenant_visitor_floor_policy_init_tenants.sql` | 代码仓库 | +| 4 | 验证 | curl addVisitor + 检查 image_rule_ref 写入行数 | — | + +### 4.2 为什么只需要修改 component-organization 库 + +``` +V2 架构中的策略查询链: + + elevator-app + PersonRuleServiceImpl.addVisitor() + → personService.detail() [Feign调用] + → component-org: ImgPersonServiceImpl.detail() + → tenantVisitorFloorPolicyService [本地调用] + → TenantVisitorFloorPolicyMapper [本地调用] + → SQL: SELECT FROM tenant_visitor_floor_policy ← component-org 库 + + 电梯侧完全不参与策略查询。V1 时代的电梯侧 tenant_visitor_floor_policy 表 + 已成为死数据。确认: + - V2 电梯 Java 源码中无 TenantVisitorFloorPolicy* 引用 + - V2 电梯 MyBatis Mapper 中无该表查询 + - PersonRuleServiceImpl.addVisitor() 注释明确: "电梯侧不再读策略表" +``` + +### 4.3 数据一致性保证 + +| 保证机制 | 说明 | +|----------|------| +| 唯一约束 | `uk_org_building(org_id, building_id)` — 确保每个组织只有一条策略 | +| 版本追踪 | `policy_version` 字段自增 — 每次变更可追溯 | +| 回滚即时 | UPDATE enabled=0 或 UPDATE allow_zone_ids — 下个 detail() 调用即刻生效 | +| 幂等变更 | 使用固定 `id` 的 INSERT ON DUPLICATE KEY UPDATE — 重复执行安全 | + +--- + +## 5. 方案合理性论证 + +### 5.1 为什么是表驱动而非硬编码 + +| 论证维度 | 表驱动 (A) | 硬编码 (B/C) | +|----------|-----------|-------------| +| **当前代码就绪** | L643-648 已存在策略替代块 | 需要新增 @Value + if/else | +| **现有实例** | 广发 28F 已作为表行存在 (enabled=1) | 需要新增代码路径 | +| **扩展性** | INSERT 一行 = 新租户策略 | 每次 + @Value + 代码分支 | +| **运行时变更** | UPDATE SQL, 即时生效 | 改配置 + 重启服务 | +| **多 zone 支持** | JSON 数组原生支持 | 长字符串, 难以维护 | +| **组织级隔离** | `org_id` 精确定位 | if/else 链, 易出错 | +| **与 40F/6F 关系** | 互斥 (策略先于硬编码) | 冲突 (两套逻辑并排) | +| **数据库一致性** | 单库 (component-org) | 无数据库参与 | + +### 5.2 为什么不需要修改电梯侧 + +V2 架构将策略职责完全收敛到 component-organization: + +``` + V1 (旧) V2 (新) + ┌──────────┐ ┌──────────┐ + 策略存储 │ 双库维护 │ → │ 单库维护 │ + ├──────────┤ ├──────────┤ + 策略查询 │ elevator │ → │ org组件 │ + ├──────────┤ ├──────────┤ + addVisitor语义 │ 求交(∩) │ → │ 替代(=) │ + ├──────────┤ ├──────────┤ + listByPage语义 │ 无策略 │ → │ 策略覆盖 │ + └──────────┘ └──────────┘ +``` + +V2 的设计决策已在代码中体现 (L643-648 替代语义, addVisitor "此处不做 ∩" 注释)。方案A是对这个既有设计的延续，而非引入新的设计模式。 + +### 5.3 为什么 org_id 是合适的隔离键 + +``` +问题: BUSINESS_ID=2524639890ba4f2cba9ba1a4eeaa4015 被多个租户共享 + ├─ 广发基金 (28-38F) + ├─ 星河湾物业管理 (全楼) + ├─ 康怡健 + ├─ 大石 + └─ ... (642 个组织节点) + +如果按 business_id 隔离 → 一个策略影响所有租户 → 不可行 +如果按 org_id 隔离 → 每个组织独立策略 → 精确控制 +``` + +`tenant_visitor_floor_policy` 的 `uk_org_building(org_id, building_id)` 唯一约束正是为此设计。 + +### 5.4 为什么 20 层扩展只需 1 条 SQL + +``` +扩展前 (当前生产): + allow_zone_ids = '["605560545117995008"]' ← 1 个 zone (28F) + → detail() floorList = [28F] + → addVisitor UC-01 effective = [28F] + → image_rule_ref INSERT 1 行 + +扩展后: + allow_zone_ids = '["28F_id","29F_id",...,"47F_id"]' ← 20 个 zone + → detail() floorList = [28F,...,47F] + → addVisitor UC-01 effective = [28F,...,47F] + → image_rule_ref INSERT 20 行 (循环, 单次批量操作) + +引擎层面无任何变化: parseAllowZoneIds() 已支持任意数量, +replacementZoneIdsIfPolicyActive() 已遍历 orgIds 并返回列表, +detail() L647 已用 new ArrayList<>(replacementFloors.get()) 接收。 +``` + +### 5.5 当前架构的已知缺陷 (与方案A无关) + +| 缺陷 | 位置 | 影响 | 是否本方案引入 | +|------|------|------|-------------| +| addVisitor 无 floorId 校验 | PersonRuleServiceImpl L222 | 调用方可传任意 floorId | ❌ 已有 | +| UC-02 不做子集检查 | PersonRuleServiceImpl L187-191 | 绕过策略限制 | ❌ 已有 | +| getDefaultByZoneId 无 null 检查 | PersonRuleServiceImpl L222-227 | NPE → 76260530 | ❌ 已有 | +| 40F/6F 仍为硬编码 | ImgPersonServiceImpl L354-370 | 技术债 | ❌ 已有 | + +以上缺陷在方案A、B、C 中均存在，非本方案引入。 + +--- + +## 6. 附录: 关键表DDL + +### 6.1 tenant_visitor_floor_policy (策略表) + +```sql +CREATE TABLE `tenant_visitor_floor_policy` ( + `id` varchar(32) NOT NULL COMMENT '主键', + `business_id` varchar(64) DEFAULT NULL COMMENT 'DEPRECATED', + `org_id` varchar(32) DEFAULT NULL COMMENT '组织节点ID (隔离键)', + `policy_type` varchar(32) NOT NULL DEFAULT 'INTERSECT_ALLOWLIST', + `allow_zone_ids` text COMMENT 'JSON数组 zoneId列表', + `building_id` varchar(64) DEFAULT NULL, + `enabled` tinyint(1) NOT NULL DEFAULT '1', + `policy_version` bigint(20) NOT NULL DEFAULT '1', + `remark` varchar(256) DEFAULT NULL, + `created_at` bigint(20) DEFAULT NULL, + `updated_at` bigint(20) DEFAULT NULL, + PRIMARY KEY (`id`), + UNIQUE KEY `uk_org_building` (`org_id`,`building_id`), + KEY `idx_org_enabled` (`org_id`,`enabled`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; +``` + +### 6.2 image_rule_ref (通行规则 — 访客权限落地表) + +```sql +CREATE TABLE `image_rule_ref` ( + `id` varchar(32) NOT NULL, + `zone_id` varchar(64) NOT NULL COMMENT '楼层zone_id', + `zone_name` varchar(64) DEFAULT NULL, + `name` varchar(64) DEFAULT NULL COMMENT '规则名', + `person_id` varchar(64) DEFAULT NULL COMMENT '人员id', + `include_labels` varchar(64) DEFAULT NULL COMMENT '标签ID(单值)', + `include_organizations` varchar(64) DEFAULT NULL COMMENT '组织ID(单值)', + `is_default` tinyint(1) DEFAULT '0' COMMENT '默认规则标记', + `parent_rule` varchar(64) DEFAULT NULL COMMENT '归属规则id', + `person_delete` tinyint(1) DEFAULT '0', + PRIMARY KEY (`id`), + KEY `image_rule_ref_include_labels_IDX` (`include_labels`), + KEY `image_rule_ref_include_organizations_IDX` (`include_organizations`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; +``` + +### 6.3 cw_is_organization (组织架构) + +```sql +CREATE TABLE `cw_is_organization` ( + `ID` varchar(32) NOT NULL, + `NAME` varchar(60) DEFAULT NULL COMMENT '如"[28-38F]广发基金管理有限公司"', + `PARENT_ID` varchar(32) DEFAULT NULL COMMENT '树形结构', + `BUSINESS_ID` varchar(32) DEFAULT NULL, + `IS_DEL` smallint(2) DEFAULT NULL, + `IS_VALID` int(2) DEFAULT NULL COMMENT '0禁用 1启用', + PRIMARY KEY (`ID`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; +``` + +### 6.4 code_elevator_area (zone 编码) + +```sql +CREATE TABLE `code_elevator_area` ( + `zone_id` varchar(64) NOT NULL COMMENT '电梯编码', + `code` varchar(64) NOT NULL COMMENT '地区编码(如0x1C=28F)', + `parent_id` varchar(64) DEFAULT NULL COMMENT '楼栋id', + `is_first` tinyint(4) DEFAULT NULL, + PRIMARY KEY (`zone_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; +``` + +--- + +## 总结 + +广发基金访客默认 28F (及后续 20 层扩展) 的合理实现方案是: + +1. **利用已有的** `tenant_visitor_floor_policy` 表驱动架构 +2. **更新** `allow_zone_ids` 字段为目标 zone 列表 +3. **不改** 任何 Java 代码 (L643-648 策略替代块已就绪) +4. **只维护** component-organization 库 (V2 电梯侧不参与) +5. **org_id** 做隔离键 (多租户共享同一 business_id) + +架构评审关键点: 这不是引入新模式, 而是对 V2 既有表驱动设计的**延续使用**。 diff --git a/docs/superpowers/walkthroughs/2026-05-09-guangfa-28f-hardcoded-design.md b/docs/superpowers/walkthroughs/2026-05-09-guangfa-28f-hardcoded-design.md new file mode 100644 index 00000000..001b4f86 --- /dev/null +++ b/docs/superpowers/walkthroughs/2026-05-09-guangfa-28f-hardcoded-design.md @@ -0,0 +1,296 @@ +# 广发基金 28F 硬编码方案 — 组件/模块/位置细化设计 + +**日期**: 2026-05-09 +**分支**: `feature/guangfa-28f-hardcoded` +**状态**: 方案细化完成，待实施 + +--- + +## 1. 涉及组件与模块总览 + +``` +source/backend/ +├── ninca-common-component-organization/ ★ 唯一变更组件 +│ ├── cwos-component-organization-service/ ★ 代码变更 +│ │ └── src/main/java/cn/cloudwalk/service/organization/service/ +│ │ └── ImgPersonServiceImpl.java ★ 唯一变更 Java 文件 +│ │ +│ ├── cwos-component-organization-starter/ ★ 配置变更 +│ │ └── deploy/run-verify/ +│ │ └── application.properties ★ 唯一变更配置文件 +│ │ +│ └── (其余模块不变: data, interface, web) +│ +├── cw-elevator-application/ ☆ 仅增强日志 +│ └── cw-elevator-application-service/ +│ └── .../impl/PersonRuleServiceImpl.java ☆ +2 行日志 +│ +└── intelligent-cwoscomponent/ 不变 (仅 Feign 接口定义) +``` + +--- + +## 2. 变更点详细定位 + +### 2.1 模块: `cwos-component-organization-service` + +**文件**: `backend/ninca-common-component-organization/cwos-component-organization-service/src/main/java/cn/cloudwalk/service/organization/service/ImgPersonServiceImpl.java` + +**包**: `cn.cloudwalk.service.organization.service` +**类**: `ImgPersonServiceImpl` (1414 行) + +#### 位置 A — 依赖注入区 (第 157-158 行后，新增 2 行) + +**原代码**: +```java +157: @Value("${xhwSixFloorId}") +158: private String xhwSixFloorId; +159: +160: private static final String imageBase64 = +``` + +**改为**: +```java +157: @Value("${xhwSixFloorId}") +158: private String xhwSixFloorId; +159: +160: @Value("${gfOrgId}") +161: private String gfOrgId; +162: +163: @Value("${gfDefaultFloorId}") +164: private String gfDefaultFloorId; +165: +166: private static final String imageBase64 = +``` + +#### 位置 B — `listByPage()` 访客列表分支 (第 354-370 行，插入 else-if) + +**当前代码** (精确): +```java +354: if (imgStorePersonResult.getOrganizationIds().contains(this.xhwId)) { +355: imgStorePersonResult.setDefaultChooseFloor(this.xhwDefaultFloorId); +356: List floorInfoList = new ArrayList<>(); +357: AcsPassRuleImageResultDto resultDto = new AcsPassRuleImageResultDto(); +358: resultDto.setZoneId(this.xhwDefaultFloorId); +359: resultDto.setZoneName("40F"); +360: floorInfoList.add(resultDto); +361: imgStorePersonResult.setFloorInfoList(floorInfoList); +362: } else { +363: imgStorePersonResult.setDefaultChooseFloor(this.xhwSixFloorId); +364: List floorInfoList = new ArrayList<>(); +365: AcsPassRuleImageResultDto resultDto = new AcsPassRuleImageResultDto(); +366: resultDto.setZoneId(this.xhwSixFloorId); +367: resultDto.setZoneName("6F"); +368: floorInfoList.add(resultDto); +369: imgStorePersonResult.setFloorInfoList(floorInfoList); +370: } +``` + +**改为**: +```java +354: if (imgStorePersonResult.getOrganizationIds().contains(this.xhwId)) { +355: imgStorePersonResult.setDefaultChooseFloor(this.xhwDefaultFloorId); +356: List floorInfoList = new ArrayList<>(); +357: AcsPassRuleImageResultDto resultDto = new AcsPassRuleImageResultDto(); +358: resultDto.setZoneId(this.xhwDefaultFloorId); +359: resultDto.setZoneName("40F"); +360: floorInfoList.add(resultDto); +361: imgStorePersonResult.setFloorInfoList(floorInfoList); +362: } else if (imgStorePersonResult.getOrganizationIds().contains(this.gfOrgId)) { +363: imgStorePersonResult.setDefaultChooseFloor(this.gfDefaultFloorId); +364: List floorInfoList = new ArrayList<>(); +365: AcsPassRuleImageResultDto resultDto = new AcsPassRuleImageResultDto(); +366: resultDto.setZoneId(this.gfDefaultFloorId); +367: resultDto.setZoneName("28F"); +368: floorInfoList.add(resultDto); +369: imgStorePersonResult.setFloorInfoList(floorInfoList); +370: imgStorePersonResult.setIsAcrossDay(Integer.valueOf(0)); +371: this.logger.info("[GF-28F] listByPage MATCH orgId={} in orgIds={} → default 28F", +372: this.gfOrgId, imgStorePersonResult.getOrganizationIds()); +373: } else { +374: imgStorePersonResult.setDefaultChooseFloor(this.xhwSixFloorId); +375: List floorInfoList = new ArrayList<>(); +376: AcsPassRuleImageResultDto resultDto = new AcsPassRuleImageResultDto(); +377: resultDto.setZoneId(this.xhwSixFloorId); +378: resultDto.setZoneName("6F"); +379: floorInfoList.add(resultDto); +380: imgStorePersonResult.setFloorInfoList(floorInfoList); +381: } +``` + +**注意**: 行号偏移 (+5 行，因上方注入区新增)。实际编辑以内容匹配为准。 + +#### 位置 C — `detail()` 邀约+派梯核心路径 (第 643-651 行，在策略替代块后插入) + +**当前代码** (精确): +```java +643: Optional> replacementFloors = +644: this.tenantVisitorFloorPolicyService.replacementZoneIdsIfPolicyActive( +645: result.getOrganizationIds()); +646: if (replacementFloors.isPresent()) { +647: floorList = new ArrayList<>(replacementFloors.get()); +648: zoneNames = buildCommaSeparatedFloorNames(businessId, floorList); +649: } +650: result.setFloorNames(zoneNames); +651: result.setFloorList(floorList); +``` + +**改为**: +```java +643: Optional> replacementFloors = +644: this.tenantVisitorFloorPolicyService.replacementZoneIdsIfPolicyActive( +645: result.getOrganizationIds()); +646: if (replacementFloors.isPresent()) { +647: floorList = new ArrayList<>(replacementFloors.get()); +648: zoneNames = buildCommaSeparatedFloorNames(businessId, floorList); +649: } +650: // 广发基金: 邀约 + UC-01 派梯 floorList 限制为 28F +651: if (!CollectionUtils.isEmpty(result.getOrganizationIds()) +652: && result.getOrganizationIds().contains(this.gfOrgId)) { +653: List originalFloors = new ArrayList<>(floorList); +654: floorList = Collections.singletonList(this.gfDefaultFloorId); +655: zoneNames = "28F"; +656: this.logger.info("[GF-28F] detail MATCH orgId={} in orgIds={} → floor restricted: {}→[28F]", +657: this.gfOrgId, result.getOrganizationIds(), originalFloors); +658: } else { +659: this.logger.debug("[GF-28F] detail NO-MATCH orgId={} not in orgIds={}", +660: this.gfOrgId, result.getOrganizationIds()); +661: } +662: result.setFloorNames(zoneNames); +663: result.setFloorList(floorList); +``` + +**注意**: `Collections.singletonList` 需要 `import java.util.Collections;` — 检查是否已存在（当前代码 `listByPage` 中使用了 `Collections.singletonList`，import 应已存在）。 + +#### 位置 D — `detail()` 入口日志 (在第 600 行附近，`detail()` 方法体内) + +在 `detail()` 方法体的早期（如第 570-600 行区间，根据实际方法体定位），新增: + +```java +this.logger.info("[GF-DETAIL] entry personId={} businessId={} orgIds={}", + param.getId(), businessId, result.getOrganizationIds()); +``` + +#### 位置 E — `detail()` listByImageId 返回日志 (在第 630 行附近) + +在 `listByImageId` 调用成功后、循环组装 `floorList` 前: + +```java +this.logger.info("[GF-DETAIL] listByImageId returned {} zones: {}", + acsPassRuleImageResultDtoList.size(), + acsPassRuleImageResultDtoList.stream() + .map(AcsPassRuleImageResultDto::getZoneId).collect(Collectors.toList())); +``` + +--- + +### 2.2 模块: `cw-elevator-application-service` + +**文件**: `backend/cw-elevator-application/cw-elevator-application-service/src/main/java/cn/cloudwalk/elevator/person/impl/PersonRuleServiceImpl.java` + +**包**: `cn.cloudwalk.elevator.person.impl` +**类**: `PersonRuleServiceImpl` + +#### 位置 F — addVisitor() 日志增强 (第 187-194 行附近) + +**当前代码** (精确): +```java +187: boolean callerProvidedFloors = !CollectionUtils.isEmpty(param.getFloorIds()); +188: if (callerProvidedFloors) { +189: effective = param.getFloorIds(); +190: this.logger.info("UC-02：调用方显式楼层 effective={}", effective); +191: } else { +192: effective = personResult.getFloorList(); +193: if (CollectionUtils.isEmpty(effective)) { +194: this.logger.warn("UC-01：被访人 detail.floorList 为空 personId={}", param.getPersonId()); +``` + +**改为**: +```java +187: boolean callerProvidedFloors = !CollectionUtils.isEmpty(param.getFloorIds()); +188: if (callerProvidedFloors) { +189: effective = param.getFloorIds(); +190: this.logger.info("[GF-ADDV] UC-02 effective={}", effective); +191: } else { +192: effective = personResult.getFloorList(); +193: if (CollectionUtils.isEmpty(effective)) { +194: this.logger.warn("[GF-ADDV] UC-01 floorList empty personId={}", param.getPersonId()); +``` + +--- + +### 2.3 模块: `cwos-component-organization-starter` (配置) + +**文件**: `backend/ninca-common-component-organization/cwos-component-organization-starter/deploy/run-verify/application.properties` + +**位置**: 第 172 行后（`xhwSixFloorId` 之后），新增 2 行: + +```properties +# 第 170-172 行 (现有): +xhwId=21474e012cd14e26bc62771873b22562 +xhwDefaultFloorId=605560547135455232 +xhwSixFloorId=605560541473144832 + +# 第 173-174 行 (新增): +gfOrgId=488b8ad049bb43408a6fbcc50bcb89ac +gfDefaultFloorId=605560545117995008 +``` + +--- + +### 2.4 数据层: 禁用原表驱动策略 + +**数据库**: `component-organization` (组织库) +**表**: `tenant_visitor_floor_policy` + +```sql +UPDATE tenant_visitor_floor_policy +SET enabled = 0, + remark = CONCAT(remark, ' [DISABLED 2026-05-09: migrated to hardcoded 28F in ImgPersonServiceImpl]'), + updated_at = UNIX_TIMESTAMP(NOW()) * 1000 +WHERE id = 'gf_vstr_policy_guangfa_fund_001x' + AND enabled = 1; +``` + +**数据库**: `cw-elevator-application` (电梯库，如果存在同步表) +```sql +-- 仅当电梯库也有 tenant_visitor_floor_policy 表时执行 +UPDATE tenant_visitor_floor_policy +SET enabled = 0 +WHERE id = 'gf_vstr_policy_guangfa_fund_001x' + AND enabled = 1; +``` + +--- + +## 3. 不变更清单 + +| 组件 | 模块 | 文件 | 原因 | +|------|------|------|------| +| intelligent-cwoscomponent | interface | PersonService.java | Feign 接口定义，不变 | +| intelligent-cwoscomponent | rest | PersonFeignClient.java | HTTP 路径映射，不变 | +| ninca-common-component-organization | data | TenantVisitorFloorPolicyMapper.java | 仍服务物业策略，不删 | +| ninca-common-component-organization | service | TenantVisitorFloorPolicyService.java | 仍服务物业策略，不删 | +| ninca-common-component-organization | web | PersonController.java | REST 入口，不变 | +| ninca-common-component-organization | starter | bootstrap.properties | 启动配置，不变 | +| cw-elevator-application | web | AcsPersonController.java | REST 入口，不变 | +| cw-elevator-application | data | ImageRuleRefDao.java | DAO 层，不变 | +| scripts/test-env | config | component-org.properties | 测试模板（最小配置），不变 | +| ninca-common-component-organization | releases/ | 所有 `releases/` 下文件 | 历史发布快照，不变 | + +--- + +## 4. 汇总 + +| # | 组件 | Maven 模块 | 文件 | 变更类型 | 行数 | +|---|------|-----------|------|---------|------| +| A | component-org | cwos-component-organization-**service** | `ImgPersonServiceImpl.java` | 注入 `@Value` ×2 | +4 | +| B | component-org | cwos-component-organization-**service** | `ImgPersonServiceImpl.java` | `listByPage` else-if 分支 | +11 | +| C | component-org | cwos-component-organization-**service** | `ImgPersonServiceImpl.java` | `detail()` floorList 截断 | +13 | +| D | component-org | cwos-component-organization-**service** | `ImgPersonServiceImpl.java` | `detail()` 入口日志 | +2 | +| E | component-org | cwos-component-organization-**service** | `ImgPersonServiceImpl.java` | listByImageId 返回日志 | +3 | +| F | elevator-app | cw-elevator-application-**service** | `PersonRuleServiceImpl.java` | addVisitor 日志前缀 | ~0 (替换) | +| — | component-org | cwos-component-organization-**starter** | `application.properties` | 配置 ×2 | +2 | +| — | (数据库) | — | `tenant_visitor_floor_policy` | UPDATE enabled=0 | 1 行 | + +**总计: 2 个组件, 3 个模块, 3 个文件, ~35 行新增** diff --git a/docs/superpowers/walkthroughs/2026-05-09-guangfa-hardcoded-feasibility.md b/docs/superpowers/walkthroughs/2026-05-09-guangfa-hardcoded-feasibility.md new file mode 100644 index 00000000..dae57eba --- /dev/null +++ b/docs/superpowers/walkthroughs/2026-05-09-guangfa-hardcoded-feasibility.md @@ -0,0 +1,243 @@ +# 广发基金 28F 策略 — 参照 40F/6F 硬编码模式重实现可行性评估 + +**日期**: 2026-05-09 +**状态**: 评估完成 — **不可行 (推荐保留表驱动方案)** + +--- + +## 1. 两种模式的本质差异 + +### 1.1 40F/6F 硬编码模式 + +``` +┌─ @Value("${xhwId}") 注入配置 +├─ @Value("${xhwDefaultFloorId}") 注入配置 +├─ @Value("${xhwSixFloorId}") 注入配置 +│ +└─ ImgPersonServiceImpl#listByPage (仅此一处) + └─ if (orgIds.contains(xhwId)) + └─ defaultChooseFloor = xhwDefaultFloorId, zoneName = "40F" + else + └─ defaultChooseFloor = xhwSixFloorId, zoneName = "6F" +``` + +**核心特征**: 只影响 `listByPage` 访客列表展示层, **不涉及 `detail()` / `addVisitor()`**。 + +### 1.2 当前广发基金表驱动模式 + +``` +┌─ tenant_visitor_floor_policy 表 数据源 +├─ TenantVisitorFloorPolicyMapper DAO +├─ TenantVisitorFloorPolicyService 策略引擎 +│ +├─ ImgPersonServiceImpl#listByPage P1 分支 (列表展示) +└─ ImgPersonServiceImpl#detail() 核心路径 (UC-01 派梯) + └─ replacementZoneIdsIfPolicyActive → floorList 替代 + └─ PersonRuleServiceImpl#addVisitor() → 写入 image_rule_ref +``` + +**核心特征**: 同时影响 `listByPage` (列表) 和 `detail()` (派梯)。 + +### 1.3 关键差异对比 + +| 维度 | 40F/6F 硬编码 | 广发表驱动 | 差异 | +|------|-------------|-----------|------| +| 数据存储 | `application.properties` | `tenant_visitor_floor_policy` 表 | 文件 vs DB | +| 变更方式 | 改配置文件 + 重启 | UPDATE SQL (立即生效) | 重启 vs 实时 | +| 生效范围 | `listByPage` 仅列表 | `listByPage` + `detail()` | 单路径 vs 双路径 | +| 多 zone 支持 | 否 (单 zone) | 是 (JSON 数组) | 1 vs N | +| zone 名称 | 硬编码字符串 `"40F"` | 动态解析 (zone 表) | 硬编码 vs 动态 | +| 组织匹配 | contains(xhwId) | 按 org_id 精确匹配 | 包含 vs 精确 | +| 多组织策略 | 无概念 | 按 orgIds 顺序依次命中 | N/A | +| 启用/禁用 | 无开关 | `enabled` 字段 | 需删配置 vs 一行 SQL | +| 策略版本 | 无 | `policy_version` 自增 | 无追踪 vs 有追踪 | +| addVisitor 影响 | ❌ 无 (不走 detail) | ✅ 核心路径 | **致命差异** | + +--- + +## 2. 致命问题: `detail()` 路径缺失 + +### 2.1 `addVisitor()` 的楼层来源 + +```java +// PersonRuleServiceImpl#addVisitor() 第 187-194 行 +boolean callerProvidedFloors = !CollectionUtils.isEmpty(param.getFloorIds()); +if (callerProvidedFloors) { + effective = param.getFloorIds(); // UC-02 +} else { + effective = personResult.getFloorList(); // UC-01 ← 来自 detail() +} +``` + +`detail()` 返回的 `floorList` 是 UC-01 派梯的**唯一数据源**。 + +### 2.2 `detail()` 的当前楼层组装流程 + +```java +// ImgPersonServiceImpl#detail() 第 630-651 行 +// Step A: listByImageId 获取被访人全部楼层 +CloudwalkResult> images = elevatorFeignClient.listByImageId(...); + +// Step B: 遍历组装 floorList (原始全量) +for (AcsPassRuleImageResultDto dto : acsPassRuleImageResultDtoList) { + floorList.add(dto.getZoneId()); +} + +// Step C: ★ 策略替代 — 这是 40F/6F 模式完全没有的 +Optional> replacementFloors = + tenantVisitorFloorPolicyService.replacementZoneIdsIfPolicyActive(organizationIds); +if (replacementFloors.isPresent()) { + floorList = new ArrayList<>(replacementFloors.get()); // ← 替代 +} + +// Step D: 写入 PersonResult +result.setFloorList(floorList); +``` + +### 2.3 如果搬到 40F/6F 模式会发生什么 + +广发基金访客 `addVisitor` 的 UC-01 路径: + +``` +// 改造后 detail() 不再查策略表 +detail() → listByImageId() → floorList = [28F, 29F, ..., 38F] 全部楼层 + → 无策略替代 → floorList = 11 个 zone (被访人的全部楼层) + → addVisitor UC-01: effective = 11 个 zone + → 写入 11 行 image_rule_ref + → ❌ 访客获得了不应该有的 29-38F 权限 +``` + +**结论**: 40F/6F 模式的核心缺陷是**不接入 `detail()` 路径**。广发基金策略如果只套用 `listByPage` 硬编码, 将导致 `addVisitor` 派梯**完全绕过策略限制**, 访客获得被访人的全部楼层权限而非仅限 20 层。 + +--- + +## 3. 如果强行修补 (在 detail() 中也加硬编码) + +### 3.1 代码膨胀预估 + +```java +// 需要在 ImgPersonServiceImpl 中新增: +@Value("${gfOrgId}") private String gfOrgId; +@Value("${gfDefaultFloorList}") private String gfDefaultFloorList; // 逗号分隔 20 个 zoneId + +// detail() 中新增 (第 646 行附近): +if (result.getOrganizationIds().contains(this.gfOrgId)) { + floorList = Arrays.asList(gfDefaultFloorList.split(",")); + zoneNames = buildCommaSeparatedFloorNames(businessId, floorList); +} + +// listByPage 中新增 (第 354 行附近): +if (imgStorePersonResult.getOrganizationIds().contains(this.gfOrgId)) { + List floorIds = Arrays.asList(gfDefaultFloorList.split(",")); + buildFloorInfoListFromOrderedZoneIds(businessId, floorIds); + imgStorePersonResult.setDefaultChooseFloor(floorIds.get(0)); +} +``` + +### 3.2 问题清单 + +| # | 问题 | 严重度 | +|---|------|--------| +| 1 | 每新增一个租户需要加 2 个 `@Value` + 2 处 if/else | 🔴 | +| 2 | `application.properties` 中 `gfDefaultFloorList` 需要维护 20 个 zone_id (长字符串) | 🔴 | +| 3 | 20 个 zone_id 在配置文件中不可读，容易出错 | 🟡 | +| 4 | 修改策略需改配置文件 + 重启服务 | 🟡 | +| 5 | 无法动态启用/禁用 (需注释掉 @Value 或删配置) | 🟡 | +| 6 | 无策略版本追踪 | 🟢 | +| 7 | 与现有 `tenant_visitor_floor_policy` 表形成**双重逻辑源** | 🔴 | +| 8 | `detail()` 中硬编码逻辑与表驱动逻辑并存，维护混乱 | 🔴 | + +### 3.3 架构退化示意 + +``` +改造前 (表驱动, 单一逻辑源): + detail() ─→ TenantVisitorFloorPolicyService ─→ DB + listByPage ─→ TenantVisitorFloorPolicyService ─→ DB + +改造后 (混合模式, 双逻辑源): + detail() ─┬→ TenantVisitorFloorPolicyService ─→ DB (其他租户) + └→ if (contains(gfOrgId)) { split(config) } (广发特例) + listByPage ─┬→ TenantVisitorFloorPolicyService ─→ DB (其他租户) + ├→ if (contains(xhwId)) { "40F" } (物业) + ├→ else { "6F" } (非物业) + └→ if (contains(gfOrgId)) { split(config) } (广发特例 ← 新增) +``` + +**每增加一个租户策略, 代码分支呈线性增长**, 最终成为无法维护的 if/else 链。 + +--- + +## 4. 对比结论 + +| 评估维度 | 40F/6F 模式 | 表驱动模式 | 胜出 | +|----------|-----------|-----------|------| +| 代码简洁性 | 简单 (3 个 @Value + 1 个 if/else) | 中等 (5 个类) | 40F | +| 扩展性 (新增租户) | 差 (每次加代码) | 优 (INSERT 一行) | 表驱动 | +| 多 zone 支持 | 无 (单 zone) | 优 (JSON 数组) | 表驱动 | +| 变更生效 | 需重启 | 实时 | 表驱动 | +| 启用/禁用 | 改配置重启 | UPDATE SQL | 表驱动 | +| 版本追踪 | 无 | policy_version | 表驱动 | +| **addVisitor 覆盖** | **❌ 不覆盖** | **✅ 覆盖** | **表驱动** | +| 双重逻辑源风险 | 无 (仅 listByPage) | 无 (单一策略引擎) | 平 | +| 安全审计 | 无 | DB 行可审计 | 表驱动 | + +### 4.1 40F/6F 模式为什么可以存在 + +40F/6F 逻辑是**星河湾物业管理的历史遗留**, 且: +1. 其职责仅限于 `listByPage` 访客列表的**展示层默认值** +2. 不影响 `detail()` / `addVisitor()` 的派梯权限 +3. 是"全物业" vs "非物业"的二分类, 不需要细粒度组织匹配 +4. 只有 2 个 zone, 不需要多 zone 支持 + +因此 40F/6F 的正确理解是: **这不是一个"楼层策略", 而是列表展示的 fallback 默认值**。 + +### 4.2 广发基金不能套用的根本原因 + +广发基金 20 层是**真正的访问控制策略** — 它必须限制 `addVisitor` 写入的 `image_rule_ref` 行。40F/6F 模式完全不接入这条路径, 强行接入会导致代码膨胀和双重逻辑源。 + +--- + +## 5. 推荐方案 + +### 方案 A: 保持表驱动不改 (★★★★★ 强烈推荐) + +``` +当前架构已经正确: + tenant_visitor_floor_policy 表 ← 数据 + TenantVisitorFloorPolicyService ← 引擎 + ImgPersonServiceImpl#detail() ← 替代 floorList + ImgPersonServiceImpl#listByPage ← P1 展示 + PersonRuleServiceImpl#addVisitor ← UC-01 透传 +``` + +**唯一需要的变更**: UPDATE `allow_zone_ids` 从 1 个 zone 到 20 个 zone。 + +### 方案 B: 重构 40F/6F 到表驱动 (★★★ 锦上添花, 非必须) + +将 40F/6F 的硬编码逻辑也迁移到 `tenant_visitor_floor_policy` 表: + +```sql +INSERT INTO tenant_visitor_floor_policy (...) VALUES ( + 'pm_40f_hardcoded_migration', + '21474e012cd14e26bc62771873b22562', -- xhwId + '2524639890ba4f2cba9ba1a4eeaa4015', + 'INTERSECT_ALLOWLIST', + '["605560547135455232"]', -- 40F + NULL, 1, 1, + '物业公司：列表默认展示 40F (迁移自硬编码)' +); +``` + +然后在 `listByPage` 中删除 40F/6F 硬编码分支, 统一走策略引擎。此项非当前必须, 可作为技术债务清理。 + +--- + +## 6. 总结 + +| 问题 | 答案 | +|------|------| +| 能否参照 40F/6F 模式重实现广发 28F? | **技术上可以, 产出上不可行** | +| 根本原因 | 40F/6F 模式不接入 `detail()`, 导致 `addVisitor` 绕过策略 | +| 如果强行修补 | 双逻辑源、代码膨胀、维护灾难 | +| 正确做法 | 保持表驱动, 扩展 `allow_zone_ids` 即可 (零代码变更) | +| 额外收益 | 后续可将 40F/6F 也迁移到表驱动 (统一架构) | diff --git a/docs/superpowers/walkthroughs/2026-05-09-visitor-floor-policy-analysis.md b/docs/superpowers/walkthroughs/2026-05-09-visitor-floor-policy-analysis.md new file mode 100644 index 00000000..fc7260fc --- /dev/null +++ b/docs/superpowers/walkthroughs/2026-05-09-visitor-floor-policy-analysis.md @@ -0,0 +1,590 @@ +# 访客楼层策略完整走查 & 广发基金 20 层扩展评估 + +**日期**: 2026-05-09 +**状态**: 走查评估完成 +**作者**: OpenCode Agent + +--- + +## 目录 + +1. [架构总览](#1-架构总览) +2. [星河湾 40F/6F 硬编码逻辑走查](#2-星河湾-40f6f-硬编码逻辑走查) +3. [租户访客策略完整链路走查](#3-租户访客策略完整链路走查) +4. [广发基金当前 28F 策略分析](#4-广发基金当前-28f-策略分析) +5. [广发基金扩展至 20 层评估](#5-广发基金扩展至-20-层评估) +6. [变更点清单与风险矩阵](#6-变更点清单与风险矩阵) +7. [测试验证策略](#7-测试验证策略) +8. [附录: 关键文件索引](#8-附录-关键文件索引) + +--- + +## 1. 架构总览 + +### 1.1 服务拓扑 + +``` +访客登记页 (BFF/第三方) + │ + │ POST /elevator/person/add/visitor + ▼ +┌──────────────────────────────┐ +│ cw-elevator-application │ PersonRuleServiceImpl#addVisitor() +│ (电梯应用) │ ┌─ 阶段1: personService.detail() +│ │ ├─ 阶段2: UC-01/UC-02 分支 +│ │ ├─ 阶段3: 空集校验 +│ │ └─ 阶段4: 写入 image_rule_ref +├──────────────────────────────┤ +│ PersonService.detail() │ ──Feign──▶ +└──────────────────────────────┘ + │ + ▼ +┌──────────────────────────────┐ +│ ninca-common-component-org │ ImgPersonServiceImpl#detail() +│ (组织组件) │ ┌─ listByImageId() → 电梯 Feign +│ │ ├─ ★ 策略替代 (replacementZoneIds) +│ │ └─ 返回 PersonResult.floorList +│ │ +│ TenantVisitorFloorPolicyService +│ TenantVisitorFloorPolicyMapper +│ tenant_visitor_floor_policy 表 +└──────────────────────────────┘ +``` + +### 1.2 核心原则（已确立） + +| 原则 | 说明 | +|------|------| +| **策略只在组织组件** | `tenant_visitor_floor_policy` 表及策略逻辑仅在 `ninca-common-component-organization` | +| **电梯侧只透传** | `PersonRuleServiceImpl#addVisitor()` 不再读策略表，不做求交 | +| **替代（Replacement）语义** | 策略命中时 `allow_zone_ids` **整表替换** `floorList`，禁止与原始楼层求交 | +| **对外接口不变** | `PersonService.detail` → `PersonResult.floorList` 契约保持兼容 | +| **隔离键 = org_id** | 策略按组织节点 (`org_id`) 隔离，非 `business_id` | + +### 1.3 楼层数据流 + +``` +detail() 路径 (UC-01 权威来源): + ImgPersonServiceImpl#detail() + → elevatorFeignClient.listByImageId() # 获取被访人所有楼层 + → tenantVisitorFloorPolicyService.replacementZoneIds() # 策略替代 + → PersonResult.floorList = allow_zone_ids # 返回替代后的楼层 + +listByPage 路径 (列表展示): + ImgPersonServiceImpl#listByPage(isVisitor) + → P1: 策略命中 → 使用 allow_zone_ids (跳过 XHW 块) + → P2: 无策略 → listByImageId + XHW 40F/6F 硬编码逻辑 + +addVisitor() 路径 (电梯派梯): + PersonRuleServiceImpl#addVisitor() + → UC-01 (无 floorIds): effective = personResult.floorList + → UC-02 (有 floorIds): effective = param.floorIds + → 写入 image_rule_ref (每条 floorId 一行) +``` + +--- + +## 2. 星河湾 40F/6F 硬编码逻辑走查 + +### 2.1 配置来源 + +**文件**: `backend/ninca-common-component-organization/cwos-component-organization-starter/deploy/run-verify/application.properties` + +```properties +# 第 170-172 行 +xhwId=21474e012cd14e26bc62771873b22562 +xhwDefaultFloorId=605560547135455232 # = 40F +xhwSixFloorId=605560541473144832 # = 6F +``` + +### 2.2 Java 实现 + +**文件**: `backend/ninca-common-component-organization/cwos-component-organization-service/src/main/java/cn/cloudwalk/service/organization/service/ImgPersonServiceImpl.java` + +注入点 (第 154-158 行): +```java +@Value("${xhwId}") private String xhwId; +@Value("${xhwDefaultFloorId}") private String xhwDefaultFloorId; +@Value("${xhwSixFloorId}") private String xhwSixFloorId; +``` + +### 2.3 生效路径: `listByPage` 访客列表分支 + +**关键事实**: 40F/6F 硬编码逻辑 **只存在于 `listByPage`**，不存在于 `detail()`。这意味着: + +- **访客邀约页 / UC-01 派梯**: 走 `detail()` → 不会触发 40F/6F 逻辑 +- **访客列表页**: 走 `listByPage(isVisitor)` → 无策略命中时触发 40F/6F + +```java +// listByPage 第 326-370 行 +if (policyZones.isPresent()) { + // P1: 策略命中 → 使用 allow_zone_ids (跳过 XHW 块) + imgStorePersonResult.setFloorInfoList(policyFloorInfo); + imgStorePersonResult.setDefaultChooseFloor(policyZones.get().get(0)); +} else { + // P2: 无策略 → 走到 XHW 40F/6F + List orgFloorList = orgFloorMapper.listByOrgIds(organizationIds); + if (CollectionUtils.isEmpty(orgFloorList)) { + imgStorePersonResult.setIsAcrossDay(1); // 跨天 + } else { + if (imgStorePersonResult.getOrganizationIds().contains(this.xhwId)) { + // 物业公司 → 默认 40F + imgStorePersonResult.setDefaultChooseFloor(this.xhwDefaultFloorId); + // zoneName = "40F" + } else { + // 其他组织 → 默认 6F + imgStorePersonResult.setDefaultChooseFloor(this.xhwSixFloorId); + // zoneName = "6F" + } + } +} +``` + +### 2.4 40F/6F 判定逻辑总结 + +``` +是否命中租户策略？ + ├── YES → 策略 allow_zone_ids 替代 (跳过 XHW 块) + └── NO → 查询 OrgFloor 表 + ├── 无 OrgFloor 记录 → isAcrossDay=1 (跨天通行) + └── 有 OrgFloor 记录 + ├── 组织 ID 含 xhwId → 默认 40F + └── 其他组织 → 默认 6F +``` + +### 2.5 影响范围 + +| 接口 | 是否涉及 40F/6F | 说明 | +|------|----------------|------| +| `PersonService.detail` | ❌ 不涉及 | detail 只做 listByImageId + 策略替代 | +| `listByPage(isVisitor)` | ✅ 涉及 | 无策略命中时展示 40F/6F | +| `addVisitor` | ❌ 不涉及 | 只透传 floorList/floorIds | + +--- + +## 3. 租户访客策略完整链路走查 + +### 3.1 数据库表结构 + +**表**: `tenant_visitor_floor_policy` (组织库 `component-organization`) + +```sql +-- DDL 定义于: docs/sql/tenant_visitor_floor_policy_v2.sql +id VARCHAR(64) PRIMARY KEY +org_id VARCHAR(64) -- 组织节点 ID (隔离键) +business_id VARCHAR(64) -- 业务 ID +policy_type VARCHAR(64) -- 'INTERSECT_ALLOWLIST' +allow_zone_ids TEXT -- JSON 数组: ["zoneId1","zoneId2"] +building_id VARCHAR(64) -- NULL (全局) +enabled TINYINT(1) -- 0/1 +policy_version INT -- 版本号 (ON UPDATE 自增) +remark VARCHAR(512) +created_at BIGINT +updated_at BIGINT + +UNIQUE KEY: uk_org_building (org_id, building_id) +``` + +### 3.2 策略查询链路 + +``` +TenantVisitorFloorPolicyMapper.selectEnabledByOrgId(orgId) + ↓ @Select + SELECT * FROM tenant_visitor_floor_policy + WHERE org_id = #{orgId} + AND enabled = 1 + AND (building_id IS NULL OR building_id = '') + LIMIT 1 + +TenantVisitorFloorPolicyService.findEnabledPolicyByOrgId(orgId) + ↓ 返回 Optional + +TenantVisitorFloorPolicyService.replacementZoneIdsIfPolicyActive(orgIds) + ↓ 遍历 orgIds, 找到第一个命中策略的 + ↓ 解析 allow_zone_ids JSON → List + ↓ 返回 Optional> (非空列表) + +ImgPersonServiceImpl#detail() + ↓ replacementFloors.isPresent() ? + ↓ YES: floorList = replacementFloors.get() // 替代 + ↓ NO: 保留 listByImageId 原始结果 +``` + +### 3.3 多组织匹配优先级 + +`replacementZoneIdsIfPolicyActive(List orgIds)` 按 `orgIds` 顺序依次尝试: + +```java +// TenantVisitorFloorPolicyService.java 第 70-80 行 +for (String id : orgIds) { + Optional> zones = replacementZoneIdsIfPolicyActive(id); + if (zones.isPresent()) { + return zones; // 第一个命中的策略作为结果 + } +} +``` + +意味着: **人员所属的第一个有策略的组织决定最终楼层**。 + +### 3.4 电梯侧 addVisitor() 流程 + +```java +// PersonRuleServiceImpl.java 第 165-270 行 +addVisitor() { + // 阶段 1: 获取被访人 detail + PersonResult personResult = personService.detail(detailParam); + + // 阶段 2: 确定生效楼层 + if (callerProvidedFloors) { + effective = param.getFloorIds(); // UC-02: 调用方指定 + } else { + effective = personResult.getFloorList(); // UC-01: 使用 detail 返回 + } + + // 阶段 3: 空集校验 → 76260531 + if (CollectionUtils.isEmpty(effective)) { + return fail("76260531"); + } + + // 阶段 4: 写入 image_rule_ref + for (String floorId : effective) { + ImageRuleRefResultDto defaultRule = imageRuleRefDao.getDefaultByZoneId(floorId); + // 插入 image_rule_ref 行 + } +} +``` + +### 3.5 错误码 + +| 错误码 | 含义 | 触发点 | +|--------|------|--------| +| `76260530` | addVisitor 未捕获异常 | PersonRuleServiceImpl:263 | +| `76260531` | 无可用楼层 | PersonRuleServiceImpl:184, 197, 208 | +| `76260532` | 历史: 求交为空 (已废弃) | V1 解编译版:207 | + +--- + +## 4. 广发基金当前 28F 策略分析 + +### 4.1 当前策略配置 + +**组织库种子数据** (`docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql`): + +```sql +INSERT INTO tenant_visitor_floor_policy (...) VALUES ( + 'gf_vstr_policy_guangfa_fund_001x', -- id + '488b8ad049bb43408a6fbcc50bcb89ac', -- org_id (广发基金组织节点) + '2524639890ba4f2cba9ba1a4eeaa4015', -- business_id + 'INTERSECT_ALLOWLIST', -- policy_type + '["605560545117995008"]', -- allow_zone_ids: 仅 28F + NULL, 1, 1, -- building_id, enabled, version + '广发基金：访客楼层策略（组织库）；默认 28F。' +); +``` + +**允许楼层**: 1 个 zone — `605560545117995008` (28F) + +### 4.2 当前生效流程 + +``` +广发基金访客邀约: + 1. 前端/POST /elevator/person/add/visitor + 2. addVisitor() → personService.detail(personId) + 3. ImgPersonServiceImpl#detail() + → listByImageId() 返回被访人全部楼层 (可能多 zone) + → replacementZoneIds(["488b8ad..."]) 命中策略 + → floorList = ["605560545117995008"] # 仅 28F + 4. addVisitor() UC-01: effective = ["605560545117995008"] + 5. 写入 image_rule_ref (仅 28F 一条) +``` + +### 4.3 当前配置的局限 + +| 局限 | 描述 | +|------|------| +| 仅 1 层 | 广发基金租用 28-38F (11层)，但策略仅开放 28F 给访客 | +| 组织粒度单一 | `org_id` 绑定到 `[28-38F]广发基金管理有限公司` 一个节点 | +| 无部门区分 | 广发基金内部所有部门的访客均只能到达 28F | + +### 4.4 相关文件清单 + +| 文件 | 内容 | +|------|------| +| `docs/sql/tenant_visitor_floor_policy_init_guangfa_fund.sql` | 广发 28F 种子 (电梯库侧) | +| `docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql` | 广发 28F + 物业 28F+6F 种子 (组织库侧) | +| `docs/testing/广发基金访客被访楼层接口生产验证.md` | 广发生产验证文档 | +| `docs/testing/tenant-visitor-default-floor-isolation.md` | 租户隔离边界说明 | +| `scripts/test-env/stub-person-service.py` | 测试桩 (organizationNames: ["广发基金"]) | +| `backend/cw-elevator-application/tools/visitor_floor_verification/...` | 策略验证脚本 | +| `docs/testing/release-visitor-noauth-verify-v20260430/...` | 批量验证套件 | + +--- + +## 5. 广发基金扩展至 20 层评估 + +### 5.1 需求理解 + +将广发基金访客可到达楼层从 **1 层 (28F)** 扩展至 **20 层** (推测: 28-38F 共 11 层 + 扩展至 20 层范围 = 可能包含更广范围的楼层如 19-38F 或 28-47F 等)。 + +**待确认**: 具体哪 20 层的 zone_id 列表需与业务方确认。 + +### 5.2 变更方案 + +#### 方案 A: 纯数据变更 (推荐 ★★★★★) + +**操作**: 仅更新 `tenant_visitor_floor_policy` 表的 `allow_zone_ids` 字段, 从 `["605560545117995008"]` 扩展为 20 个 zone_id 的 JSON 数组。 + +**变更范围**: + +| 层级 | 变更内容 | +|------|---------| +| 数据库 | UPDATE `tenant_visitor_floor_policy` SET `allow_zone_ids` = '["zone1",...,"zone20"]' WHERE `id` = 'gf_vstr_policy_guangfa_fund_001x' | +| Java 代码 | **无需修改** — `parseAllowZoneIds()` 已支持任意数量 zone | +| SQL 种子 | 更新 `organization_tenant_visitor_floor_policy_init_tenants.sql` 和 `tenant_visitor_floor_policy_init_guangfa_fund.sql` | +| 接口契约 | **不变** — `PersonResult.floorList` 自动包含 20 个 zone | + +**优点**: +- 零代码变更 +- 现有策略引擎自动支持多 zone 替代 +- `detail()` 返回 `floorList` 自动包含 20 个 zone +- `addVisitor()` 透传, 为每个 zone 写一条 `image_rule_ref` +- 立即生效 (无需重启, 下次 `detail()` 调用即可) + +**风险**: 无 — `parseAllowZoneIds()` 和 `buildFloorInfoListFromOrderedZoneIds()` 都已正确处理多 zone 列表。 + +**验证**: +```sql +-- 执行变更后验证 +SELECT id, org_id, allow_zone_ids, enabled, policy_version +FROM tenant_visitor_floor_policy +WHERE id = 'gf_vstr_policy_guangfa_fund_001x'; + +-- 预期: allow_zone_ids 包含 20 个 zone_id 的 JSON 数组 +``` + +#### 方案 B: 多组织拆分策略 + +**思路**: 为广发基金的不同部门 / 组织节点配置不同的楼层范围。 + +**变更范围**: +- 新增多个 `tenant_visitor_floor_policy` 行, 每条绑定不同的 `org_id` +- 例如: `[28-30F]广发基金IT部` → allow 28-30F, `[31-33F]广发基金财务部` → allow 31-33F + +**适用场景**: 广发基金内部需要按部门细粒度控制访客楼层时启用。当前需求为整体 20 层开放, 暂不需要此方案。 + +#### 方案 C: 前端增强 (可选) + +**思路**: 前端访客邀约页根据 `floorList` (20 个 zone) 展示多选列表, 允许 BFF 调用方选择特定楼层子集传入 `addVisitor`。 + +**注意**: 当前 `addVisitor` 已支持 UC-02 调用方传 `floorIds` 子集, 无需后端变更。 + +### 5.3 推荐实施步骤 + +``` +Step 1 ─ 确认 20 层 zone_id 列表 + 查询 code_elevator_area 表获取对应 zone_id + SELECT zone_id, zone_name, code FROM code_elevator_area + WHERE building_id = '605560539791228928' -- floor.building.id + +Step 2 ─ 更新生产库策略数据 + UPDATE tenant_visitor_floor_policy + SET allow_zone_ids = '["zone1","zone2",...,"zone20"]', + policy_version = policy_version + 1, + remark = '广发基金：访客默认 20 层（扩展自 v1 28F 单层）', + updated_at = UNIX_TIMESTAMP(NOW()) * 1000 + WHERE id = 'gf_vstr_policy_guangfa_fund_001x' + +Step 3 ─ 更新组织库种子 SQL + 修改 organization_tenant_visitor_floor_policy_init_tenants.sql + +Step 4 ─ 验证 + curl POST /elevator/person/add/visitor (广发基金被访人) + 检查 PersonResult.floorList 包含 20 个 zone + 检查 image_rule_ref 写入 20 行 +``` + +### 5.4 性能影响 + +| 影响项 | 评估 | +|--------|------| +| `detail()` 响应 | 增加 19 个 zone_id, 响应体微增 (~1-2KB) | +| `addVisitor()` 写入 | 从 1 行 image_rule_ref 变为 20 行, 批量插入一次性完成 | +| `listByPage` 列表 | `buildFloorInfoListFromOrderedZoneIds()` 构建 20 条而不是 1 条 | +| zone 查询 | 结果列表变大但无额外 DB 查询 | + +**结论**: 性能影响可忽略。核心开销在 `addVisitor` 的 `image_rule_ref` 批量插入 (20 行), 仍为单次 DB 操作。 + +### 5.5 何时需要代码变更 + +当前架构中, **以下场景需要代码变更**: + +| 场景 | 是否需要代码变更 | +|------|-----------------| +| 修改 allow_zone_ids (数量变化) | ❌ 不需要 | +| 新增策略行 (新租户) | ❌ 不需要 | +| 修改策略类型 (policy_type) | ⚠️ 可能需要 — 当前仅实现 INTERSECT_ALLOWLIST | +| 新增策略字段 (如按 building_id 隔离) | ✅ 需要 — Mapper/TDO 需添加字段 | +| 前端默认选中逻辑需要映射 zone_name | ❌ 不需要 — `buildFloorInfoListFromOrderedZoneIds` 已处理 | + +--- + +## 6. 变更点清单与风险矩阵 + +### 6.1 变更范围最小化方案 + +| # | 步骤 | 类型 | 风险 | +|---|------|------|------| +| 1 | 确认 20 层 zone_id 列表 | 调研 | 🟢 | +| 2 | UPDATE tenant_visitor_floor_policy (组织库) | DML | 🟢 | +| 3 | UPDATE tenant_visitor_floor_policy (电梯库, 如存在) | DML | 🟢 | +| 4 | 更新种子 SQL 文件 | 文档 | 🟢 | +| 5 | 功能验证 (见 §7) | 测试 | 🟢 | + +### 6.2 关键检查点 + +| 检查点 | 预期结果 | +|--------|---------| +| 策略查询 | `selectEnabledByOrgId('488b8ad...')` 返回 `enabled=1` 行 | +| allow_zone_ids 解析 | `parseAllowZoneIds()` 返回 20 个 zone_id | +| detail() floorList | `PersonResult.floorList` 含 20 个 zone_id | +| addVisitor UC-01 | `effective` = 20 个 zone_id, 写入 20 行 image_rule_ref | +| addVisitor UC-02 | 调用方传 5 个 floorIds → 只写 5 行 (策略不覆盖 UC-02) | +| listByPage 访客列表 | 策略命中 → 展示 20 层, defaultChooseFloor = 第一个 zone | +| 其他租户不受影响 | 非广发基金组织 → detail() 走 listByImageId 原路径 | + +### 6.3 回滚方案 + +```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'; +``` + +回滚立即生效, 无需重启服务。 + +--- + +## 7. 测试验证策略 + +### 7.1 快速验证 (curl) + +```bash +# 广发基金被访人访客邀约 +curl -X POST http://127.0.0.1:18081/elevator/person/add/visitor \ + -H 'Content-Type: application/json' \ + -d '{ + "personId": "1072908835884208128", + "businessId": "2524639890ba4f2cba9ba1a4eeaa4015", + "visitorName": "test_20f", + "begVisitorTime": "2026-05-09 00:00:00", + "endVisitorTime": "2026-12-31 23:59:59" + }' + +# 预期: 返回成功, image_rule_ref 写入 20 行 +``` + +### 7.2 数据库验证 + +```sql +-- 1. 验证策略配置 +SELECT id, org_id, allow_zone_ids, enabled, policy_version +FROM tenant_visitor_floor_policy +WHERE id = 'gf_vstr_policy_guangfa_fund_001x'; + +-- 2. 验证写入的规则行数 +SELECT COUNT(*) AS rule_count +FROM image_rule_ref +WHERE person_id = ''; + +-- 预期: rule_count = 20 + +-- 3. 验证 zone 覆盖 +SELECT DISTINCT zone_id, zone_name +FROM image_rule_ref +WHERE person_id = '' +ORDER BY zone_name; +``` + +### 7.3 验证脚本 (现有工具) + +```bash +# 使用现有组织策略验证脚本 +cd backend/cw-elevator-application/tools/visitor_floor_verification +python3 scripts/verify_org_policy_fix.py + +# 期望: T1 (有策略→allow 替代) 返回 20 个 zone +# T2-T7 不受影响 +``` + +### 7.4 回归检查点 + +| 测试项 | 期望 | +|--------|------| +| 广发基金访客获 20 层权限 | ✅ | +| 物业公司访客仍为 28F+6F | ✅ | +| 其他租户访客不受影响 | ✅ | +| UC-02 调用方指定 3 层 → 只写 3 行 | ✅ | +| listByPage 访客列表策略命中展示 | ✅ | +| 策略禁用 (enabled=0) → 回退到原逻辑 | ✅ | + +--- + +## 8. 附录: 关键文件索引 + +### 8.1 Java 源码 + +| 文件 | 行数参考 | 功能 | +|------|---------|------| +| `backend/ninca-common-component-organization/.../policy/TenantVisitorFloorPolicyService.java` | 全文 103 行 | 策略服务: 查询、解析、替代 | +| `backend/ninca-common-component-organization/.../service/ImgPersonServiceImpl.java` | 154-158 (注入), 326-370 (listByPage), 643-648 (detail) | 策略应用点 | +| `backend/cw-elevator-application/.../impl/PersonRuleServiceImpl.java` | 165-270 (addVisitor) | 电梯侧透传 | +| `backend/ninca-common-component-organization/.../entity/TenantVisitorFloorPolicy.java` | 全文 | 策略实体 | +| `backend/ninca-common-component-organization/.../mapper/TenantVisitorFloorPolicyMapper.java` | 18-26 (查询) | 策略 DAO | + +### 8.2 SQL 脚本 + +| 文件 | 功能 | +|------|------| +| `docs/sql/tenant_visitor_floor_policy.sql` | 表 DDL | +| `docs/sql/tenant_visitor_floor_policy_v2.sql` | 增加 org_id 迁移 | +| `docs/sql/tenant_visitor_floor_policy_init_guangfa_fund.sql` | 广发基金种子 (电梯库) | +| `docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql` | 广发 + 物业种子 (组织库) | +| `docs/sql/tenant_visitor_floor_policy_migrate_org_id.sql` | org_id 数据迁移 | + +### 8.3 设计文档 + +| 文件 | 内容 | +|------|------| +| `docs/superpowers/specs/2026-05-06-tenant-visitor-policy-organization-implementation.md` | 策略迁入组织组件规范 (559 行) | +| `docs/superpowers/specs/2026-05-01-org-id-policy-fix-design.md` | org_id 粒度修复设计 | +| `docs/business/租户访客默认楼层技术产品方案.md` | 产品方案 (427 行) | +| `docs/testing/tenant-visitor-default-floor-isolation.md` | 租户隔离边界 (105 行) | +| `docs/testing/visitor-registration-floor-validation.md` | 测试方案 (151 行) | +| `docs/testing/广发基金访客被访楼层接口生产验证.md` | 广发生产验证 | + +### 8.4 测试与验证 + +| 文件 | 功能 | +|------|------| +| `scripts/test-env/verify-functional.sh` | 功能验证 (F3/F4 租户策略测试) | +| `scripts/test-env/stub-person-service.py` | 广发基金测试桩 | +| `backend/cw-elevator-application/tools/visitor_floor_verification/...` | 策略验证脚本集 | +| `docs/testing/release-visitor-noauth-verify-v20260430/...` | 批量验证套件 | + +--- + +## 总结 + +1. **40F/6F 逻辑**是星河湾物业管理的历史遗留硬编码, 仅影响 `listByPage` 访客列表展示, 不影响 `detail()` 和 `addVisitor()`。 + +2. **租户策略 (tenant_visitor_floor_policy)** 走 **替代** 语义: 命中后 `allow_zone_ids` 完全替代 `floorList`, 不做求交。 + +3. **广发基金当前仅开放 28F** (1 层), 通过 `tenant_visitor_floor_policy` 单行配置实现。 + +4. **扩展至 20 层是纯数据变更**: 只需 UPDATE `allow_zone_ids` 字段为 20 个 zone_id 的 JSON 数组。**零代码变更, 零接口变更, 零重启**。 + +5. **next step**: 确认 20 层 zone_id 列表 → UPDATE 生产库 → 更新种子 SQL → 功能验证。