发版与现场验证
研发开发规范
四阶段检查单
现场验证记录
维护性微版本
红线速查
本篇学习指南
读完你能
- 按四阶段检查单独立走完一次版本发版，不漏项
- 正确填写现场验证记录，拿到回流的「通行证」
- 记住分支与 SQL 的五条硬规则和红线，避开事故级操作
1
发版与现场验证
发布流程总览
每个版本（vX.Y.Z）发版走四个阶段，逐项勾选检查单；主干流程与命令见 08·发布流程 SOP。
发版四阶段
冻结与验证
feature 合入齐 · 记录齐备
SQL 定稿
序号连续 · 幂等抽查
冻结与打包
tag 目录冻结 · 打 tag
交付与收尾
现场执行 · 逐项登记
维护性微版本（四段
vX.Y.Z.N，见 03·规则五）同样适用本检查单，版本号为四段发版信息：每个版本登记「发版版本 / 负责人 / 日期」三要素，检查单按版本归档到 doc/branch/tag/<版本>/，与发版说明放在一起。
阶段一：冻结与验证
- 该版本全部 feature 已合入
release/<版本>：sql/feature/<版本>/与doc/branch/feature/<版本>/无未合入遗留（顺延项已明确标记并登记） - 全部回流分支的验证记录齐备：
doc/branch/<分支路径>/验证记录.md存在且结论为「通过」 - 临时 worktree 中
mvnw compile通过（JDK 21） - 回归测试通过
阶段二：SQL 定稿
sql/release/<版本>/序号连续、无临时/草稿文件- CHANGELOG 该版本行登记完整（脚本、类型、影响表、作者、日期）
- 幂等性抽查通过（重点：本次新增的
ALTER/CREATE TABLE/INSERT） - （推荐）全新环境从 2.1.0 基线按版本顺序执行至本版本，全部脚本无报错
阶段三：冻结与打包
sql/release/<版本>/全量复制为sql/tag/<版本>/，附 README 冻结声明- CHANGELOG「脚本」列路径与 tag 目录实际文件一致
doc/branch/tag/<版本>/发版说明.md完成（本次变更清单、升级步骤、已知问题）- 打 annotated tag，tag 号 = 安装包版本号（
git tag -a vX.Y.Z -m "..."） - 出集成安装包（安装包附带 tag 目录 SQL）
阶段四：交付与收尾
- 现场按
sql/tag/<版本>/序号顺序执行，CHANGELOG「现场执行」列逐现场登记 - tag 目录自此冻结：此后该版本只走 hotfix（禁改库）/ custom 定制 / 维护性微版本
- 发版说明归档；规范、速查表如有修订同步推送
现场验证记录（回流门禁的凭证）
用法：复制模板到 doc/branch/<分支路径>/验证记录.md 后填写。回流合并前，负责人核对本记录存在且结论为「通过」（03·规则二：无记录不得合并）；发版检查单阶段一会再次全量核对。「验证记录.md」是固定文件名、不可改名——固定名规则与文档目录去向见 10·文档目录规范。
记录字段：
| 字段 | 说明 |
|---|---|
| 分支 | feature/2.1.1/xxx |
| 验证环境类型 | 现场 / 联调环境 / 试点现场（开发中版本尚无现场时，feature 允许用后两者代替，须注明） |
| 环境信息 | 客户/现场名 或 环境地址、部署包版本号 |
| 验证日期 | YYYY-MM-DD |
| 验证人 | 执行验证的责任人 |
| 验证范围 | 本次变更涉及的功能点 / 修复点清单（对应分支语义） |
验证步骤与结果（逐项填写）：
| # | 步骤 / 场景 | 预期 | 实际 | 结果 |
|---|---|---|---|---|
| 1 | <操作步骤或复现场景> | <预期表现> | <实际表现> | ✅ / ❌ |
| 2 | … | … | … | … |
- 遗留问题：无 / 描述（注明是否阻塞回流；阻塞项必须解决后方可回流）。
- 结论：✅ 通过，同意回流 release；或 ❌ 不通过（原因见遗留问题）。
「通过」的记录不只是一张表——它同时是「release 头 = 现场已验证状态」这条链条上的一环：有了它，后续所有人从 release 头拉分支、做下行同步时，基线才是可信的。
分支与 SQL 五条硬规则与红线
五条硬规则（一页看懂，完整规则见各篇）：
- 命名：
<前缀>/<版本>/<语义>，语义中文/英文均可（如feature/2.1.1/物联缓存一致性、hotfix/2.1.0/knx-fix），禁止空格。 - 拉取：feature / hotfix / custom / line 一律从 release 分支头拉（不从 tag 拉）。
- 门禁：未现场验证（记录落
doc/branch/<分支路径>/验证记录.md）禁止回流 release。 - hotfix 不碰数据库；已发布版本要改库 → 走
custom/定制分支（多现场通用 DB 修复 → 维护性微版本）。 - 已发布版本（已有 tag）不开 feature。
红线（违反 = 事故）：
❌ custom/ 或 line/ 合并进任何 release（定制/子产品污染通用版）
❌ 未验证的分支 merge / cherry-pick / 直提进 release
❌ hotfix 分支里的 DDL / DML（建表、改列、插数据）
❌ 定制 SQL 出现在通用 sql/ 目录
❌ 修改已冻结的 sql/tag/<版本>/
新手常见问题
发版当天最容易手忙脚乱，这些问答提前看
为什么发版当天要专门复制一份 sql/tag/<版本>/？直接用 sql/release/ 不行吗？
安装包附带的是 tag 目录的 SQL——「同一个版本号 = 同一套 SQL」全靠它保证。release 目录在发版后仍会接收回流修正，若安装包直接指向它，同一版本号的现场拿到的脚本就可能不一样，排查问题时无从对齐。所以打包当天冻结一份副本并声明「此目录冻结不改」，修正走
sql/release/ + 下个版本 / hotfix / 微版本流程。v2.1.0.1 和 v2.1.1 有什么区别？看起来都像“小版本”
看段数：三段 = 正式版，四段 = 维护性微版本。v2.1.0.1 是从
release/2.1.0 拉出的四段微版本——面向「多个现场都需要的通用 DB 修复 / 补丁包」，允许改库但频率受限；v2.1.1 是正常的三段正式版，走完整发版流程。微版本同样要现场验证、双向回流，检查单也照用（版本号写四段）。验证记录谁来核对？什么时候核对？
两个时点：① 回流合并前——负责人（MR 审查时）核对
doc/branch/<分支路径>/验证记录.md 存在且结论为「通过」，无记录不得合并；② 发版阶段一——检查单要求全量核对所有回流分支的记录齐备。平时随手翻 doc/branch/ 也能看到每个版本都有哪些现场修复、验证结论如何。