合并回流与定制隔离

这是本规范最重要的一节，直接针对「定制误合并到新版本」的问题。

• 客户定制分支（custom/<版本>/客户-功能）仅用于交付该客户现场，交付方式为「从该 custom/ 分支单独打安装包」。
• 严禁 git merge custom/x.x.x/xxx → release/x.x.x，严禁 git cherry-pick 把定制代码搬进通用版本。
• 定制内容需在 doc/定制/ 备案，无文档不分定制：详细的文档组织、模板与定制 SQL 隔离规则见 §2.9。

feature/ 与 hotfix/ 分支必须经现场（或与现场等价的实际环境）部署验证通过后，方可回流合入 release。

• 门禁目的：保证 release 分支头始终对应「现场已验证状态」。这也是 01·分支生命周期「feature/hotfix 从 release 分支头拉取」的前提——基线可信，「验证产物 = 回流产物」才成立，两条规则互锁。
• 验证记录：验证通过后按模板复制到 doc/branch/<分支路径>/验证记录.md 填写（环境、日期、验证人、范围、结果，模板见 09·现场验证记录）；回流合并前核对记录存在且结论为「通过」，无记录不得合并。
• 未验证分支的处置：只允许停留在本分支或部署到验证环境，禁止 git merge / cherry-pick 进任何 release（含开发中版本）。
• 开发中版本尚无现场时，feature 以「与现场等价的实际环境」（联调环境 / 试点现场）验证代替，验证记录须注明环境类型。

现场修复分支必须回流到两个地方：

1. 原版本 release（如 hotfix/2.1.0/xxx → release/2.1.0），保证该版本后续现场拿到修复。
2. 下一个开发中的 release（如 → release/2.1.1），保证修复进入新版本。

hotfix 分支禁止任何数据库变更：不建表、不改列、不插数据。hotfix 面向已发布版本的现场快速修复，DB 变更意味着现场需执行升级脚本，风险与节奏都不匹配。已发布版本确需改库的项目 → 走 custom/ 定制分支交付（SQL 隔离见下方定制 SQL 隔离）；通用性的 DB 修复 → 进下个开发中版本，或多现场紧急时走维护性微版本（规则五）。

# 现场修复完成后
git checkout release/2.1.0 && git merge hotfix/2.1.0/xxx
git checkout release/2.1.1 && git merge hotfix/2.1.0/xxx   # 或 cherry-pick
# 然后删除 hotfix 分支
git branch -d hotfix/2.1.0/xxx

• custom/<版本> 与 line/<产品>/<版本> 从对应 release 分支头拉取（见 01·分支生命周期），并定期 merge 该 release 保持下行同步——release 头即「tag + 历次已验证修复」，同步一次即把全部通用修复带给客户/子产品。
• 原「hotfix → custom 逐个 cherry-pick」方式由整体同步取代（hotfix 回流 release 后随同步带入）；仅在客户明确只要个别修复时，才用 cherry-pick 精确控制，方向仍只能 hotfix → custom。
• 方向严格单向：release → custom/line；禁止 custom/line → release（防定制/子产品代码泄漏到通用版）。

# [✓] 正确：下行同步，把已验证修复带给定制/产品线
git checkout custom/2.1.0/huzhou-xxx
git merge release/2.1.0

# [✓] 客户明确只要个别修复时：精确 cherry-pick
git cherry-pick <hotfix-commit-hash>

# [✗] 禁止：把定制搬进通用
git checkout release/2.1.1
git merge custom/2.1.0/huzhou-xxx   # 绝对不允许

hotfix 禁改库（规则三）+ 已发布版本禁 feature（01·命名细则）之后，「多个现场都需要的通用数据库修复」缺少轻量出口，逐现场走 custom 成本过高。为此设维护性微版本（四段版本号）：

