starRiverProperty/docs/visitor-floor-policy-implementation-log.md

租户访客楼层策略 — 实施操作日志

项目: 星河湾星中星 (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 操作可回滚

恢复方式

# 单库恢复示例（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 执行记录:

-- 目标库: 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

变更内容:

-- 修改前
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

变更内容:

# 修改前
spring.messages.basename=i18n/messages_zh_CN

# 修改后（Spring 自动追加 locale）
spring.messages.basename=i18n/messages

Graceful Shutdown:

@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	广发基金层