docs: add visitor floor policy user guide and implementation log

- 功能清单与使用手册：23项功能清单、策略配置说明、部署运维、22项验收检查表 - 实施操作日志：9阶段操作流水、commit清单、关键文件索引、103服务器全库备份记录 Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-06-09 08:20:31 +08:00 · 2026-05-26 09:27:57 +08:00
parent f7c042ca8f
commit db2cb1966c
2 changed files with 766 additions and 0 deletions
@@ -0,0 +1,410 @@
+# 租户访客楼层策略 — 实施操作日志
+
+> **项目**: 星河湾星中星 (starRiverProperty)
+> **功能**: 租户访客楼层策略（REPLACE_ALLOWLIST）
+> **分支**: feature/guangfa-28f-hardcoded
+> **实施人**: Huang Ping (hpd840321)
+> **基线**: v2.0.17
+
+---
+
+## 操作日志总览
+
+| 阶段 | 时间段 | 操作次数 | 涉及文件 |
+|------|--------|---------|---------|
+| **0. 生产环境全库备份** | **04-23 17:28** | **1** | **data-backups/** |
+| Ⅰ. 需求分析与设计 | 04-30 ~ 05-05 | 4 | docs/ |
+| Ⅱ. 代码重组 | 05-07 ~ 05-09 | 15 | 全局目录 |
+| Ⅲ. 广发 28F 楼层策略设计 | 05-09 | 1 | docs/ |
+| Ⅳ. 策略数据归一化 | 05-10 01:14 | 1 | SQL + 发布脚本 |
+| Ⅴ. DDL 修正 | 05-10 06:43 | 1 | SQL DDL |
+| Ⅵ. 发布脚本 | 05-10 06:54 | 1 | scripts/build/ |
+| Ⅶ. 日志系统增强 | 05-10 09:37 ~ 13:22 | 5 | Java service |
+| Ⅷ. 启动与 Bean 修复 | 05-10 11:44 ~ 12:32 | 4 | Java config |
+| Ⅸ. 上线日志分析 | 05-10 15:32 | 1 | docs/ |
+
+---
+
+## 阶段0：生产环境全库备份（04-23 17:28）
+
+### 操作
+
+在实施任何数据库变更前，对 **103 生产服务器**（10.0.22.103）全部数据库执行完整 `mysqldump` 备份，共计 **11 个库 / 3.1 GB**。
+
+### 备份清单
+
+| # | 数据库文件 | 大小 | 说明 |
+|---|-----------|------|------|
+| 1 | `component-organization_2026_04_23_17_28_33.sql.gz` | 212 MB | **策略表目标库** — 组织服务库 |
+| 2 | `cwos_portal_2026_04_23_17_28_33.sql.gz` | 212 MB | 物业管理门户 |
+| 3 | `34_2026_04_23_17_28_33.sql.gz` | 2.5 GB | 电梯应用主库 |
+| 4 | `12_2026_04_23_17_28_33.sql.gz` | 158 MB | 电梯应用辅助库 |
+| 5 | `alarm_deploy_2026_04_23_17_28_33.sql.gz` | 15 MB | 报警服务 |
+| 6 | `ninca_common_2026_04_23_17_28_33.sql.gz` | 6.0 MB | 公共服务 |
+| 7 | `cwos_manager_2026_04_23_17_28_33.sql.gz` | 51 KB | CWOS 管理 |
+| 8 | `cloudwalk_device_thirdparty_2026_04_23_17_28_33.sql.gz` | 4.0 KB | 三方设备 |
+| 9 | `ods_2026_04_23_17_28_33.sql.gz` | 485 KB | ODS 数据 |
+| 10 | `g_2026_04_23_17_28_33.sql.gz` | 3.9 KB | 通用库 G |
+| 11 | `p_2026_04_23_17_28_33.sql.gz` | 1.1 KB | 通用库 P |
+
+### 备份信息
+
+| 项目 | 内容 |
+|------|------|
+| **服务器** | 10.0.22.103 |
+| **时间戳** | 2026-04-23 17:28:33 |
+| **工具** | `mysqldump` + `gzip` |
+| **总量** | 11 个数据库，合计 3.1 GB |
+| **备份存储** | `data-backups/`（仓库根目录） |
+| **备份目的** | 策略功能上线前全量快照，确保 DDL/DML 操作可回滚 |
+
+### 恢复方式
+
+```bash
+# 单库恢复示例（component-organization）：
+zcat data-backups/component-organization_2026_04_23_17_28_33.sql.gz \
+  | mysql -h 10.0.22.103 -u root -p component-organization
+
+# 全库恢复：
+cd data-backups
+for f in *.sql.gz; do
+  dbname=$(echo "$f" | sed 's/_2026.*//')
+  echo "Restoring $dbname from $f ..."
+  zcat "$f" | mysql -h 10.0.22.103 -u root -p "$dbname"
+done
+```
+
+---
+
+## 阶段Ⅰ：需求分析与设计（04-30 ~ 05-05）
+
+### 2026-04-30 策略重设计文档
+
+**操作**: 撰写策略重设计文档，含序列图
+**涉及文件**:
+- `docs/superpowers/specs/*-policy-redesign.md`
+- `docs/superpowers/specs/*-initialization-flow-analysis.md`
+
+**变更内容**:
+- 确定了 REPLACE_ALLOWLIST 替换语义（VS INTERSECT_ALLOWLIST 求交）
+- 分析了策略初始化流程
+
+### 2026-05-01 功能验证脚本
+
+**操作**: 新增 API 对拍 + 租户策略 + 集成测试脚本
+**涉及文件**: `scripts/test-env/verify-functional.sh`
+
+**变更内容**:
+- 增加策略相关测试用例
+- tenant policy + integration 验证
+
+### 2026-05-05 策略评估逻辑修正
+
+**操作**: 修复策略始终参与评估的 bug
+**涉及文件**: `backend/cw-elevator-application/.../PersonRuleServiceImpl.java`
+
+**变更内容**:
+- 策略无论调用方是否传入楼层均参与评估
+- 补充 `INTERSECT_ALLOWLIST` 求交逻辑
+
+---
+
+## 阶段Ⅱ：代码仓库重组（05-07 ~ 05-09）
+
+### 2026-05-07 目录规范化
+
+**操作**: 中文目录 → 英文目录重命名（15 次提交）
+
+| 操作 | 变更 |
+|------|------|
+| `星中心/` → `runtime/` | 服务目录命名规范化 |
+| `部署包/` → `packages/` | 部署包目录重命名 |
+| `data_backup/` → `data-backups/` | kebab-case 统一 |
+| `源码/` → `source/` | 源码目录重命名 |
+| 前端备份移至 `archive/` | 整理归档 |
+| nginx/artifacts 从 submodule 迁出 | 顶层目录化 |
+
+**影响**: 所有策略相关路径更新为新目录结构
+
+---
+
+## 阶段Ⅲ：广发 28F 访客楼层策略设计（05-09）
+
+### 2026-05-09 23:56 设计文档 + 数据库 ER 图
+
+**操作**: 新增广发 28F 访客楼层策略设计文档
+**涉及文件**:
+- `docs/superpowers/specs/*-guangfa-visitor-floor-design.md`
+- `docs/sql/tenant_visitor_floor_policy.sql`（标记 @deprecated）
+- `docs/sql/organization_tenant_visitor_floor_policy.sql`（新增组织侧 DDL）
+- `docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql`（种子数据）
+
+**变更内容**:
+1. 设计文档：表驱动方案 A 作为实现路径
+2. 电梯侧策略表标记为 @deprecated
+3. 组织侧 DDL 新建：`organization_tenant_visitor_floor_policy.sql`
+4. 组织侧种子数据：广发基金 28F + 物业管理 28F+6F
+5. 数据库 ER 图：14 个库、537 张表
+
+**决策记录**:
+```
+方案选择: 表驱动方案 A
+理由: 配置化策略管理，无需代码修改即可新增/修改策略
+V2 策略维护点: component-organization 库（唯一）
+电梯侧策略表: @deprecated（V2 不查询）
+```
+
+---
+
+## 阶段Ⅳ：策略数据归一化（05-10 01:14）
+
+### 2026-05-10 01:14 归一化 REPLACE_ALLOWLIST
+
+**操作**: 统一所有策略数据为 REPLACE_ALLOWLIST
+**涉及文件**:
+- `docs/sql/` 下所有策略 SQL
+- `scripts/build/release-component-organization.sh`
+- `scripts/build/release-cw-elevator-application.sh`
+
+**变更内容**:
+1. 种子 SQL 中 `policy_type` 全部改为 `REPLACE_ALLOWLIST`
+2. 备注格式统一：`组织名 | 访客默认NF`
+3. 发布脚本包含组织侧 DDL/seed + deprecation README
+4. 发布版本命名规范文档
+5. 电梯侧 `tenant_visitor_floor_policy` 禁用（V2 不查询）
+
+**SQL 执行记录**:
+```sql
+-- 目标库: component-organization
+-- 执行文件:
+--   1. organization_tenant_visitor_floor_policy.sql（建表）
+--   2. organization_tenant_visitor_floor_policy_init_tenants.sql（种子）
+```
+
+**策略数据清单**:
+| org_id | 策略类型 | allow_zone_ids | 组织名称 |
+|--------|---------|---------------|---------|
+| `488b8ad0...` | REPLACE_ALLOWLIST | `["605560545117995008"]` | [28-38F]广发基金管理有限公司 |
+| `64fdc8ea...` | REPLACE_ALLOWLIST | `["605560545117995008","605560541473144832"]` | 物业管理公司 (1/7) |
+| `8fc3f910...` | REPLACE_ALLOWLIST | `["605560545117995008","605560541473144832"]` | 物业管理公司 (2/7) |
+| `cc760fdf...` | REPLACE_ALLOWLIST | `["605560545117995008","605560541473144832"]` | 物业管理公司 (3/7) |
+| `f216235e...` | REPLACE_ALLOWLIST | `["605560545117995008","605560541473144832"]` | 物业管理公司 (4/7) |
+| `95818575...` | REPLACE_ALLOWLIST | `["605560545117995008","605560541473144832"]` | 物业管理公司 (5/7) |
+| `348328d7...` | REPLACE_ALLOWLIST | `["605560545117995008","605560541473144832"]` | 物业管理公司 (6/7) |
+| `dde6cc9a...` | REPLACE_ALLOWLIST | `["605560545117995008","605560541473144832"]` | 物业管理公司 (7/7) |
+
+---
+
+## 阶段Ⅴ：DDL 修正（05-10 06:43）
+
+### 2026-05-10 06:43 DDL 默认值修正
+
+**操作**: 修正 DDL 中 `policy_type` 默认值为 `REPLACE_ALLOWLIST`
+**涉及文件**:
+- `docs/sql/organization_tenant_visitor_floor_policy.sql`
+
+**变更内容**:
+```sql
+-- 修改前
+policy_type VARCHAR(32) NOT NULL DEFAULT 'INTERSECT_ALLOWLIST'
+
+-- 修改后
+policy_type VARCHAR(32) NOT NULL DEFAULT 'REPLACE_ALLOWLIST'
+```
+
+---
+
+## 阶段Ⅵ：发布脚本编写（05-10 06:54）
+
+### 2026-05-10 06:54 component-org 发布脚本
+
+**操作**: 新增 `release-component-organization.sh`
+**涉及文件**: `scripts/build/release-component-organization.sh`（新增，139 行）
+
+**脚本流程**:
+```
+1. Maven set version → package (fat JAR)
+2. Copy JAR → releases/ 输出目录
+3. Copy 配置文件 (bootstrap/application/recognition-logback)
+4. Copy DDL（组织侧：建表SQL + 种子SQL）
+5. 生成 DDL README（执行顺序说明）
+6. 生成 start.sh
+7. 生成 RELEASE.txt + BUILD_MANIFEST.txt
+8. Zip 压缩发布包
+9. 还原 Maven 版本号
+```
+
+**发布包命名**: `ninca-common-component-organization-{ver}-xinghewan-{YYYYMMDD}`
+
+---
+
+## 阶段Ⅶ：日志系统增强（05-10 09:37 ~ 13:22）
+
+### 2026-05-10 09:37 策略追踪日志
+
+**操作**: 在 `TenantVisitorFloorPolicyService` 中添加策略追踪日志
+**涉及文件**: `source/backend/ninca-common-component-organization/.../TenantVisitorFloorPolicyService.java`
+
+**新增日志**:
+
+| 日志标签 | 级别 | 触发条件 | 记录内容 |
+|---------|------|---------|---------|
+| POLICY-HIT | INFO | 策略命中 | orgId, policyId, allowZones |
+| POLICY-MISS | DEBUG | 未找到策略 | orgId |
+| POLICY-EMPTY | WARN | allow_zone_ids 解析为空 | policyId |
+| POLICY-FALLBACK | WARN | 查询异常 | orgId, exception |
+| POLICY-RESULT | INFO | batch 命中结果 | orgId, zones |
+
+### 2026-05-10 09:50 ImgPersonServiceImpl 全链路日志
+
+**操作**: 在 `ImgPersonServiceImpl` 中添加详细日志
+**涉及文件**: `source/backend/ninca-common-component-organization/.../ImgPersonServiceImpl.java`
+
+**新增日志**:
+
+| 日志标签 | 级别 | 触发条件 |
+|---------|------|---------|
+| DETAIL | INFO | detail() 入口/出口，含 personId |
+| DETAIL-POLICY | DEBUG | 策略替换前后 floorList 对比 |
+| LIST-PAGE-POLICY | DEBUG | listByPage() 策略命中 |
+| LIST-PAGE-XHW | DEBUG | 40F/6F hardcoded 分支 |
+| PAGE | INFO | page() 查询结果 |
+| ADDV-DETAIL | DEBUG | addVisitor detail floorList/orgIds |
+
+### 2026-05-10 11:44 消息源 & Graceful Shutdown
+
+**操作**: 修复 ResourceBundle WARN + 添加优雅关闭
+**涉及文件**:
+- `source/backend/ninca-common-component-organization/.../OrganizationServer.java`
+- `bootstrap.properties`
+
+**变更内容**:
+```properties
+# 修改前
+spring.messages.basename=i18n/messages_zh_CN
+
+# 修改后（Spring 自动追加 locale）
+spring.messages.basename=i18n/messages
+```
+
+**Graceful Shutdown**:
+```java
+@EventListener(ContextClosedEvent.class)
+public void onShutdown() {
+    // 30s drain delay → 在途请求完成后销毁 Bean
+    Thread.sleep(30_000);
+}
+```
+
+### 2026-05-10 12:01 Logback 配置打包
+
+**操作**: 将 `recognition-logback.xml` 打包到 fat JAR classpath
+**涉及文件**: `source/backend/ninca-common-component-organization/.../starter/pom.xml`
+
+**变更**: 不再依赖外部 `--logging.config` 参数
+
+### 2026-05-10 12:32 Bean 冲突修复
+
+**操作**: TypeFilter 排除 GroupPersonSyn* 重复 bean
+**涉及文件**: `source/backend/ninca-common-component-organization/.../starter/.../GroupPersonSynExcludeFilter.java`
+
+**变更**: 自定义 TypeFilter，排除 starter 模块外的 `cn.cloudwalk.service.organization.config.GroupPersonSyn*` 类
+
+### 2026-05-10 13:22 日志级别优化
+
+**操作**: 将 [POLICY] 入口日志从 INFO→DEBUG
+**涉及文件**: `TenantVisitorFloorPolicyService.java`
+
+**变更**: `log.info("[POLICY] entry orgIds={}")` → `log.debug("[POLICY] entry orgIds={}")` + 新增 `[DETAIL-POLICY-CHECK]` DEBUG 日志
+
+---
+
+## 阶段Ⅷ：修复与优化（05-10 11:44 ~ 12:32）
+
+### 2026-05-10 11:44 Graceful Shutdown
+
+详见阶段Ⅶ。
+
+### 2026-05-10 12:01 Logback 配置内嵌
+
+详见阶段Ⅶ。
+
+### 2026-05-10 12:32 Bean 冲突修复
+
+详见阶段Ⅶ。
+
+### 2026-05-10 13:22 日志级别优化
+
+详见阶段Ⅶ。
+
+---
+
+## 阶段Ⅸ：上线日志分析与优化方案（05-10 15:32）
+
+### 2026-05-10 15:32 日志分析报告
+
+**操作**: 分析 component-org 上线 37 分钟日志
+**涉及文件**: `docs/superpowers/specs/2026-05-10-component-org-log-analysis.md`
+
+**分析结果**:
+
+| 指标 | 数据 |
+|------|------|
+| 日志总量 | 106,372 行 / 26MB |
+| 有效 TraceId | 9,848 个 |
+| 设备同步占比 | 84.2%（89,531 行） |
+| WARN 占比 | 29.9%（31,800 行）— 主要是设备同步失败 |
+| 用户业务调用 | 0.06%（64 行） |
+| 策略命中 | 12 行 |
+| 策略调用频率 | ~1 次/分钟 |
+| 单次策略查询耗时 | < 5ms |
+
+**策略触发优化方案**: 详见 `docs/superpowers/specs/2026-05-10-floor-policy-trigger-optimization.md`
+
+---
+
+## 附录
+
+### A. Commit 清单
+
+| 时间 | Hash | 类型 | 描述 |
+|------|------|------|------|
+| 05-09 23:56 | `42c4a9fd` | docs | 广发 28F 设计文档 + ER 图 |
+| 05-10 01:14 | `03752480` | feat | 策略归一化 REPLACE_ALLOWLIST |
+| 05-10 06:43 | `73dc34ec` | fix | DDL 默认值修正 |
+| 05-10 06:54 | `368d14de` | feat | component-org 发布脚本 |
+| 05-10 09:37 | `d8bcc145` | feat | 策略追踪日志 |
+| 05-10 09:50 | `f350f318` | feat | ImgPersonService 全链路日志 |
+| 05-10 11:44 | `3f1a23a1` | fix | 消息源 + Graceful Shutdown |
+| 05-10 12:01 | `c7d4ac4a` | fix | Logback 内嵌 |
+| 05-10 12:32 | `09b1bbe5` | fix | Bean 冲突修复 |
+| 05-10 13:22 | `203005aa` | refactor | 日志级别优化 |
+| 05-10 15:32 | `f7c042ca` | docs | 上线日志分析 |
+
+### B. 关键文件索引
+
+| 文件 | 说明 |
+|------|------|
+| `source/docs/sql/organization_tenant_visitor_floor_policy.sql` | 组织库建表 DDL |
+| `source/docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql` | 种子数据（广发+物业） |
+| `source/scripts/build/release-component-organization.sh` | component-org 发布脚本 |
+| `source/scripts/build/release-cw-elevator-application.sh` | 电梯应用发布脚本 |
+| `source/backend/ninca-common-component-organization/.../policy/TenantVisitorFloorPolicyService.java` | 策略服务核心逻辑 |
+| `source/backend/ninca-common-component-organization/.../service/ImgPersonServiceImpl.java` | detail/listByPage 策略调用入口 |
+| `docs/superpowers/specs/2026-05-10-component-org-log-analysis.md` | 上线日志分析报告 |
+| `docs/superpowers/specs/2026-05-10-floor-policy-trigger-optimization.md` | 策略触发优化方案 |
+
+### C. 数据字典
+
+| 表 | 库 | 用途 |
+|----|----|------|
+| `tenant_visitor_floor_policy` | `component-organization` | **V2 唯一策略表**（活跃） |
+| `tenant_visitor_floor_policy` | `cw-elevator-application` | ⛔ **废弃**（仅历史参考） |
+
+### D. 楼层编码
+
+| zone_id | 楼层 | 用途 |
+|---------|------|------|
+| `605560540432957440` | 1F | 首层 |
+| `605560541473144832` | 6F | 物业管理层 |
+| `605560545117995008` | 28F | 广发基金层 |