• 触发条件（满足其一）：① 影响多个现场的通用数据/结构缺陷；② 一批已验证 hotfix 累积到值得发补丁包。单现场问题仍走 custom，纯代码 bug 仍走 hotfix。
• 流程：从对应 release/<X.Y.Z> 拉出 release/<X.Y.Z>.<N>（N 从 1 起，如 release/2.1.0.1）→ 集中完成修复（允许改库，SQL 按主题序号汇总进 sql/release/<X.Y.Z>.<N>/，规则同 06·SQL 版本化）→ 现场验证（规则二门禁同样适用）→ 打 tag vX.Y.Z.N → sql/tag/<X.Y.Z>.<N>/ 冻结 → 各现场按序执行增量。子产品同理，tag 如 eos-v1.0.0.1。tag 段数即类型：三段 = 正式版，四段 = 微版本。
• 回流：与 hotfix 相同的双向回流——合回原 release/<X.Y.Z> 与下个开发中 release；代码侧整体 merge，SQL 侧按主题并入下个开发中版本对应的序号文件（原版本线保留微版本目录作为补丁包交付物）。
• 频率约束：微版本是例外通道不是常态。同一版本线微版本超过 3 个仍未升级大版本的，应推动现场升级而非继续打补丁。

提交前自问：这段代码/SQL 是否所有现场都适用？

• 是 → feature/ 或 hotfix/，可回流 release。
• 否（仅某客户需要）→ custom/，禁止回流。
• 否（属某子产品专属，非单客户）→ 归入对应产品线 line/<产品>/，回流规则见 01·产品线回流。

本地 Hook 可被绕过，服务端保护才是最后防线。本项目托管于公司私有 GitLab，由仓库 Owner/Maintainer 在 Settings → Repository 配置：

效果：

• main / release/* / line/* 禁止 git push 直推，所有改动必须走 Merge Request。
• MR 需至少 1 个 Maintainer 审批 + CI 通过方可合并，杜绝一人静默合入。
• 配合 §2.6，custom/* → release/* 的合并会在 MR 审查环节被发现并拒绝。

在 Settings → Repository → Push Rules 配置：

• Commit message 正则：^(feat|fix|docs|refactor|chore|perf|test|style|ci|build|revert)(\(.+\))?: .+|^(Merge|Revert) .*

服务端再次拦截违规提交信息（兜底本地被绕过的 Hook）。

• 禁止提交文件名：hs_err_pid.*\.log|replay_pid.*\.log|\.DS_Store|log\.bin|\.iml$
• 最大文件大小：如 20MB，防止误传大文件（JVM heap dump 等）。
• 拒绝未引用 issue 的提交：按需开启（强制 Closes #xxx）。

MR 标题与描述沿用 §2.5 提交规范，描述模板建议包含：

## 变更类型
- [ ] feature 新功能
- [ ] hotfix 现场修复
- [ ] custom 客户定制（标注客户名）

## 关联版本
release/x.x.x / tag vX.Y.Z

## 变更说明
（做了什么、为什么、影响范围）

## 测试
- [ ] 自测通过
- [ ] 影响数据库的已补 sql/ 下对应分支目录的脚本（见 06·分支目录映射）并登记 CHANGELOG

定制分支（custom/<版本>/<客户>-<语义>）可长期存在，但若不记录「改了什么、基于哪个版本、交付哪个现场」，时间一久就无人能说清，现场出问题无从追溯。

强制要求：每个客户定制必须有对应文档，且与 custom/ 分支一一对应。

• 每个客户一个目录（doc/定制/<客户>/），客户名用中文或约定代号（与 §2.2 custom/ 分支名一致）。
• 每次定制一个 <功能>.md，对应一个 custom/ 分支。
• 客户目录下一个 README.md 汇总该客户所有定制，便于快速查阅。

记录所有定制客户一览，字段：客户、联系方式、维护人、定制数量、最近交付版本、客户目录链接。

汇总该客户所有定制，字段：定制项、对应分支、基线版本、交付现场、状态、维护人、文档链接。

每次定制必须包含以下章节：

定制涉及数据库变更时，SQL 不得混入通用 sql/ 目录（含 sql/release/、sql/tag/ 等，见 06·SQL 版本化），独立存放：

理由：通用 sql/ 按版本顺序执行到所有现场，定制 SQL 只能执行到对应客户，二者混放会导致通用现场误执行定制脚本。

• 通用修复需应用到客户时，按规则四对对应 release 做下行同步（merge），并在定制文档「与通用版的同步策略」章节登记；客户明确只要个别修复时，才用 cherry-pick 精确控制。
• 客户升级到新版本时，需重新评估定制项：定制功能是否已纳入通用版（若是则废弃定制分支）、是否需基于新版本 release 重建 custom/ 分支。
• 定制分支禁止向任何 release/* 合并（规则一），违反即定制代码污染通用版。