PART 5 - 研发协作规范

5.1 - Git 分支策略 (Git Workflow)

我们采用业界成熟的 Git-Flow 简化模型，它在功能开发、版本发布和热修复之间取得了很好的平衡。

核心分支:

• main (或 master): 生产分支。

  • 用途: 存放随时可以部署到生产环境的稳定代码。此分支的代码版本应与线上运行的版本严格对应。
  • 规则: 严禁直接向 main 分支推送代码。所有变更必须从 release 分支或 hotfix 分支合并而来。
  • 标签: main 分支上的每一次合并都必须打上一个唯一的、语义化的版本标签（如 v1.2.0）。

• release: 预发布分支。

  • 用途: 用于发布前的最后准备工作。当 dev 分支的功能集基本稳定，准备提测发布时，从此分支创建 release 分支。
  • 规则: 在此分支上只进行 Bug 修复、文档生成等与发布相关的微调。不允许再合入新的功能。
  • 流程: 测试通过后，release 分支必须合并到 main（发布到生产），并且也必须合并回 dev（确保 dev 分支包含修复的 Bug）。

• dev: 主开发分支。

  • 用途: 集成所有功能开发的最新代码，是团队功能开发的基线。
  • 规则: 严禁直接向 dev 分支推送代码。所有新功能和 Bug 修复都应通过 feature 分支的 MR/PR 进行合并。
  • 状态: dev 分支应保持相对稳定，至少需要保证编译和自动化测试可以通过，以便随时拉出新的 feature 分支。

辅助分支:

• feature/*: 功能分支。

  • 用途: 开发新的业务功能。每个功能都应在一个独立的分支中进行。
  • 命名: feature/
    • 功能简述，如 feature/user-authentication。
  • 流程: 从 dev 分支创建，开发完成后，合并回 dev 分支。

• hotfix/*: 热修复分支。

  • 用途: 紧急修复线上 main 分支的严重 Bug。
  • 命名: hotfix/
    • 修复问题简述，如 hotfix/login-captcha-error。
  • 流程: 从 main 分支的对应版本标签创建，修复完成后，必须同时合并回 main 和 dev 分支（以及正在进行的 release 分支，如果有的话）。

工作流示意图:

main:    ------------------o-------------------o-----> (Tags: v1.0, v1.1)
         ^                 ^                   ^
         |                 |                   |
release: |----(Release)-----|----(Hotfix)-------|
         ^                 |                   ^
         |                 v                   |
dev:     o--------o--------o-----------o-------o----->
         ^        ^        ^           ^
         |        |        |           |
feature: |---(F1)--|        |---(F2)----|

5.2 - Git 提交信息规范 (Commit Message)

清晰的 Commit Message 是项目可追溯性的基石。我们遵循 Conventional Commits 规范。

格式: type(scope): subject

• type (必填):

  • feat: 新功能 (feature)
  • fix: 修补 bug
  • docs: 文档 (documentation)
  • style: 格式（不影响代码运行的变动，空格、格式化等等）
  • refactor: 重构（即不是新增功能，也不是修改 bug 的代码变动）
  • test: 增加测试
  • chore: 构建过程或辅助工具的变动
  • ci: 对 CI/CD 配置文件的修改

• scope (选填): 本次提交影响的范围，如 user, order, api, ui 等。

• subject (必填): 提交目的的简短描述，不超过 50 个字符，使用动词开头，如“增加”、“修复”。

示例:

• 好的提交:
  • feat(user): add user registration endpoint
  • fix(order): correct calculation error in total price
  • docs(readme): update deployment instructions
• 不好的提交:
  • fix bug
  • update
  • 提交代码

5.3 - 代码审查与合并请求 (Code Review & MR)

分支保护是铁律！

1. 锁定主线: main, release, dev 分支必须在仓库（GitHub/GitLab）中设置为“保护分支”。
2. 禁止强推 (Force Push): 保护分支必须禁止强制推送。
3. 必须通过 MR 更新: 所有对保护分支的合并请求，都必须通过 Merge Request (MR) / Pull Request (PR) 的方式进行。

MR/PR 规范:

1. 发起人职责:

   • MR 的标题和描述应清晰明了，关联对应的需求或 Bug Ticket。
   • 在提交 MR 前，必须在本地完成自测，并确保与最新的 dev 分支没有冲突。
   • 指定合适的审查者 (Reviewers)。

2. 审查 (Review) 流程:

   • 两人审核制: 每个 MR 必须由至少 2 位同事进行审查 (Approve)。
   • 终审制: 对于核心模块或重大改动，必须由该模块的负责人或资深工程师进行 最终审核 (Final Approve)。
   • 作者禁止合并: MR 的发起人 不能 亲自点击合并按钮，必须由最后一位审查者在确认无误后进行合并。

5.4 - 测试与流水线规范

质量是开发出来的，不是测试出来的。测试环节与 CI/CD 流水线深度绑定，是代码进入主线的“质检关卡”。

测试环节:

1. 单元测试: 开发者在 feature 分支开发时，必须为核心逻辑编写单元测试，保证代码逻辑的正确性。
2. 开发自测: MR 发起前，开发者必须在本地或开发环境对自己开发的功能进行完整测试。
3. 测试环境验证 (QA): 当 feature 分支合并到 dev 后，CI/CD 会自动将 dev 分支的代码部署到 测试环境。此时，由测试人员进行专业的功能测试和回归测试。
4. 预发布环境验证 (UAT): 当 release 分支创建后，会自动部署到 预发布环境。此时进行上线前的最终验收测试。

流水线 (Pipeline) 规范:

流水线是执行上述流程的自动化工具，是保障规范落地的重要手段。

• MR 流水线: 提交 MR 或向 MR 的源分支推送代码时自动触发。

  • 阶段一: 代码检查 (Lint): 执行 ESLint, Checkstyle 等静态代码扫描。
  • 阶段二: 构建 (Build): 执行 npm run build, mvn clean package。
  • 阶段三: 单元测试 (Unit Test): 运行所有单元测试，并检查测试覆盖率。
  • 规则: 以上任一阶段失败，MR 将被自动阻止合并！

• 合并后流水线: 当 MR 成功合并到 dev 或 release 分支后触发。

  • 阶段一: 构建镜像 (Build Image): （当我们采用容器化后）构建 Docker 镜像。
  • 阶段二: 推送镜像 (Push Image): 将镜像推送到镜像仓库。
  • 阶段三: 自动部署 (Deploy): 将最新的代码或镜像自动部署到对应的环境（dev -> 测试环境, release -> 预发布环境）。

通过以上协作规范，我们可以形成一个从开发、审查、测试到部署的完整、健壮、自动化的闭环。