# 星河湾星中星 — 版本发布计划与部署包规范

**日期**: 2026-05-09
**版本**: v1.0
**适用范围**: cw-elevator-application 及平台所有组件

---

## 目录

1. [版本命名规范](#1-版本命名规范)
2. [发布包目录结构与命名](#2-发布包目录结构与命名)
3. [JAR 制品命名规范](#3-jar-制品命名规范)
4. [配置文件规范](#4-配置文件规范)
5. [数据库 SQL 脚本规范](#5-数据库-sql-脚本规范)
6. [发布文档规范](#6-发布文档规范)
7. [构建流程](#7-构建流程)
8. [部署包交付清单](#8-部署包交付清单)
9. [版本发布检查清单](#9-版本发布检查清单)

---

## 1. 版本命名规范

### 1.1 语义化版本

```
MAJOR.MINOR.PATCH

MAJOR: 不兼容的 API 修改
MINOR: 向下兼容的功能新增
PATCH: 向下兼容的问题修复
```

### 1.2 平台组件版本清单

| 组件 | 当前稳定版 | Maven artifactId | 所属服务 |
|------|-----------|------------------|---------|
| cw-elevator-application | 2.0.17 | cw-elevator-application | 电梯应用 |
| ninca-common-component-organization | 2.9.4 | cwos-component-organization | 组织组件 |
| intelligent-cwoscomponent | — | intelligent-cwoscomponent | Feign 接口定义 |
| ninca-crk-std | — | ninca-crk-gpu-std | CRK 人脸识别 |
| ninca-qk-alarm | — | ninca-qk-alarm | 报警服务 |
| cloudwalk-common-* | 3.7.2 | cloudwalk-* | 公共库 |

### 1.3 版本号与日期标签

发布包命名包含版本号 + 构建日期:

```
格式: <组件名>-V<MAJOR>.<MINOR>.<PATCH>.<YYYYMMDD>

示例:
  cw-elevator-application-V2.0.17.20260505
  ninca-common-component-organization-2.9.4-xinghewan-20260506
```

**规则**:
- 日期使用 `YYYYMMDD` 格式，取构建当天
- 版本号与 Maven POM 中的 `<version>` 一致
- 历史遗留标签 `-xinghewan` 保留用于 component-org 的星中星定制版本

---

## 2. 发布包目录结构与命名

### 2.1 发布包根目录命名

```
<模块名>-V<版本号>.<日期>

# cw-elevator-application
cw-elevator-application-V2.0.17.20260505/

# ninca-common-component-organization
ninca-common-component-organization-2.9.4-xinghewan-20260506/
```

### 2.2 电梯应用发布包内部结构

```
cw-elevator-application-V2.0.17.20260505/
├── cw-elevator-application-V1.0.0.20211103.jar    # ★ JAR (固定名, 对齐V1)
├── bootstrap.properties                            # 启动配置
├── application.properties                          # 应用配置
├── application-access-control.properties           # 门禁配置
├── run.sh                                          # 启动脚本
├── common-java.sh                                  # Java 环境检测
├── start.sh                                        # systemd 启动
├── stop.sh                                         # systemd 停止
├── cw-elevator-application.service                 # systemd unit
├── ddl/
│   ├── tenant_visitor_floor_policy.sql              # DDL
│   ├── tenant_visitor_floor_policy_init_guangfa_fund.sql    # 广发种子 [@deprecated]
│   └── tenant_visitor_floor_policy_init_property_mgmt_6f.sql # 物业种子 [@deprecated]
├── 版本升级说明书.md
├── 发布说明.md
├── 甲方版本升级说明.md
├── 升级计划.md
├── 实施交付清单.md
├── 实施验收记录模板.md
├── SQL与代码一致性审核记录.md
├── collect_elevator_runtime_evidence.sh             # 现场证据采集
└── BUILD_MANIFEST.txt                               # 构建清单
```

### 2.3 组织组件发布包内部结构

```
ninca-common-component-organization-2.9.4-xinghewan-20260506/
├── ninca-common-component-organization-V2.9.2_20210730.jar  # JAR
├── application.properties
├── bootstrap.properties
├── recognition-logback.xml
├── run-verify.sh
└── ddl/
    └── organization_tenant_visitor_floor_policy_init_tenants.sql  # ★ 活跃策略种子
```

---

## 3. JAR 制品命名规范

### 3.1 电梯应用 (特殊)

```
JAR 文件名: cw-elevator-application-V1.0.0.20211103.jar  (固定)

原因: 生产部署脚本和运维习惯依赖此文件名。不随内部版本号变化。
内部版本由 BUILD_MANIFEST.txt 中的 git_rev 追踪。
```

### 3.2 其他组件

```
JAR 文件名: <artifactId>-<version>.jar

示例:
  ninca-common-component-organization-V2.9.2_20210730.jar
```

### 3.3 Maven 版本号

POM 中的 `<version>` 字段在构建时由 release 脚本自动设置:
- 构建前: `mvn versions:set -DnewVersion=<目标版本>`
- 构建后: 恢复为 `2.0-SNAPSHOT`

---

## 4. 配置文件规范

### 4.1 配置文件命名

| 文件 | 用途 | 必需 |
|------|------|------|
| `bootstrap.properties` | Spring Cloud 引导配置 (服务名, Consul/ZK) | ✅ |
| `application.properties` | 业务配置 (数据源, Redis, Dubbo, 楼层) | ✅ |
| `application-access-control.properties` | 门禁/通行规则配置 | ✅ |
| `application-test.properties` | 测试环境覆盖配置 | 测试用 |

### 4.2 配置关键属性命名

| 属性 | 格式 | 示例 |
|------|------|------|
| 楼层属性 | `<tenant>OrgId`, `<tenant>DefaultFloorId` | `xhwId`, `gfOrgId`, `xhwDefaultFloorId` |
| 楼栋属性 | `floor.building.id` | `605560539791228928` |
| Redis | `spring.redis.*` | — |
| 数据源 | `spring.datasource.url` | `jdbc:mysql://host:port/db` |

---

## 5. 数据库 SQL 脚本规范

### 5.1 SQL 文件命名

```
格式: [<库名>_]<表名>[_<用途>].sql

# DDL
tenant_visitor_floor_policy.sql
organization_tenant_visitor_floor_policy.sql

# 种子数据
organization_tenant_visitor_floor_policy_init_tenants.sql

# 迁移
tenant_visitor_floor_policy_v2.sql
tenant_visitor_floor_policy_migrate_org_id.sql
```

**命名规则**:
- 不带 `organization_` 前缀 = 电梯库 (历史 V1, 已废弃)
- 带 `organization_` 前缀 = 组织库 (活跃 V2)
- `_init_` = 种子数据 INSERT
- `_v2`, `_v3` = 版本迁移 DDL
- `_migrate_` = 数据迁移 DML

### 5.2 策略数据规范

`tenant_visitor_floor_policy` 行的命名规范:

```sql
-- ID 格式: {tenant_abbrev}_vstr_policy_{org_description}_{seq}
-- 广发基金: gf_vstr_policy_guangfa_fund_001x
-- 物业管理: pm_6f_vstr_policy_001 ~ 007

-- policy_type: REPLACE_ALLOWLIST (V2 正确语义, 非旧 INTERSECT_ALLOWLIST)

-- remark 格式: '{租户简称} | {策略说明} | org={org_id}'
-- 示例: '广发基金 | org=[28-38F] | 访客默认28F'
--       '物业管理 | 访客默认28F+6F'
```

### 5.3 V2 维护规则

| 规则 | 说明 |
|------|------|
| 策略唯一维护库 | `component-organization` |
| 电梯库策略表 | 已废弃 (`enabled=0`, `[DEPRECATED]` 前缀) |
| 种子 SQL 维护 | 仅 `organization_tenant_visitor_floor_policy_init_tenants.sql` |
| 电梯侧种子 SQL | 保留仅供历史参考 (`@deprecated` 注释) |

---

## 6. 发布文档规范

### 6.1 必需文档 (每个版本)

| 文档 | 文件名格式 | 内容 |
|------|-----------|------|
| 版本升级说明书 | `cw-elevator-application-v<VERSION>-版本升级说明书.md` | 变更内容、升级步骤 |
| 发布说明 | `cw-elevator-application-v<VERSION>-发布说明.md` | 版本概述、新功能、修复 |
| 甲方版本升级说明 | `cw-elevator-application-v<VERSION>-甲方版本升级说明.md` | 面向客户的升级说明 |
| 升级计划 | `cw-elevator-application-v<VERSION>-升级计划.md` | 时间表、里程碑 |
| 实施交付清单 | `cw-elevator-application-v<VERSION>-实施交付清单.md` | 交付物核对 |
| 实施验收记录模板 | `cw-elevator-application-v<VERSION>-实施验收记录模板.md` | 验收标准 |
| SQL审核记录 | `cw-elevator-application-v<VERSION>-SQL与代码一致性审核记录.md` | DDL/DML 审核 |
| 构建清单 | `BUILD_MANIFEST.txt` | 自动生成 (git rev, java version, timestamp) |

### 6.2 文档版本回退

release 脚本在找不到特定版本文档时，自动回退到 `DOC_FALLBACK_VER` (当前: `2.0.6`):

```bash
DOC_FALLBACK_VER="${DOC_FALLBACK_VER:-2.0.6}"
```

---

## 7. 构建流程

### 7.1 构建命令

```bash
# 在仓库根目录执行
./scripts/build/release-cw-elevator-application.sh <版本号>

# 示例: 构建 v2.0.18
./scripts/build/release-cw-elevator-application.sh 2.0.18

# 指定日期标签
RELEASE_DATE_LABEL=20260509 ./scripts/build/release-cw-elevator-application.sh 2.0.18

# 不生成 zip (仅目录)
RELEASE_MAKE_ZIP=0 ./scripts/build/release-cw-elevator-application.sh 2.0.18
```

### 7.2 构建步骤

```
Step 1: 环境检查 (JDK 8)
Step 2: mvn versions:set → 目标版本
Step 3: mvn package → 编译打包 (fat JAR)
Step 4: 复制 JAR 到 releases/
Step 5: 复制 DDL/SQL 到 releases/ddl/
Step 6: 复制文档到 releases/
Step 7: 复制配置文件 (bootstrap/application*.properties)
Step 8: 复制运行脚本 (run.sh, start.sh, stop.sh, common-java.sh)
Step 9: 生成 systemd service 文件
Step 10: 复制现场证据采集脚本
Step 11: 生成 BUILD_MANIFEST.txt
Step 12: 可选: 打包 zip
Step 13: mvn versions:set → 恢复 2.0-SNAPSHOT
```

### 7.3 构建产出

```
backend/cw-elevator-application/releases/
├── cw-elevator-application-V2.0.18.20260509/    # 发布目录
└── cw-elevator-application-V2.0.18.20260509.zip  # (可选) 压缩包
```

---

## 8. 部署包交付清单

### 8.1 必须交付

| # | 交付物 | 格式 | 说明 |
|---|--------|------|------|
| 1 | JAR 文件 | `.jar` | 固定文件名 |
| 2 | bootstrap.properties | `.properties` | 启动引导 |
| 3 | application.properties | `.properties` | 业务配置 |
| 4 | application-access-control.properties | `.properties` | 门禁配置 |
| 5 | DDL SQL | `.sql` | 表结构 |
| 6 | 种子 SQL | `.sql` | 初始数据 (仅组织库) |
| 7 | 运行脚本 | `.sh` | run.sh, start.sh, stop.sh |
| 8 | systemd unit | `.service` | Linux 服务配置 |
| 9 | 版本升级说明书 | `.md` | 变更内容 |
| 10 | 发布说明 | `.md` | 版本概述 |
| 11 | 甲方升级说明 | `.md` | 客户版 |
| 12 | 升级计划 | `.md` | 时间表 |
| 13 | 实施交付清单 | `.md` | 核对表 |
| 14 | 验收记录模板 | `.md` | 验收标准 |
| 15 | SQL审核记录 | `.md` | DDL/DML 审核 |
| 16 | 构建清单 | `.txt` | git rev, 时间戳 |
| 17 | 证据采集脚本 | `.sh` | 现场运维 |

### 8.2 不应交付

| 项目 | 原因 |
|------|------|
| Maven target/ 目录 | 构建中间产物 |
| 源码 `.java` | 闭源交付 |
| `.git/` | 版本库 |
| IDE 配置 `.idea/`, `.iml` | 本地开发配置 |
| 测试脚本和测试数据 | 非生产用途 |

---

## 9. 版本发布检查清单

### 发布前

- [ ] 所有单元测试通过
- [ ] `policy_type` 值为 `REPLACE_ALLOWLIST` (非旧 `INTERSECT_ALLOWLIST`)
- [ ] DDL 仅在 `organization_tenant_visitor_floor_policy_init_tenants.sql` 维护
- [ ] 电梯侧 SQL 已标记 `@deprecated`
- [ ] JDK 8 编译验证 (`java -version` → `1.8.x`)
- [ ] Maven POM 版本号与发布版本一致
- [ ] `BUILD_MANIFEST.txt` 包含正确的 git rev
- [ ] 配置文件中无测试环境硬编码值 (如 `localhost:9517`)

### 发布后

- [ ] 发布包目录结构完整 (16 项交付物)
- [ ] `run.sh` 可执行权限正确 (`chmod 755`)
- [ ] systemd service 文件路径占位符已替换
- [ ] zip 包 (如生成) 可正常解压
- [ ] SQL 文件可正常导入 (语法无误)
- [ ] 版本升级说明书版本号与发布包一致

### 数据库一致性

- [ ] `component-organization.tenant_visitor_floor_policy` 所有行:
  - `policy_type` = `REPLACE_ALLOWLIST`
  - `enabled` = 1 (需启用的行)
  - `remark` 格式统一: `'{租户} | {说明} | org={org_id}'`
- [ ] `cw-elevator-application.tenant_visitor_floor_policy` 所有行:
  - `enabled` = 0
  - `remark` 以 `[DEPRECATED]` 开头