# 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`** 中构建时间为准。