mirror of
https://github.com/hpd840321/starRiverProperty.git
synced 2026-06-09 08:20:31 +08:00
release(cw-elevator): v2.0.0 发布说明、升级文档与发布脚本
- 增加电梯应用 v2.0.0 技术/甲方/升级计划说明 - 增加 release-cw-elevator-application.sh 与 releases 忽略 JAR - 发布包目录含 ddl 与文档副本（JAR 由本地构建，不提交） Made-with: Cursor Former-commit-id: 3939231809c424041419f38be69db99edaef55f4
This commit is contained in:
反编译工作区
@@ -0,0 +1,9 @@
|
||||
artifact=cw-elevator-application-2.0.0.jar
|
||||
directory=/media/zebra/9e8fa357-7db6-4d70-88ed-d5de5a059a663/星河湾星中星/反编译/maven-cw-elevator-application/releases/v2.0.0
|
||||
built_at=2026-04-27T14:05:31+08:00
|
||||
java_home=/usr/lib/jvm/java-8-openjdk-amd64
|
||||
java_version_line=openjdk version "1.8.0_482"
|
||||
java_version_line=OpenJDK Runtime Environment (build 1.8.0_482-8u482-ga~us1-0ubuntu1~22.04-b08)
|
||||
java_version_line=OpenJDK 64-Bit Server VM (build 25.482-b08, mixed mode)
|
||||
git_rev=571c9a99ee26d90505e550c287eb8ad8d743ff8d
|
||||
git_branch=release/cw-elevator-v1-lib-min-risk
|
||||
@@ -0,0 +1,27 @@
|
||||
-- 租户访客默认楼层策略（电梯应用库）
|
||||
-- 设计说明：docs/business/租户访客默认楼层-数据库配置阶段技术设计.md
|
||||
|
||||
CREATE TABLE IF NOT EXISTS tenant_visitor_floor_policy (
|
||||
id VARCHAR(32) NOT NULL COMMENT '主键',
|
||||
business_id VARCHAR(64) NOT NULL COMMENT '机构/租户 ID',
|
||||
policy_type VARCHAR(32) NOT NULL DEFAULT 'INTERSECT_ALLOWLIST' COMMENT '策略类型',
|
||||
allow_zone_ids TEXT NULL COMMENT 'JSON 数组，zoneId 列表',
|
||||
building_id VARCHAR(64) NULL COMMENT '预留：楼栋维度；租户默认填 NULL',
|
||||
enabled TINYINT(1) NOT NULL DEFAULT 1 COMMENT '1 启用 0 停用',
|
||||
policy_version BIGINT NOT NULL DEFAULT 1 COMMENT '配置版本号',
|
||||
remark VARCHAR(256) NULL,
|
||||
created_by VARCHAR(64) NULL,
|
||||
created_at BIGINT NULL,
|
||||
updated_by VARCHAR(64) NULL,
|
||||
updated_at BIGINT NULL,
|
||||
PRIMARY KEY (id),
|
||||
UNIQUE KEY uk_biz_building (business_id, building_id),
|
||||
KEY idx_business_enabled (business_id, enabled)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='租户访客默认楼层策略（与组织 floorList 求交）';
|
||||
|
||||
-- 示例（实施时替换占位符后执行）
|
||||
-- INSERT INTO tenant_visitor_floor_policy
|
||||
-- (id, business_id, policy_type, allow_zone_ids, building_id, enabled, policy_version, remark, created_at, updated_at)
|
||||
-- VALUES
|
||||
-- (REPLACE(UUID(),'-',''), 'REPLACE_WITH_BUSINESS_ID', 'INTERSECT_ALLOWLIST',
|
||||
-- '["REPLACE_ZONE_A","REPLACE_ZONE_B"]', NULL, 1, 1, '实施录入', UNIX_TIMESTAMP(NOW())*1000, UNIX_TIMESTAMP(NOW())*1000);
|
||||
@@ -0,0 +1,106 @@
|
||||
# cw-elevator-application v2.0.0 升级计划
|
||||
|
||||
**项目名称**（可填）：智慧电梯 / 访客派梯系统升级
|
||||
**版本**：v2.0.0
|
||||
**计划性质**：执行级排期草案，**具体日期、起止时刻以与甲方书面/邮件确认为准**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 升级目标
|
||||
|
||||
完成电梯派梯应用 **v2.0.0** 上线，启用**租户访客固定访问楼层**能力所需的应用与数据库对象；按业务需要为指定租户配置策略并完成验收。
|
||||
|
||||
---
|
||||
|
||||
## 2. 计划时间窗口（夜间 · 暂定周二、周三）
|
||||
|
||||
| 窗口 | 意向安排 | 建议内容（可合并或调整） |
|
||||
|------|-----------|----------------------------|
|
||||
| **第一次：周二晚间** | 夜间低峰段，具体 **HH:MM–HH:MM** 待定 | 环境检查、数据库备份、执行 **DDL**（新建策略表）、（可选）预发布验证、必要时准备回滚包与检查单 |
|
||||
| **第二次：周三晚间** | 夜间低峰段，具体 **HH:MM–HH:MM** 待定 | 部署新版本 **JAR**、滚动/重启应用、按需 **INSERT** 租户策略数据、业务联调与验收、监控与值守 |
|
||||
|
||||
**说明**：
|
||||
|
||||
- 若贵方现场要求**一个晚上完成全部步骤**，可将 DDL 与部署**合并在同一晚间窗口**执行，本表仅体现「周二、周三两晚」的**当前意向拆分**，最终以确认单为准。
|
||||
- 两次窗口建议**间隔至少数小时至一个工作日**，便于第一次变更后观察库表与低风险项；若合并为单次窗口，须在计划单中注明**连续操作顺序与回滚点**。
|
||||
|
||||
**待确认栏**（实施时填写）：
|
||||
|
||||
- 周二实施日期：`____年____月____日`，时段： `____ : ____` – `____ : ____`
|
||||
- 周三实施日期：`____年____月____日`，时段： `____ : ____` – `____ : ____`
|
||||
- 甲方现场联系人： `____________` 乙方/实施负责人： `____________`
|
||||
|
||||
---
|
||||
|
||||
## 3. 影响范围与沟通
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| 影响系统 | 电梯派梯相关应用（`cw-elevator-application`）及同一业务库。 |
|
||||
| 用户感知 | 应用重启期间可能出现短时派梯接口失败；策略误配可能导致部分访客路径失败，需按验收清单核对。 |
|
||||
| 通知范围 | 建议提前通知：物业/客服、前台与访客登记、安保与梯控相关值班（按项目实际 roster 确定）。 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 前置条件（升级前）
|
||||
|
||||
- [ ] 已与甲方确认 **周二 / 周三** 夜间窗口。
|
||||
- [ ] 取得 **v2.0.0** 发布包（含 `jar`、`ddl/tenant_visitor_floor_policy.sql`、说明书）。
|
||||
- [ ] 目标环境 **JDK 版本**符合实施方要求（与构建说明一致，一般为 JDK 8）。
|
||||
- [ ] 数据库已做**备份**（全库或按运维规范），并可从发布包定位 DDL。
|
||||
- [ ] 明确需启用「固定访客楼层」的租户列表及**允许区域**配置（若不启用，可跳过策略数据录入，行为与升级前一致）。
|
||||
- [ ] 回滚包：保留**当前线上 JAR** 备份与回滚步骤（见下文）。
|
||||
|
||||
---
|
||||
|
||||
## 5. 实施步骤（建议顺序）
|
||||
|
||||
### 5.1 周二晚间（或首个窗口）
|
||||
|
||||
1. 备份数据库。
|
||||
2. 执行 `tenant_visitor_floor_policy.sql`（`CREATE TABLE IF NOT EXISTS`，可重复执行需与 DBA 确认）。
|
||||
3. （可选）在测试/预发环境先执行一遍并验证。
|
||||
4. 记录执行人、时间与结果。
|
||||
|
||||
### 5.2 周三晚间（或第二个窗口 / 同晚续作）
|
||||
|
||||
1. 停止或滚动发布应用（按现网规范）。
|
||||
2. 替换为 `cw-elevator-application-2.0.0.jar` 并启动。
|
||||
3. 按业务需求对需启用的租户执行策略 **INSERT**（`enabled=1`、`allow_zone_ids` 等为合法 JSON 等，字段级以技术说明书为准）。
|
||||
4. 抽样验证：未传显式楼层时的访客派梯、租户策略开/关、与组织楼层无交集时的失败提示等。
|
||||
5. 观察监控与日志，**值守**至约定结束时间。
|
||||
|
||||
*若合并为单次窗口：按「备份 → DDL → 部署 JAR → 策略数据 → 验收」顺序连续执行，并预留回滚决策时间。*
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收要点（摘要）
|
||||
|
||||
- 未配置或未启用策略时：与升级前行为一致。
|
||||
- 已启用策略且业务走「未显式指定楼层」路径：访客可去楼层为**组织允许**与**租户允许**的**交集**。
|
||||
- 交集为空时：接口返回预期业务错误（技术码见实施方说明书）。
|
||||
- 第三方已显式传入楼层的路径：不因本策略表改变原逻辑。
|
||||
|
||||
---
|
||||
|
||||
## 7. 回滚预案
|
||||
|
||||
| 场景 | 建议动作 |
|
||||
|------|-----------|
|
||||
| 应用异常 | 回退至上一版本 JAR；数据库新表若已存在且旧应用不读该表，通常可继续服务；与实施方确认。 |
|
||||
| 策略配置错误 | 优先**停用或修正策略行**，避免大规模回滚应用。 |
|
||||
| 必须撤表 | 仅在评估无依赖后由 DBA 执行删表；**高风险**，需书面确认。 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 交付物核对
|
||||
|
||||
- [ ] `cw-elevator-application-2.0.0.jar`
|
||||
- [ ] `ddl/tenant_visitor_floor_policy.sql`
|
||||
- [ ] 《版本升级说明书》（实施/技术）
|
||||
- [ ] 本《甲方版本升级说明》（如已作为对甲交付）
|
||||
- [ ] 本《升级计划》（双方确认签字/邮件留档）
|
||||
|
||||
---
|
||||
|
||||
**文档状态**：草案；**时间点为暂定周二、周三晚间**，正式实施前请更新「待确认栏」并留存确认记录。
|
||||
@@ -0,0 +1,29 @@
|
||||
# cw-elevator-application v2.0.0 发布索引
|
||||
|
||||
本版本**功能升级说明**已单独成文，**仅覆盖「租户访客固定访问楼层」**及配套数据库 DDL，见：
|
||||
|
||||
**[cw-elevator-application-v2.0.0-版本升级说明书](./cw-elevator-application-v2.0.0-版本升级说明书.md)**
|
||||
|
||||
**对甲交付（业务表述与排期）**：
|
||||
|
||||
- [甲方版本升级说明](./cw-elevator-application-v2.0.0-甲方版本升级说明.md)
|
||||
- [升级计划（含夜间 · 周二/周三窗口）](./cw-elevator-application-v2.0.0-升级计划.md)
|
||||
|
||||
---
|
||||
|
||||
## 一键构建与发布目录
|
||||
|
||||
在仓库根目录、**JDK 8** 下执行：
|
||||
|
||||
```bash
|
||||
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
|
||||
./scripts/release-cw-elevator-application.sh
|
||||
```
|
||||
|
||||
输出：`**maven-cw-elevator-application/releases/v2.0.0/**`，含 `jar`、`ddl/`、`版本升级说明书.md`、`甲方版本升级说明.md`、`升级计划.md`、`发布说明.md`、`BUILD_MANIFEST.txt`。
|
||||
|
||||
---
|
||||
|
||||
## Git 与大文件
|
||||
|
||||
`maven-cw-elevator-application/.gitignore` 忽略 `**releases/**/*.jar**`；**DDL 与说明书**可提交；可执行 JAR 请通过制品库或制品服务器分发。
|
||||
@@ -0,0 +1,111 @@
|
||||
# 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`** 中构建时间为准。
|
||||
@@ -0,0 +1,34 @@
|
||||
# 电梯派梯应用 v2.0.0 — 版本升级说明（广发基金）
|
||||
|
||||
**制品**：`cw-elevator-application-2.0.0.jar`。技术细节、验收码与脚本位置见同目录《版本升级说明书》。
|
||||
|
||||
---
|
||||
|
||||
## 本次升级做什么
|
||||
|
||||
针对**广发基金**租户：访客走常见派梯路径（接口**未单独传楼层**）时，系统在「被访人所在单位给的可去楼层」基础上，再按**广发基金侧配置的允许区域**做一次收紧，两边**都满足**的楼层才能派梯。这样可以把访客权限收在比如固定接待层，而员工本人仍可按组织权限去多层办公。
|
||||
|
||||
广发基金若**未配置或未启用**该策略，行为与现在一致。
|
||||
|
||||
---
|
||||
|
||||
## 上线要动什么
|
||||
|
||||
- 换新版应用包。
|
||||
- 库里**多一张策略表**（脚本在发布包 `ddl/` 下）；表里为广发基金写入**一行**启用策略即可，允许区域（如接待层对应的 zone）由业务与实施定稿。
|
||||
|
||||
其它租户不配策略则**不受影响**。
|
||||
|
||||
---
|
||||
|
||||
## 对您这边的影响
|
||||
|
||||
- **时间**：安排在**夜间**，具体周二/周三窗口见《升级计划》。
|
||||
- **中断**：重启应用时派梯接口可能**短暂**不可用，一般会控制在很短时间。
|
||||
- **配合**：指定一个对接人；确认广发基金侧要开放的**访客可达区域/楼层**（与前台、接待流程对齐）；上线后若有异常派梯请及时反馈。
|
||||
|
||||
---
|
||||
|
||||
## 出问题怎么办
|
||||
|
||||
应用可先退回上一版包；策略数据可单独改/停，不一定整库回滚。细则见《升级计划》。
|
||||
Reference in New Issue
Block a user