合并策略

• 合并方向与方式

  • 目标：将 hotfix/calc-rounding-bug 以最小改动、可审计的方式合入 main，并自动触发紧急补丁发布。
  • 合并方法：通过 PR 合并到 main，使用 Squash merge（保持主干简洁、便于回溯一次修复）。禁止在该分支上进行强推或交互式 rebase。
  • 提交信息规范：使用语义化提交，建议 squash 提交标题为 fix(calc): rounding bug，正文包含根因、影响范围、回归风险点与测试覆盖。

• 基线与冲突策略

  • 不将 main 合并进 hotfix 分支（避免引入额外变更面），改为在临时分支验证合并冲突，确保“无冲突检查”通过。
  • 若发现冲突，仅在 PR 前于临时合并分支定位并修复冲突，再回到 hotfix 分支做最小必要修改（不扩大改动面）。
  • 禁止在 hotfix 分支中修改版本号文件与 CHANGELOG（见下一条）。

• 版本号与 CHANGELOG 专项策略（针对历史冲突）

  • 人工约束：热修复 PR 严禁包含 version.、package. version 字段、CHANGELOG.* 的变更。由发布流水线在合入 main 后自动做 patch 版本号提升与 changelog 生成。
  • CI 守护：在 PR 检查中加入“禁止修改版本/CHANGELOG 文件”的校验（如 diff 规则或 Danger/自定义 Action），直接阻断不合规变更。
  • 提交信息驱动：依靠语义化提交自动生成 CHANGELOG，避免手写冲突。

