starRiverProperty/docs/superpowers/specs/2026-05-09-release-plan-and-naming-conventions.md

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

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

---

目录

1. 版本命名规范
2. 发布包目录结构与命名
3. JAR 制品命名规范
4. 配置文件规范
5. 数据库 SQL 脚本规范
6. 发布文档规范
7. 构建流程
8. 部署包交付清单
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 行的命名规范:

-- 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):

DOC_FALLBACK_VER="${DOC_FALLBACK_VER:-2.0.6}"

---

7. 构建流程

7.1 构建命令

# 在仓库根目录执行
./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] 开头