starRiverProperty/maven-cw-elevator-application/releases/v2.0.3/版本升级说明书.md

cw-elevator-application v2.0.0 版本升级说明书

适用范围：本说明仅描述 v2.0.0 中与 租户访客固定访问楼层（租户级允许区域与组织 floorList 求交）相关的升级内容，不含其它性能优化或通用发布项。

应用制品：cw-elevator-application-2.0.0.jar（Spring Boot 可执行 fat JAR）。

---

1. 功能概述

在 访客派梯 接口 add/visitor（实现类 PersonRuleServiceImpl#addVisitor）中，当调用方 未传入非空 floorIds（业务流程 UC-01：按被访人组织侧楼层推导）时：

1. 服务仍先通过 person/detail 取得被访人 floorList（与升级前一致）。
2. 新增：若数据库中存在启用的租户策略行，且 allow_zone_ids 解析为非空 JSON 数组，则最终生效楼层为
   effectiveFloors = floorList ∩ allow_zone_ids（顺序保持 floorList 原有顺序）。
3. 若交集 为空，接口返回失败码 76260532（不允许静默放宽到其它楼层）。
4. 若无策略表、无启用行、allow_zone_ids 为空或 JSON 无效：行为与升级前一致，使用 floorList 全集。

当调用方 已传入非空 floorIds（UC-02，第三方显式指定楼层）时：不读取策略表，不对入参求交，与升级前一致。

产品表述：「固定访问楼层」在本阶段由租户管理员通过 allow_zone_ids 声明允许开放给访客派梯的区域（zoneId）集合；在 UC-01 路径下与组织返回的 floorList 取交集，从而将访客权限收敛到既有「被访人可去楼层」与「租户允许楼层」的双重约束内。

---

2. 涉及的数据库变更

2.1 变更类型

类型	对象
新增表	tenant_visitor_floor_policy

执行库：与电梯应用 同一数据源（MySQL/InnoDB，与现有派梯业务库一致）。

2.2 表用途（摘要）

字段	含义
business_id	租户/机构 ID
policy_type	本阶段固定 INTERSECT_ALLOWLIST
allow_zone_ids	TEXT，存 JSON 数组字符串，元素为允许访客派梯的 zoneId
building_id	租户级默认策略填 NULL（预留楼栋维）
enabled	1 启用 / 0 停用
policy_version	配置版本号（审计）

唯一约束 uk_biz_building (business_id, building_id)：同一租户、租户级策略（building_id 为空）建议仅维护一行，避免多行时查询仅命中「最新一条」与运维预期不符。

2.3 DDL 脚本位置

用途	仓库内路径
权威 DDL	docs/sql/tenant_visitor_floor_policy.sql

发布包内副本：随 v2.0.0 发布目录一并下发，路径为 ddl/tenant_visitor_floor_policy.sql（与根目录 JAR 同级下的 ddl 子目录）。

脚本内容为 CREATE TABLE IF NOT EXISTS，在未建表环境可重复执行；不含业务数据 INSERT，上线需按租户配置自行 INSERT 策略行。

2.4 上线执行顺序（建议）

1. 备份当前电梯应用库（至少包含待变更库的全库或相关表备份策略）。
2. 在目标库执行 ddl/tenant_visitor_floor_policy.sql（或直接使用仓库 docs/sql 下同源文件）。
3. 对需启用策略的租户 INSERT 一行（示例字段：business_id、policy_type='INTERSECT_ALLOWLIST'、allow_zone_ids 为合法 JSON 数组、enabled=1、building_id 为 NULL）。
4. 部署 cw-elevator-application-2.0.0.jar 并滚动重启应用。
5. 按 §4 做 UC-01 / UC-02 验收。

2.5 回滚说明

• 仅回滚应用：还原旧版本 JAR 后，若库中已存在策略行且仍为 enabled=1，旧版本应用通常不读取该表，行为与历史一致；表结构可保留。
• 回滚数据库：若需删除表（谨慎），在确认无其它依赖后执行 DROP TABLE tenant_visitor_floor_policy；请在变更窗口与 DBA 确认。

---

3. 行为与错误码（验收）

场景	floorIds	策略库	期望
UC-01 基线	空/未传	无启用行或 allow 空/无效	使用组织 floorList 全集（与升级前一致）
UC-01 + 固定楼层	空/未传	有启用行且 allow 非空	floorList ∩ allow（保序）
无交集	空/未传	allow 与 floorList 无交集	76260532
被访人无楼层	空/未传	任意	76260531
UC-02	非空	任意	不读策略表，按请求楼层处理

---

4. 发布包目录结构（v2.0.0）

执行仓库根目录 ./scripts/release-cw-elevator-application.sh 后，输出目录为：

maven-cw-elevator-application/releases/v2.0.0/

文件/目录	说明
cw-elevator-application-2.0.0.jar	可执行应用
ddl/tenant_visitor_floor_policy.sql	与本功能相关的 唯一 DDL（与 docs/sql 同源）
版本升级说明书.md	本文件副本（便于随包交付）
BUILD_MANIFEST.txt	构建时间、JDK、git 修订号

---

5. 参考文档（仓库内）

文档	路径
数据库阶段变更记录	docs/business/租户访客默认楼层-数据库阶段变更记录.md
数据库配置阶段技术设计	docs/business/租户访客默认楼层-数据库配置阶段技术设计.md
技术产品方案	docs/business/租户访客默认楼层技术产品方案.md
访客注册与派梯楼层走查	docs/business/访客注册与派梯楼层业务流程走查.md

---

文档版本：与制品 cw-elevator-application-2.0.0 对齐；若仅升级文档而不改代码，请以 BUILD_MANIFEST.txt 中构建时间为准。