• CI/CD 与发布流程

  • PR 必须通过：单元/集成测试、静态检查、合并结果构建（Merge-queue 或 “merge-preview” 构建）以满足“必须通过 CI/CD 流水线”和“无冲突检查”。
  • 合并后自动发布：当分支名为 hotfix/* 且流水线通过时，自动执行：
    • 版本号自动 +1（patch）
    • 生成并追加 changelog
    • 打 Tag（修复上次失败的根因：由流水线统一改写版本与 changelog，避免人工冲突）
    • 走生产发布通道（可走热修复优先级队列）
  • 回滚准备：发布作业保留上一个可回滚版本；如健康检查不达标，自动中止并回滚。

• 外部 API 依赖策略

  • 合并前检查：在 CI 中加入外部 API 合同测试（使用 mock + 合同校验），并在发布阶段加健康探针（实际环境连通性/版本/速率限制）。
  • 发布门禁：发布作业在生产前增加“外部 API 就绪”门（自动探测或运维手动勾选），未满足则阻塞发布。
  • 降级/开关：以特性开关或回退路径保护，若外部 API 未更新/不稳定，可快速关闭热修复路径或启用降级逻辑。

操作提示

• 本地与预检查（不改动 hotfix 分支历史）

  • git fetch origin
  • 基于 main 建立临时合并验证分支并检测冲突：
    • git switch -c tmp-merge-check origin/main
    • git merge --no-ff hotfix/calc-rounding-bug --no-commit
    • 若出现冲突：
      • 记录冲突文件；对版本号与 CHANGELOG 若出现冲突，决策为“保留 main 版本，热修复不修改”，并把需要的代码最小化调整回 hotfix 分支修复（不要把 main 合并进 hotfix）。
    • git merge --abort
    • git switch -
    • git branch -D tmp-merge-check
  • 确认热修复分支仅包含修复与测试，不含版本号/CHANGELOG/格式化大改。

• 提交与 PR

  • 推送 hotfix 分支（无需 force）：git push -u origin hotfix/calc-rounding-bug
  • 创建 PR 指向 main：
    • 标题：fix(calc): rounding bug
    • 标签：hotfix、urgent
    • 勾选仅允许 Squash merge
  • CI 要求：
    • 必须通过流水线（含合并预览构建）
    • Bot 校验版本与 CHANGELOG 未被修改
    • 外部 API 合同测试通过

• 合并与发布

  • 审查通过后执行 Squash merge，合入 main。
  • 依赖流水线自动：
    • 版本号 patch 提升
    • 生成 CHANGELOG
    • 打 Tag 并发布到生产（热修复优先级通道）
  • 发布门禁与观测：
    • 确认外部 API 已更新就绪（自动探针/人工门）
    • 先做小流量/灰度，监控错误率与关键业务指标，稳定后全量放开

• 风险控制与回滚

  • 若发布失败或健康检查异常：
    • 自动回滚至上一个 Tag
    • 关闭相关特性开关
    • 在 PR 追加事后记录与后续改进项

• 后续维护

  • 若有长期维护分支（如 release/*），将 main 中的 squash 提交按需 cherry-pick 到对应分支（仍不携带版本/CHANGELOG 变更）。
  • 将“禁止版本/CHANGELOG 变更”的校验与自动发布策略沉淀为常规规则，消除同类冲突根因。

合并策略

• 分支与目标

  • 当前分支：feature/db-sharding-phase1
  • 目标分支：release/2025.12（预发布稳定环境）
  • 协作模式：GitLab Flow（通过 Merge Request 集成到环境/发布分支）

• 合并方式与约束

  • 仅通过 Merge Request 合入 release/2025.12，禁止直接在 release 分支提交。
  • MR 合并策略：Merge commit（禁用 fast-forward），便于一键回滚整合并提交；不使用 squash，以保留迁移步骤的提交边界。
  • 禁止对共享分支（release/*）进行 rebase 或 force-push；feature 分支亦避免强推，按合并为主。

• 分阶段集成（适配“Phase1 + 稳定环境”）

  • Phase1 仅包含“可前滚的扩展式改动 + 向后兼容的代码 + 开关受控”，避免破坏性 DDL 与数据回收操作。
  • 建议按三小步提交（可拆为多个 MR，或一个 MR 中分阶段流水线/开关控制）：
    1. Expand：无破坏 DDL（加列/加索引/加冗余表/建立新分片路由元数据），DAO 层实现双读兼容（新旧路径并存），默认关闭新路径。
    2. 验证与灰度：在预发布环境开启只读流量开关与影子读/灰度读路由，完成数据校验、回填与一致性校验（必要时双写/校验读）。
    3. Contract（不在本次 Phase1 合入）：删除旧列/旧索引/旧路由等破坏性收缩改动延后至后续版本。
  • 合并后打 RC 标签（如 v2025.12-rcN），通过预发布环境的受控部署与手工门禁。

• 依赖与门禁

  • CI/CD 必须全部通过（含代码规范检查、单测/集成测试、迁移脚本 dry-run）。
  • 审批：至少N人批准（按项目设置）；MR 必须关联任务单。
  • 特殊依赖纳入流水线顺序：数据库迁移（expand）→ 应用部署 → 配置中心发布（特性开关默认关闭）→ 手工门禁灰度流量。
  • 回滚预案：准备 down 脚本与特性开关一键关闭；以合并提交为单位执行 revert；必要时切只读流量以保护数据一致性。

• 冲突与稳定性侧重（针对既往问题）

  • DDL 与 DAO 必须严格版本对齐：先落地 expand DDL，再上兼容 DAO 代码；开关默认关，避免启动时访问缺失结构。
  • 严禁在 Phase1 MR 中包含删除/重命名列等破坏性 DDL。
  • DAO 层通过 SchemaVersion/Capability 检测（或迁移版本号）做分支逻辑，避免启动时因结构未就绪而失败。

操作提示

• 合并前同步与自测

  1. git fetch origin
  2. git checkout feature/db-sharding-phase1
  3. 将 release/2025.12 的最新变更合入当前分支（减少 MR 冲突风险）
     • git merge origin/release/2025.12
  4. 本地执行：
     • 单元/集成测试
     • 迁移脚本 dry-run（对预发布库/影子库）：仅包含 expand 脚本
     • 代码规范检查
  5. 推送分支：git push origin feature/db-sharding-phase1

• 数据库与配置中心准备

  • 迁移脚本
    • 命名示例：V2025_12_XXXX_expand.sql（幂等、可重复执行），V2025_12_XXXX_contract.sql（暂不在 Phase1 执行）。
    • 脚本内置前后置校验（存在性检查、行数/索引健康、超时与锁等待阈值）。
  • 配置中心
    • 新增特性开关：db.sharding.phase1.enabled=false
    • 只读切换键：db.readOnlySwitch=false
    • Schema/Route 版本键：db.schema.version=2025.12
    • 发布顺序：应用部署后再发布配置；开启新路径需手工门禁。

• 提交 MR（指向 release/2025.12）

  • 勾选：Pipelines must succeed、Merge commit（no-ff）。
  • 附加内容：
    • 关联任务单
    • 迁移/回滚方案与手工操作步骤
    • 风险评估与观察指标（错误率、慢查询、路由命中率、写入延迟）
  • 审批：至少N人批准（含 DB/后端/运维各一名为佳）。

• 预发布环境演练（GitLab Flow 环境）

  1. 执行 DB expand 迁移 Job（受保护、需手工确认）。
  2. 部署应用（feature 开关仍为 false）。
  3. 手工门禁：逐步开启只读流量/影子读用于校验分片路由正确性。
  4. 若包含回填/重分片任务：在只读或低峰窗口执行，完成后校验一致性指标。
  5. 观察期通过后，仅在预发布环境小流量开启 db.sharding.phase1.enabled=true 做灰度验证；生产仍保持关闭。

• 回滚与应急

  • 出现不兼容：
    • 立即关闭 db.sharding.phase1.enabled 与只读开关；
    • 回退应用版本（不回退 expand 结构）；
    • 必要时对 MR 执行 git revert -m 1 <merge_commit_sha>（在新分支上提交 MR 回到 release/2025.12），并同步关闭相关配置。
  • 数据库层回滚仅在确认无依赖新结构后执行 down 脚本，避免二次破坏。

• 注意事项

  • 禁止对 release/2025.12 强制推送/重写历史；禁止直接在该分支上开发。
  • Phase1 不得包含破坏性 DDL；Contract 改动推迟至后续版本并单独 MR。
  • 严格遵守迁移先行、代码兼容、再灰度放量的顺序。
  • 与 DBA/配置中心/运维确认变更窗口与回退时间窗，确保可观测性与审批链闭环。