初始化文档

05 - Collaboration & Delivery/5.1 版本控制与代码提交规范.md

@@ -0,0 +1,106 @@
+# **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 那天才去处理几千行的灾难性冲突。

05 - Collaboration & Delivery/5.2 CI_CD 与环境部署规范.md

@@ -0,0 +1,85 @@
+# **5.2 CI/CD 与环境部署规范**
+
+持续集成与持续部署（CI/CD）是连接代码与生产环境的高速公路。我们追求的目标是：**一次构建，随处运行；一切即代码（Pipeline as Code）；消除环境差异带来的人为故障。**
+
+团队统一采用 **Jenkins** 作为核心的 CI/CD 引擎。
+
+### **5.2.1 多环境定义与资源流转 (Environments)**
+
+系统从开发到上线，必须经历严格的环境隔离与流转。严禁跨环境调用（如 Dev 环境连接 Prod 数据库）。
+
+* **1\. Local (本地开发环境)**  
+  * **使用者**：开发人员。  
+  * **形态**：研发个人的笔记本电脑，依赖的数据库、Redis 推荐通过本地 Docker Compose 快速拉起。  
+  * **目的**：日常编码、单步调试、执行本地单元测试。  
+* **2\. Dev (开发集成环境)**  
+  * **对应分支**：dev (或 develop)  
+  * **使用者**：开发人员、前端/客户端联调人员。  
+  * **形态**：自动拉取 dev 分支最新代码部署。允许存在一定的不稳定性，日志级别通常设为 DEBUG。  
+  * **目的**：验证微服务间的连通性、前后端接口联调。  
+* **3\. Test (系统测试环境)**  
+  * **对应分支**：test (或 release)  
+  * **使用者**：QA 测试工程师。  
+  * **形态**：由专门的合并操作触发部署。数据库通常会定期从线上脱敏同步部分数据以模拟真实场景。  
+  * **目的**：功能验收测试、自动化接口回归测试、性能压测基准测试。  
+* **4\. UAT (用户验收测试 / 预发环境)**  
+  * **对应分支**：main (打 Tag 前的最终验证)  
+  * **使用者**：产品经理、业务方验收人员。  
+  * **形态**：**基础架构、配置规格必须与 Prod 生产环境 100% 保持一致**。甚至可以连接生产环境的只读库或独立的预发库。  
+  * **目的**：上线前的最后一次演练，验证部署脚本本身是否正确，业务逻辑是否符合预期。  
+* **5\. Prod (生产环境)**  
+  * **对应分支**：main (基于发布 Tag，如 v1.2.0)  
+  * **使用者**：真实的外部用户。  
+  * **形态**：极度稳定、高可用、严控权限。  
+  * **目的**：承载真实业务。
+
+### **5.2.2 配置隔离与凭证安全**
+
+为了实现“同一份代码（或镜像）在不同环境无缝切换”，必须做到代码与配置的彻底分离。
+
+* **配置文件解耦**：  
+  * 遵循《3.2 框架实施规范》，代码中必须拆分不同环境的配置文件（如 settings/dev.py, settings/prod.py）。  
+  * 运行时通过环境变量（如 export APP\_ENV=prod）来决定加载哪份配置。  
+* **密码与密钥红线 (Secret Management)**：  
+  * **绝对禁止**将数据库密码、API 秘钥、云服务 AccessKey 写死在代码库（包括 .env 文件也不允许提交到 Git）。  
+  * Jenkins 注入：在 CI/CD 阶段，通过 Jenkins 的凭据管理（Credentials Binding）或 HashiCorp Vault、云厂商配置中心（如 Nacos/Apollo）在容器启动时动态注入环境变量。
+
+### **5.2.3 持续集成流水线规范 (Jenkins Pipeline)**
+
+**核心理念：Pipeline as Code (流水线即代码)。**
+
+* **严禁手动配置 Job**：禁止在 Jenkins UI 页面上手工拼凑 Shell 脚本构建步骤。  
+* **强制使用 Jenkinsfile**：  
+  * 每个代码仓库的根目录必须包含一个使用声明式语法（Declarative Pipeline）编写的 Jenkinsfile。  
+  * 流水线的版本控制与业务代码同源，谁修改了部署逻辑，Git 历史一目了然。
+
+**标准 Jenkinsfile 阶段 (Stages) 划分：**
+
+1. Checkout：拉取代码。  
+2. Quality Gate (Linter & Test)：执行静态代码扫描（Ruff/ESLint）和单元测试（Pytest）。**失败则立刻中断流水线**。  
+3. SonarQube Analysis：进行代码异味、漏洞分析。  
+4. Build & Push：将应用打包并构建为 Docker 镜像，打上与 Git Commit ID 绑定的 Tag，推送到镜像仓库（Harbor/阿里云 ACR）。  
+5. Deploy to XXX：触发 Kubernetes (K8s) 或目标服务器拉取新镜像并滚动更新。
+
+### **5.2.4 流水线触发规则与门禁策略 (Trigger Rules)**
+
+为了平衡开发效率与质量控制，Jenkins 流水线必须配合 Webhook 实现自动化触发，并设置严格的卡点（Quality Gates）：
+
+#### **1\. PR/MR 提交阶段 (Merge Request to Dev/Main)**
+
+* **触发方式**：开发人员在 Gitlab/Github 提交 Pull Request。  
+* **执行流水线**：仅执行 Lint \-\> Unit Test \-\> Sonar。**不进行部署**。  
+* **门禁规则**：如果 Jenkins 反馈测试失败、覆盖率低于 80% 或存在高危漏洞，代码托管平台必须**锁定合并按钮（Block Merge）**，强迫开发者修复。
+
+#### **2\. 代码合并阶段 (Push to Dev/Test)**
+
+* **触发方式**：PR 合并到 dev 或 test 分支。  
+* **执行流水线**：完整走完上述五个 Stage，最终自动部署到对应的 Dev 或 Test 服务器。  
+* **验证测试**：部署完成后，流水线应触发自动化接口测试（API E2E Tests），一旦测试不通过，立即发送飞书/钉钉告警通知团队。
+
+#### **3\. 生产发布阶段 (Deploy to Prod)**
+
+* **触发方式**：在 main 分支打上符合 SemVer 规范的 Tag（如 v2.1.0）。  
+* **门禁规则 (人工卡点)**：  
+  * 生产环境的部署**绝对禁止全自动触发**。  
+  * 在 Jenkins 流水线的 Deploy to Prod 阶段前，必须设置一个 input() 审批节点。只有具备 Release 权限的运维工程师或技术 TL 在 Jenkins 界面点击“同意确认”后，才会真正触发生产环境的镜像替换。