From abc690af09892860c82648b2744417d647ab6c7b Mon Sep 17 00:00:00 2001 From: hpd840321 Date: Tue, 26 May 2026 09:32:55 +0800 Subject: [PATCH] docs: rewrite implementation log as deployment step document MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 原内容为开发阶段的git操作日志，现重写为面向运维人员的部署实施步骤文档 Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- ...visitor-floor-policy-implementation-log.md | 679 +++++++++--------- 1 file changed, 336 insertions(+), 343 deletions(-) diff --git a/docs/visitor-floor-policy-implementation-log.md b/docs/visitor-floor-policy-implementation-log.md index b3a80213..67057731 100644 --- a/docs/visitor-floor-policy-implementation-log.md +++ b/docs/visitor-floor-policy-implementation-log.md @@ -1,410 +1,403 @@ -# 租户访客楼层策略 — 实施操作日志 +# 租户访客楼层策略 — 部署实施步骤 > **项目**: 星河湾星中星 (starRiverProperty) > **功能**: 租户访客楼层策略（REPLACE_ALLOWLIST） -> **分支**: feature/guangfa-28f-hardcoded -> **实施人**: Huang Ping (hpd840321) -> **基线**: v2.0.17 +> **基线版本**: v2.0.17 +> **适用环境**: 生产环境（10.0.22.103） --- -## 操作日志总览 +## 一、部署概览 -| 阶段 | 时间段 | 操作次数 | 涉及文件 | -|------|--------|---------|---------| -| **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/ | +### 1.1 涉及组件 + +| 组件 | 服务名 | 端口 | 变更类型 | +|------|--------|------|---------| +| component-organization 服务 | ninca-common-component-organization | 17016 | JAR 升级 + DDL | +| 电梯应用 | cw-elevator-application | 18081 | JAR 升级（无配置变更） | + +### 1.2 涉及数据库 + +| 数据库 | IP | 变更类型 | 说明 | +|--------|----|---------|------| +| `component-organization` | 10.0.22.103 | DDL + DML | 新建策略表 + 种子数据 | +| `cw-elevator-application` | 10.0.22.103 | 无 | 仅代码查询，表已废弃 | + +### 1.3 发布包 + +| 发布包 | 构建脚本 | 输出路径 | +|--------|---------|---------| +| `ninca-common-component-organization-{ver}-xinghewan-{YYYYMMDD}.zip` | `scripts/build/release-component-organization.sh` | `backend/ninca-common-component-organization/releases/` | +| `cw-elevator-application-V{ver}.{YYYYMMDD}.zip` | `scripts/build/release-cw-elevator-application.sh` | `backend/cw-elevator-application/releases/` | --- -## 阶段0：生产环境全库备份（04-23 17:28） +## 二、前置准备 -### 操作 +### 2.1 数据库全量备份（必需） -在实施任何数据库变更前，对 **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 操作可回滚 | - -### 恢复方式 +在实施任何变更前，对生产数据库服务器（10.0.22.103）执行全库备份。 ```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 +# 备份全部数据库（预计 5-10 分钟，3.1 GB） +MYSQL_HOST=10.0.22.103 +MYSQL_USER=root +BACKUP_DIR=/data/backup/$(date +%Y%m%d_%H%M%S) +mkdir -p "$BACKUP_DIR" -# 全库恢复： -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" +# 获取所有数据库列表（排除系统库） +databases=$(mysql -h "$MYSQL_HOST" -u "$MYSQL_USER" -p \ + -e "SHOW DATABASES;" | grep -Ev "^(Database|information_schema|performance_schema|mysql|sys)$") + +# 逐个备份 +for db in $databases; do + echo "Backing up $db ..." + mysqldump -h "$MYSQL_HOST" -u "$MYSQL_USER" -p \ + --single-transaction --routines --triggers --events \ + "$db" | gzip > "$BACKUP_DIR/${db}_$(date +%Y%m%d_%H%M%S).sql.gz" done + +echo "Backup complete: $BACKUP_DIR" +ls -lh "$BACKUP_DIR" +``` + +**备份验证**： +```bash +# 检查备份文件完整性 +for f in "$BACKUP_DIR"/*.sql.gz; do + gzip -t "$f" || echo "CORRUPT: $f" +done + +# 检查 component-organization 备份大小（应有 200MB+） +ls -lh "$BACKUP_DIR"/component-organization*.sql.gz +``` + +### 2.2 发布包准备 + +```bash +# 构建 component-org 发布包 +cd /path/to/repo +bash scripts/build/release-component-organization.sh 2.9.5 + +# 构建电梯应用发布包 +bash scripts/build/release-cw-elevator-application.sh 2.0.17 + +# 产物确认 +ls -lh backend/ninca-common-component-organization/releases/*.zip +ls -lh backend/cw-elevator-application/releases/*.zip +``` + +### 2.3 当前状态快照 + +```bash +# 记录当前运行状态 +echo "=== 部署前状态快照 ===" > /tmp/pre-deploy-state.txt +date >> /tmp/pre-deploy-state.txt + +# component-org 进程 +ps aux | grep component-organization >> /tmp/pre-deploy-state.txt + +# 电梯应用进程 +ps aux | grep cw-elevator-application >> /tmp/pre-deploy-state.txt + +# 当前策略表状态（应不存在或为空） +mysql -h 10.0.22.103 -u root -p component-organization \ + -e "SELECT COUNT(*) AS policy_count FROM tenant_visitor_floor_policy;" 2>/dev/null \ + || echo "Table not exists (expected)" >> /tmp/pre-deploy-state.txt + +# 策略日志当前状态 +tail -50 logs/component-organization.info.log | grep POLICY \ + >> /tmp/pre-deploy-state.txt 2>/dev/null || true ``` --- -## 阶段Ⅰ：需求分析与设计（04-30 ~ 05-05） +## 三、部署步骤 -### 2026-04-30 策略重设计文档 +### Step 1：数据库 DDL — 建表 -**操作**: 撰写策略重设计文档，含序列图 -**涉及文件**: -- `docs/superpowers/specs/*-policy-redesign.md` -- `docs/superpowers/specs/*-initialization-flow-analysis.md` +在 **component-organization** 库创建策略表。 -**变更内容**: -- 确定了 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 不查询） +```bash +# 执行建表 DDL +mysql -h 10.0.22.103 -u root -p component-organization \ + < docs/sql/organization_tenant_visitor_floor_policy.sql ``` ---- - -## 阶段Ⅳ：策略数据归一化（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（种子） +SHOW TABLES LIKE 'tenant_visitor_floor_policy'; +SHOW CREATE TABLE tenant_visitor_floor_policy; +-- 预期： +-- policy_type DEFAULT 'REPLACE_ALLOWLIST'（非 INTERSECT_ALLOWLIST） +-- 唯一键 uk_org_building (org_id, building_id) +-- 索引 idx_org_enabled (org_id, enabled) ``` -**策略数据清单**: -| 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) | +### Step 2：数据库 DML — 种子数据 ---- +写入广发基金 28F + 物业管理 28F+6F 策略数据。 -## 阶段Ⅴ：DDL 修正（05-10 06:43） +```bash +# 执行种子数据（幂等，可重复执行） +mysql -h 10.0.22.103 -u root -p component-organization \ + < docs/sql/organization_tenant_visitor_floor_policy_init_tenants.sql +``` -### 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' +-- 验证数据完整性 +SELECT id, org_id, policy_type, allow_zone_ids, remark, enabled +FROM tenant_visitor_floor_policy +WHERE enabled = 1; --- 修改后 -policy_type VARCHAR(32) NOT NULL DEFAULT 'REPLACE_ALLOWLIST' +-- 预期返回 8 条记录： +-- 1 条广发基金 28F（gf_vstr_policy_guangfa_fund_001x） +-- 7 条物业管理 28F+6F（pm_6f_vstr_policy_001 ~ 007） + +-- 验证策略类型 +SELECT DISTINCT policy_type FROM tenant_visitor_floor_policy; +-- 预期：只有 REPLACE_ALLOWLIST +``` + +### Step 3：部署 component-org 服务 + +```bash +# 1. 传输发布包到目标服务器 +scp backend/ninca-common-component-organization/releases/\ +ninca-common-component-organization-2.9.5-xinghewan-*.zip \ + user@target-server:/opt/cw/component-organization/ + +# 2. 解压 +cd /opt/cw/component-organization +unzip ninca-common-component-organization-2.9.5-xinghewan-*.zip +cd ninca-common-component-organization-2.9.5-xinghewan-*/ + +# 3. 替换配置（如需要） +# 确认 bootstrap.properties / application.properties 与现网一致 + +# 4. 停止旧服务 +systemctl stop ninca-common-component-organization +# 或 kill 进程 +# ps aux | grep component-organization | grep -v grep | awk '{print $2}' | xargs kill + +# 5. 确认旧进程已退出 +ps aux | grep component-organization + +# 6. 启动新服务 +bash start.sh +# 或 systemctl start ninca-common-component-organization + +# 7. 检查启动日志 +tail -f logs/component-organization.info.log +# 预期： +# - 无 Bean 冲突异常 +# - 无 ResourceBundle WARN +# - 端口 17016 监听正常 +``` + +**启动验证**： +```bash +# 检查端口 +ss -tlnp | grep 17016 + +# 健康检查 +curl -s http://127.0.0.1:17016/health + +# 测试 detail 接口（含策略） +curl -X POST http://127.0.0.1:17016/component/person/detail \ + -d '{"personId":"1072908835884208128","businessId":"2524639890ba4f2cba9ba1a4eeaa4015"}' + +# 检查策略日志 +grep 'POLICY-HIT\|POLICY-RESULT' logs/component-organization.info.log +``` + +### Step 4：部署电梯应用（如需要） + +```bash +# 如果电梯应用 JAR 也有更新： +scp backend/cw-elevator-application/releases/\ +cw-elevator-application-V*.zip \ + user@target-server:/opt/cw/elevator/ + +cd /opt/cw/elevator +unzip cw-elevator-application-V*.zip +cd cw-elevator-application-V*/ + +# 停止旧服务 → 替换 JAR → 启动 +bash stop.sh +cp *.jar deploy/v2-maven/ +bash start.sh +``` + +**注意**：如果仅变更策略数据（SQL 种子），电梯应用**无需重启**。策略查询通过 Feign → component-org 实时获取。 + +### Step 5：日志配置确认 + +```bash +# 确认策略日志已正确输出 +grep -E 'POLICY-HIT|POLICY-MISS|POLICY-FALLBACK|POLICY-EMPTY' \ + logs/component-organization.info.log + +# 确认无 ResourceBundle WARN +grep 'ResourceBundle' logs/component-organization.info.log || echo "PASS: 无 ResourceBundle WARN" + +# 确认 [POLICY] 入口日志为 DEBUG（info.log 不应出现 POLICY entry） +grep '\[POLICY\] entry' logs/component-organization.info.log || echo "PASS: 无 POLICY entry INFO 日志" ``` --- -## 阶段Ⅵ：发布脚本编写（05-10 06:54） +## 四、功能验证 -### 2026-05-10 06:54 component-org 发布脚本 +### 4.1 策略命中验证 -**操作**: 新增 `release-component-organization.sh` -**涉及文件**: `scripts/build/release-component-organization.sh`（新增，139 行） +```bash +# 测试广发基金访客楼层 +curl -X POST http://127.0.0.1:17016/elevator/person/add/visitor \ + -d '{"personId":"1072908835884208128", + "businessId":"2524639890ba4f2cba9ba1a4eeaa4015", + "visitorName":"test_visitor_gf"}' +# 返回楼层应为 28F（zone_id: 605560545117995008） -**脚本流程**: -``` -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 版本号 +# 测试物业管理访客楼层 +curl -X POST http://127.0.0.1:17016/elevator/person/add/visitor \ + -d '{"personId":"another_person_id", + "businessId":"another_business_id", + "visitorName":"test_visitor_pm"}' +# 返回楼层应为 28F + 6F ``` -**发布包命名**: `ninca-common-component-organization-{ver}-xinghewan-{YYYYMMDD}` +### 4.2 无策略兜底验证 + +```bash +# 使用无策略配置的组织人员测试 +curl -X POST http://127.0.0.1:17016/component/person/detail \ + -d '{"personId":"person_id_without_policy", + "businessId":"business_id_without_policy"}' +# 返回 floorList 应保持 listByImageId 原始值（未被替换） +``` + +### 4.3 异常容错验证 + +```bash +# 模拟策略表不可用（临时重命名） +# mysql -h 10.0.22.103 -u root -p component-organization \ +# -e "RENAME TABLE tenant_visitor_floor_policy TO tenant_visitor_floor_policy_bak;" + +# 测试 detail 仍正常返回 +curl -X POST http://127.0.0.1:17016/component/person/detail \ + -d '{"personId":"1072908835884208128", + "businessId":"2524639890ba4f2cba9ba1a4eeaa4015"}' +# 预期：正常返回数据，floorList 为原始值 + +# 日志应有 POLICY-FALLBACK WARN + +# 恢复策略表 +# mysql -h 10.0.22.103 -u root -p component-organization \ +# -e "RENAME TABLE tenant_visitor_floor_policy_bak TO tenant_visitor_floor_policy;" +``` + +### 4.4 验收检查表 + +| # | 检查项 | 预期 | 结果 | +|---|--------|------|------| +| 1 | 策略表已创建 | `SHOW TABLES` 显示 `tenant_visitor_floor_policy` | □ 通过 □ 不通过 | +| 2 | 广发基金 28F 策略 | 查表有 `gf_vstr_policy_guangfa_fund_001x` | □ 通过 □ 不通过 | +| 3 | 物业 7 条 28F+6F 策略 | 查表有 `pm_6f_vstr_policy_001` ~ `007` | □ 通过 □ 不通过 | +| 4 | 策略类型全为 REPLACE_ALLOWLIST | `SELECT DISTINCT policy_type` = 1 种 | □ 通过 □ 不通过 | +| 5 | 广发访客 → 28F | 访客创建后楼层为 28F | □ 通过 □ 不通过 | +| 6 | 物业访客 → 28F+6F | 访客创建后楼层为 28F+6F | □ 通过 □ 不通过 | +| 7 | 无策略组织 → 原始楼层 | 不受影响 | □ 通过 □ 不通过 | +| 8 | 策略停用 (enabled=0) → 不生效 | 停用后楼层不被替换 | □ 通过 □ 不通过 | +| 9 | 策略查询异常 → 不阻断 | 表不可用时 detail 正常返回 | □ 通过 □ 不通过 | +| 10 | component-org 启动正常 | 端口 17016 监听，无 Bean 冲突 | □ 通过 □ 不通过 | +| 11 | POLICY-HIT 有日志 | `grep 'POLICY-HIT' info.log` 有输出 | □ 通过 □ 不通过 | +| 12 | 无 ResourceBundle WARN | `grep ResourceBundle` 无输出 | □ 通过 □ 不通过 | --- -## 阶段Ⅶ：日志系统增强（05-10 09:37 ~ 13:22） +## 五、回滚方案 -### 2026-05-10 09:37 策略追踪日志 +### 5.1 快速回滚（停用策略） -**操作**: 在 `TenantVisitorFloorPolicyService` 中添加策略追踪日志 -**涉及文件**: `source/backend/ninca-common-component-organization/.../TenantVisitorFloorPolicyService.java` +无需重启服务，仅需 SQL。 -**新增日志**: +```bash +# 停用所有策略（立即生效） +mysql -h 10.0.22.103 -u root -p component-organization \ + -e "UPDATE tenant_visitor_floor_policy SET enabled=0 WHERE enabled=1;" -| 日志标签 | 级别 | 触发条件 | 记录内容 | -|---------|------|---------|---------| -| 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 | +# 验证 +mysql -h 10.0.22.103 -u root -p component-organization \ + -e "SELECT COUNT(*) AS active_policies FROM tenant_visitor_floor_policy WHERE enabled=1;" +# 预期：0 -### 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 +# 恢复策略（重新启用） +mysql -h 10.0.22.103 -u root -p component-organization \ + -e "UPDATE tenant_visitor_floor_policy SET enabled=1;" ``` -**Graceful Shutdown**: -```java -@EventListener(ContextClosedEvent.class) -public void onShutdown() { - // 30s drain delay → 在途请求完成后销毁 Bean - Thread.sleep(30_000); -} +### 5.2 服务回滚（JAR 回退） + +```bash +# 1. 停止服务 +systemctl stop ninca-common-component-organization + +# 2. 备份新 JAR +mv ninca-common-component-organization-2.9.5.jar \ + ninca-common-component-organization-2.9.5.jar.rollback + +# 3. 恢复旧 JAR +cp /backup/ninca-common-component-organization-previous.jar \ + ninca-common-component-organization-2.9.5.jar + +# 4. 启动服务 +systemctl start ninca-common-component-organization + +# 5. 验证 +tail -f logs/component-organization.info.log ``` -### 2026-05-10 12:01 Logback 配置打包 +### 5.3 全量数据库恢复 -**操作**: 将 `recognition-logback.xml` 打包到 fat JAR classpath -**涉及文件**: `source/backend/ninca-common-component-organization/.../starter/pom.xml` +仅在 DDL 执行后出现数据损坏时使用。 -**变更**: 不再依赖外部 `--logging.config` 参数 +```bash +# 使用部署前备份的全量 SQL +RESTORE_FILE=/data/backup/YYYYMMDD_HHMMSS/component-organization_YYYYMMDD_HHMMSS.sql.gz -### 2026-05-10 12:32 Bean 冲突修复 +# 恢复 component-organization 库 +zcat "$RESTORE_FILE" | mysql -h 10.0.22.103 -u root -p component-organization -**操作**: 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 日志 +# 验证恢复后策略表应不存在（或为旧状态） +mysql -h 10.0.22.103 -u root -p component-organization \ + -e "SHOW TABLES LIKE 'tenant_visitor_floor_policy';" +``` --- -## 阶段Ⅷ：修复与优化（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 日志级别优化 - -详见阶段Ⅶ。 +1. **DDL 幂等性**：建表 SQL 使用 `CREATE TABLE IF NOT EXISTS`，种子 SQL 使用 `ON DUPLICATE KEY UPDATE`，重复执行不会报错。 +2. **电梯侧策略表已废弃**：`cw-elevator-application` 库的 `tenant_visitor_floor_policy` 表 V2 不再查询，仅供历史参考。 +3. **唯一策略维护点**：所有策略变更在 **component-organization** 库执行。 +4. **Graceful Shutdown**：component-org 服务配置了 30s 排空等待，停止服务时在途请求可正常完成。 +5. **JDK 版本**：所有服务必须使用 JDK 8。 +6. **日志级别**：[POLICY] 入口日志为 DEBUG 级别，正常运行时 `info.log` 不会出现 `POLICY entry`。 --- -## 阶段Ⅸ：上线日志分析与优化方案（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 | 广发基金层 | +| 建表 | `mysql -h 10.0.22.103 -u root -p component-organization < organization_tenant_visitor_floor_policy.sql` | +| 种子数据 | `mysql -h 10.0.22.103 -u root -p component-organization < organization_tenant_visitor_floor_policy_init_tenants.sql` | +| 查策略 | `SELECT id, org_id, policy_type, allow_zone_ids, remark FROM tenant_visitor_floor_policy WHERE enabled=1;` | +| 停用策略 | `UPDATE tenant_visitor_floor_policy SET enabled=0;` | +| 查策略命中 | `grep 'POLICY-HIT' logs/component-organization.info.log` | +| 查策略回退 | `grep 'POLICY-FALLBACK' logs/component-organization.info.log` | +| 服务状态 | `ss -tlnp \| grep 17016` | +| 健康检查 | `curl http://127.0.0.1:17016/health` | +| 全库备份 | `mysqldump --single-transaction ... \| gzip > backup.sql.gz` |