# **5.1 版本控制与代码提交规范**

优秀的版本控制应当像一本条理清晰的编年史，任何人在任何时候接手代码，都能通过 Git 历史精准还原业务的演进过程。本规范旨在建立清晰、可追溯、自动化的代码流转体系。

### **5.1.1 分支管理模型 (Branching Model)**

为了兼顾敏捷交付与生产环境的极度稳定，团队统一采用 **简化的 GitFlow / 环境变量流 (Environment Flow)**。

#### **1\. 核心常驻分支 (Protected Branches)**

这三个核心分支与部署环境严格绑定，**绝对禁止**任何开发人员直接使用 git push 推送代码，必须通过 PR/MR 流程合并：

* **main (或 master) \- 生产环境分支**：  
  * 对应线上生产环境 (Production)。  
  * 这里的代码必须是随时可发布、经过全面测试的绝对稳定版本。  
* **test (或 release) \- 测试/预发环境分支**：  
  * 对应 QA 测试环境或预发布环境 (Staging)。  
  * 用于产品经理验收和测试工程师进行系统级回归测试。  
* **dev (或 develop) \- 开发集成环境分支**：  
  * 对应日常开发联调环境。  
  * 汇总所有开发人员最新的 Feature 代码，允许存在一定的 Break Change，但必须保证编译和基础启动不报错。

#### **2\. 临时工作分支 (Temporary Branches)**

开发人员日常编码都在临时分支上进行，命名必须遵循以下前缀规范，并在开发完成后删除：

* **feat/xxx**：新功能开发分支（从 dev 检出，合并回 dev）。  
  * *示例：feat/user-login-wechat*  
* **fix/xxx**：常规 Bug 修复分支（从 dev 或 test 检出）。  
  * *示例：fix/order-amount-calc-error*  
* **hotfix/xxx**：线上紧急漏洞修复分支（**直接从 main 检出**）。  
  * *红线：紧急修复测试通过后，必须同时双向合并到 main 和 dev 分支，防止代码覆盖丢失！*

### **5.1.2 Commit Message 格式规范 (Conventional Commits)**

**核心理念：让机器能读懂提交历史，以便自动生成 Release Notes。**

团队强制遵循 Angular 提交规范。推荐在项目中引入 commitlint 配合 Git Hooks（如 pre-commit）进行强制拦截。

#### **1\. 标准格式**

\<type\>(\<scope\>): \<subject\>  
\<空行\>  
\<body\>

#### **2\. Type (提交类型 \- 必填)**

* feat: ✨ 新增功能 (Feature)  
* fix: 🐛 修复缺陷 (Bug)  
* docs: 📝 文档更新 (Documentation)  
* style: 🎨 代码格式修改（不影响逻辑，如空格、缩进、格式化工具输出）  
* refactor: ♻️ 代码重构（既不是新增功能，也不是修复 bug 的代码更改）  
* perf: ⚡️ 性能优化 (Performance)  
* test: ✅ 新增或修改测试用例  
* chore: 🔧 构建过程、CI/CD 脚本、辅助工具库的更改

#### **3\. Scope (影响范围 \- 可选)**

用于说明本次提交影响的模块，如 (user), (order-service), (ci)。

#### **4\. Subject (简短描述 \- 必填)**

* 必须使用祈使句（如：“添加用户登录”，而不是“添加了用户登录”）。  
* 结尾**不要**加句号。  
* 如果关联了特定的任务卡片或 Issue 编号，强烈建议带上（如：feat(auth): 支持微信扫码登录 (\#ISSUE-102)）。

#### **4\. 反面教材与正确示范**

* ❌ 错误：update 代码  
* ❌ 错误：fix bug  
* ✅ 正确：fix(payment): 修复并发退款时状态一致性问题 (\#bug-882)  
* ✅ 正确：feat(externals): 增加 Dify 代理网关接口

### **5.1.3 Tag 与版本号命名规则 (Semantic Versioning)**

**红线：严禁人肉编造随意字符串作为版本号。** 所有对外发布、打包上线的制品（如 Docker 镜像、NPM 包、Maven 依赖）必须严格遵循 **语义化版本 (SemVer 2.0.0)** 规范。

#### **1\. 版本号格式：v\<MAJOR\>.\<MINOR\>.\<PATCH\>**

* **MAJOR (主版本号)**：当你做了**不兼容的 API 修改**或系统进行了史诗级重构时。  
* **MINOR (次版本号)**：当你做了**向下兼容的新功能新增**时。  
* **PATCH (修订号)**：当你做了**向下兼容的缺陷修复 (Bugfix)** 时。

*示例：v1.0.0 \-\> v1.1.0 (加了新功能) \-\> v1.1.1 (修了新功能的 Bug) \-\> v2.0.0 (接口大重构，老版本客户端不可用)。*

#### **2\. 预发布版本后缀**

在正式 Tag 之前，如果是处于测试阶段的里程碑，应当追加连字符与标识：

* Alpha (内测版): v2.0.0-alpha.1  
* Beta (公测版): v2.0.0-beta.1  
* RC (Release Candidate 候选发布版): v2.0.0-rc.1

### **5.1.4 提交与合并纪律 (Commit & Merge Discipline)**

为配合 4.2 代码审查规范 与 CI/CD 质量门禁，特设立以下代码流转纪律：

1. **防门禁失败兜底 (Pre-commit)**：  
   * 所有代码在 git commit 时，必须触发本地钩子验证。如项目存在特定的门禁脚本（如 GTCO\_AI 项目下的 scripts/ci/quality\_gate.sh），必须在本地保证执行通过。  
2. **禁止强推 (No Force Push)**：  
   * 绝对禁止对 dev, test, main 等公共分支执行 git push \-f。此行为将直接导致团队其他成员的版本库断裂。  
3. **主张 Squash Merge (压缩合并)**：  
   * 开发者在自己的 feat/xxx 分支上为了备份，可能会产生大量零碎的 commit（如 fix typo, update again）。  
   * 在通过 PR 合并到主干分支（如 dev）时，**强烈建议使用 Squash and Merge**，将无数琐碎的 commit 压缩成一个整洁的业务 Commit 记录进入主干。  
4. **及时变基 (Rebase / Sync)**：  
   * 开发周期较长的 Feature 分支，必须每天从目标主干分支拉取最新代码（建议使用 git pull \--rebase origin dev），提前解决冲突，严禁等到提 PR 那天才去处理几千行的灾难性冲突。