xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 恢复分支开发模式 - AI 不切换分支,默认多AI协作,经验沉淀不标注AI身份

Browse Source
This commit is contained in:
SpecialX
2026-07-10 13:46:47 +08:00
parent f15912c7ee
commit 6051f84a65
5 changed files with 557 additions and 372 deletions
Download Patch File Download Diff File Expand all files Collapse all files

252
docs/standards/git-workflow.md
View File

@@ -1,8 +1,8 @@
# Edu Git 工作流规范
> 版本：1.2
> 版本：1.3
> 日期：2026-07-10
> 状态：基线发布（v1.2：移除分支/PR 流程，改为直接 push main）
> 状态：v1.3：恢复分支开发模式，AI 不切换分支
> 适用范围：Edu 多语言 monorepo（pnpm workspace + go.work + pyproject.toml）
> 关联文档：
>
@@ -15,7 +15,7 @@
## 目录
1. [主干开发（直接 push main）](#一主干开发直接-push-main)
1. [分支开发](#一分支开发)
2. [Conventional Commits 规范](#二conventional-commits-规范)
3. [commitlint + husky 配置](#三commitlint--husky-配置)
4. [事后 Code Review](#四事后-code-review)
@@ -27,57 +27,91 @@
---
## 一、主干开发（直接 push main）
## 一、分支开发
### 1.1 模式
本项目采用**主干开发**模式，所有变更**直接提交到 `main` 分支**。
本项目采用**分支开发**模式：**人类决策者**为每个任务/模块创建分支并分配给 AI，AI 只在当前分配的分支上工作，分支的创建、切换、合并均由人类决策者维护。
> 因 Gitea 问题，**不再使用特性分支、发布分支、hotfix 分支，不再使用 PR 流程**。所有变更通过 `git push origin main` 提交。
> **AI 不允许自行切换/创建/合并分支**。AI 禁止执行以下命令：
>
> - `git checkout -b`、`git switch`（创建/切换分支）
> - `git branch`（创建分支）
> - `git merge`（合并分支）
> - `git push origin main`（推送主干）
**核心原则**：
- `main` 分支始终保持可发布状态
- 所有变更直接 push main，**禁止 `git checkout -b` 创建任何分支**
- push 前本地通过 lint + typecheck + test + build（见 §3.4 pre-push hook）
- push 前 `git pull --rebase origin main` 同步最新
- `main` 分支始终保持可发布状态，**只有人类决策者能向 main 合并**
- 人类决策者为每个任务/模块创建分支并分配给对应 AI
- AI 只在当前分配的分支上工作，**不切换、不创建、不合并分支**
- AI 完成提交后通知人类决策者合并，**不自行 push main**
- 提交前本地通过 lint + typecheck + test + build（见 §3.4 pre-push hook）
- 通过特性开关（Feature Flag）控制未完成功能的暴露
- 代码审查改为事后追溯（见 §4），不在 push 前阻塞
- 代码审查改为事后追溯（见 §4），不在合并前阻塞
- 默认多 AI 协作，每个模块单一负责制
### 1.2 提交流程
### 1.2 AI 提交流程
AI 只在当前分配的分支上执行 `git add` → `git commit`，完成后**通知人类决策者合并**，不推送 main。
```bash
# 1. 同步最新 main
git pull --rebase origin main
# 2. 本地校验（强制）
# 1. 本地校验（强制）
pnpm run lint # TS 服务
pnpm run typecheck # TS 服务
cd services/api-gateway && go vet ./... && go build ./... # Go 服务
ruff check src/ # Python 服务
# 3. 提交（遵循 Conventional Commits，见 §2）
# 2. 提交（遵循 Conventional Commits，见 §2）
git add <files>
git commit -m "feat(<scope>): <subject>"
# 4. push 前再次同步（避免冲突）
git pull --rebase origin main
# 5. 直接 push main
git push origin main
# 3. 通知人类决策者合并
# AI 不执行 git push origin main，不创建/切换/合并分支
```
### 1.3 冲突处理
> **AI 可执行**：`git add`、`git commit`、`git status`、`git log`、`git diff`、`git pull`（仅同步当前分支）。
>
> **AI 禁止执行**：`git checkout -b`、`git switch`、`git branch`、`git merge`、`git push origin main`、`git push --force`。
- **push 被拒绝**（远端有新提交）：`git pull --rebase origin main` → 解决冲突 → `git add` → `git rebase --continue` → `git push origin main`
- **架构冲突**：由协调 AI 仲裁，通过 `git revert` + 新 commit 修正
- **禁止 `git push --force` 到 main**：仅协调 AI 在事故时可 `git push --force-with-lease origin main`
### 1.3 人类合并流程
### 1.4 main 分支保护
人类决策者负责将分支合并到 `main`，合并时机与策略由人类决策者判断。
- 禁止 force push（仅协调 AI 在事故时操作）
```bash
# 人类决策者操作（AI 不执行）
# 1. 同步最新 main
git checkout main
git pull origin main
# 2. 合并分支（由人类决策者选择策略）
git merge <branch-name> # 或 git merge --no-ff <branch-name>
# 3. 推送 main（触发 CI 部署）
git push origin main
# 4. （可选）删除已合并分支
git branch -d <branch-name>
```
**合并策略建议**：
- 一般任务：`git merge --no-ff`（保留分支拓扑，便于追溯）
- 紧急修复：`git merge --ff-only`（线性历史）
- 大特性分支：`git merge --squash`（压缩为单 commit）
### 1.4 冲突处理
- **分支合并冲突**：由人类决策者在合并分支到 main 时解决，AI 不参与合并操作
- **架构冲突**：由协调 AI 仲裁，通知人类决策者保留方案后合并，通过后续 commit 修正
- **禁止 `git push --force` 到 main**：仅协调 AI 在事故时可 `git push --force-with-lease origin main`，需人类决策者确认
### 1.5 main 分支保护
- 禁止 force push（仅协调 AI 在事故时操作，需人类决策者确认）
- pre-commit / commit-msg / pre-push hook 强制校验（见 §3.4）
- 不再要求 PR review，代码质量由本地校验 + 事后 review（§4）+ CI（project_rules §15）保证
- 不要求 PR review，代码质量由本地校验 + 事后 review（§4）+ CI（project_rules §15）保证
- **AI 无权直接 push main**，所有 main 变更须经人类决策者合并
---
@@ -268,7 +302,7 @@ module.exports = {
};
```
> **单一事实源**：实际生效的配置在仓库根 `.commitlintrc.js`，本节示例仅作说明。修改 scope 必须同步更新 `.commitlintrc.js` 与本节，并在 PR 中说明原因。
> **单一事实源**：实际生效的配置在仓库根 `.commitlintrc.js`，本节示例仅作说明。修改 scope 必须同步更新 `.commitlintrc.js` 与本节，并在提交时说明原因。
### 3.3 scope-enum 完整清单
@@ -355,27 +389,29 @@ module.exports = {
## 四、事后 Code Review
> 不再使用 PR 流程，代码审查改为**事后追溯**：变更直接 push main 后，由模块 owner 或协调 AI 通过 commit history 进行 review。问题通过后续 commit 修正或 `git revert` 回滚。
> 不再使用 PR 流程，代码审查改为**事后追溯**：AI 在分支上提交后通知人类决策者合并，人类决策者合并到 main 后由模块 owner 或协调 AI 通过分支 commit history 进行 review。问题通过后续 commit 修正或 `git revert` 回滚。
### 4.1 事后 Review 流程
```mermaid
flowchart TD
A[开发 AI 本地校验] --> B[直接 push main]
B --> C[CI 自动检查]
C --> D{CI 通过?}
D -->|否| E[git revert + 修复后重新 push]
D -->|是| F[模块 owner 事后审查 commit]
F --> G{审查通过?}
G -->|有问题| H[后续 commit 修正或 revert]
G -->|通过| I[review 完成]
A[开发 AI 本地校验] --> B[分支上 git add + git commit]
B --> C[通知人类决策者合并]
C --> D[人类决策者合并到 main]
D --> E[CI 自动检查]
E --> F{CI 通过?}
F -->|否| G[人类 git revert + 修复后重新合并]
F -->|是| H[模块 owner 事后审查分支 commit]
H --> I{审查通过?}
I -->|有问题| J[后续 commit 修正或 revert]
I -->|通过| K[review 完成]
```
**review 依据**：
- commit message（Conventional Commits 格式，见 §2）
- 分支 commit history（通过 `git log` 或平台分支/合并视图追溯）
- commit diff（通过 `git log -p` 或平台 commit 视图）
- AI 身份标注（commit body 末尾的 `AI-Agent:` 字段，见 project_rules §14.6）
### 4.2 Code Review 清单
@@ -414,14 +450,14 @@ flowchart TD
**实际生效文件**：仓库根 `.github/CODEOWNERS`。
> 不再用于自动分配 PR reviewer（无 PR 流程），CODEOWNERS 保留作为**模块归属追溯依据**：commit 涉及某路径时，对应 owner 负责事后 review。
> 不再用于自动分配 PR reviewer（无 PR 流程），CODEOWNERS 保留作为**模块归属追溯依据**：分支合并涉及某路径时，对应 owner 负责事后 review。
**设计原则**：
- 每个模块至少 1 名 owner，核心模块 2 名
- 跨模块变更（如 proto 契约、arch.db、project_rules）由架构组事后 review
- 基础设施变更（K8s/Helm/backup）由 SRE 事后 review
- owner 名单变更通过直接 commit 更新，由架构组确认
- owner 名单变更通过分支提交更新，由架构组确认后人类决策者合并
**模块 Owner 分配矩阵**：
@@ -449,7 +485,7 @@ flowchart TD
**CODEOWNERS 文件维护规则**：
1. 新增服务/包时，必须同步更新 `.github/CODEOWNERS`
2. owner 变更（人员调动）由架构组确认后直接 commit 更新
2. owner 变更（人员调动）由架构组确认后通过分支提交更新
3. CODEOWNERS 与本节表格保持同步，单一事实源为 `.github/CODEOWNERS` 文件
---
@@ -458,19 +494,19 @@ flowchart TD
### 5.1 文档同步矩阵
| 代码变更类型 | 需同步的文档 | 同步时机 |
| --------------------- | -------------------------------------------- | --------- |
| 新增/删除服务 | `001_architecture_overview.md` + 服务 README | PR 内同步 |
| 新增/删除模块 | 服务 README + `arch:scan` | PR 内同步 |
| 新增/删除导出函数 | `pnpm run arch:scan` | 提交前 |
| 修改函数签名 | `pnpm run arch:scan` | 提交前 |
| 修改权限点 | `project_rules.md` + 权限文档 | PR 内同步 |
| 新增/删除数据库表 | 架构文档 + 服务 README | PR 内同步 |
| 新增/删除路由 | 服务 README + OpenAPI | PR 内同步 |
| 修改模块间依赖 | `arch:scan` + 架构文档 | PR 内同步 |
| 新增 protobuf message | `proto/` README + `arch:scan` | PR 内同步 |
| 新增 Kafka topic | 架构文档 + 服务 README | PR 内同步 |
| 遇到新问题/经验 | `known-issues.md` | PR 内同步 |
| 代码变更类型 | 需同步的文档 | 同步时机 |
| --------------------- | -------------------------------------------- | ---------- |
| 新增/删除服务 | `001_architecture_overview.md` + 服务 README | 分支内同步 |
| 新增/删除模块 | 服务 README + `arch:scan` | 分支内同步 |
| 新增/删除导出函数 | `pnpm run arch:scan` | 提交前 |
| 修改函数签名 | `pnpm run arch:scan` | 提交前 |
| 修改权限点 | `project_rules.md` + 权限文档 | 分支内同步 |
| 新增/删除数据库表 | 架构文档 + 服务 README | 分支内同步 |
| 新增/删除路由 | 服务 README + OpenAPI | 分支内同步 |
| 修改模块间依赖 | `arch:scan` + 架构文档 | 分支内同步 |
| 新增 protobuf message | `proto/` README + `arch:scan` | 分支内同步 |
| 新增 Kafka topic | 架构文档 + 服务 README | 分支内同步 |
| 遇到新问题/经验 | `known-issues.md` | 分支内同步 |
### 5.2 arch.db 同步规则
@@ -551,6 +587,7 @@ git commit -m "feat(identity): 实现用户注册接口"
- 不写代码示例和错误示范
- 同类问题在原条目补充，不重复创建
- **不设"工作经验日志"区**：模块内经验沉淀在各自服务 README，known-issues 只保留索引式场景→技术映射（见 project_rules §9）
- **经验沉淀不标注 AI 身份**：AI 只做经验沉淀（场景→技术映射），不记录工作日志，不标注 AI 身份
---
@@ -601,7 +638,7 @@ git commit -m "build(contracts): 重新生成 proto 代码"
- 依赖升级使用 `build(deps):` 类型
- 必须说明升级原因（安全、功能、兼容性）
- 安全漏洞修复必须包含 CVE 编号
- 大版本升级需单独 PR 并完整测试
- 大版本升级需单独分支并完整测试
**示例**：
@@ -633,7 +670,7 @@ git commit -m "feat(notification): 适配 UserRegistered v2 事件"
## 七、版本管理
> 不再使用 tag 发布与 release 分支（见 project_rules §15.3 no-push 模式）。版本通过 commit SHA 追溯，发布由 push main 触发 CI 自动部署。
> 不使用 tag 发布与 release 分支（见 project_rules §15.3 no-push 模式）。版本通过 commit SHA 追溯，发布由人类决策者合并分支到 main 后触发 CI 自动部署。
### 7.1 版本号体系
@@ -671,20 +708,22 @@ git commit -m "feat(notification): 适配 UserRegistered v2 事件"
```mermaid
flowchart TD
A[开发 AI 本地校验通过] --> B[直接 push main]
B --> C[CI 自动触发 quality + deploy]
C --> D{CI 通过?}
D -->|否| E[git revert + 修复后重新 push]
E --> B
D -->|是| F[部署至目标环境]
F --> G[健康检查轮询 /healthz]
G --> H{健康?}
H -->|否| I[输出容器日志 + 紧急回滚 §8]
H -->|是| J[发布完成]
J --> K[更新 CHANGELOG.md]
A[开发 AI 本地校验通过] --> B[分支上 git add + git commit]
B --> C[通知人类决策者合并]
C --> D[人类决策者合并到 main]
D --> E[CI 自动触发 quality + deploy]
E --> F{CI 通过?}
F -->|否| G[人类 git revert + 修复后重新合并]
G --> D
F -->|是| H[部署至目标环境]
H --> I[健康检查轮询 /healthz]
I --> J{健康?}
J -->|否| K[输出容器日志 + 紧急回滚 §8]
J -->|是| L[发布完成]
L --> M[更新 CHANGELOG.md]
```
> 不再创建 release 分支、不再打 git tag。发布点通过 commit SHA 追溯，回滚通过 `git revert` 或 `workflow_dispatch` 指定 `commit_sha`（见 project_rules §15.4）。
> 不创建 release 分支、不打 git tag。发布点通过 commit SHA 追溯，回滚通过 `git revert` 或 `workflow_dispatch` 指定 `commit_sha`（见 project_rules §15.4）。
### 7.5 CHANGELOG 格式
@@ -735,32 +774,36 @@ flowchart TD
### 8.1 回滚策略
| 场景 | 回滚方式 | 耗时 |
| -------------- | ----------------------------------------- | ---------- |
| 代码缺陷 | `git revert` + push main 触发 CI 重新部署 | 5-10 分钟 |
| 镜像问题 | `kubectl rollout undo` | 1-2 分钟 |
| 数据库迁移问题 | 执行迁移 down 脚本 | 5-30 分钟 |
| 配置错误 | 回滚 ConfigMap/Secret | 1-2 分钟 |
| 全站故障 | `workflow_dispatch` 指定稳定 `commit_sha` | 10-30 分钟 |
| 场景 | 回滚方式 | 耗时 |
| -------------- | --------------------------------------------------- | ---------- |
| 代码缺陷 | 人类在 main 上 `git revert` + push 触发 CI 重新部署 | 5-10 分钟 |
| 镜像问题 | `kubectl rollout undo` | 1-2 分钟 |
| 数据库迁移问题 | 执行迁移 down 脚本 | 5-30 分钟 |
| 配置错误 | 回滚 ConfigMap/Secret | 1-2 分钟 |
| 全站故障 | `workflow_dispatch` 指定稳定 `commit_sha` | 10-30 分钟 |
### 8.2 代码回滚
> 不再创建 hotfix 分支。直接在 main 上 `git revert` 后 push，CI 自动重新部署。
> 不创建 hotfix 分支。**由人类决策者在 main 上 `git revert` 后 push**，CI 自动重新部署。AI 不参与 main 上的回滚推送操作。
```bash
# 人类决策者操作（AI 不执行 push main）
# 1. 确认要回滚的 commit
git log --oneline -10
# 2. 拉取最新 main
git pull --rebase origin main
# 2. 切换到 main 并拉取最新
git checkout main
git pull origin main
# 3. 回滚指定 commit（生成反向 commit）
git revert <commit-sha>
# 4. 直接 push main（CI 自动触发重新部署）
# 4. push main（CI 自动触发重新部署）
git push origin main
```
> 修复型回滚也可通过新分支提交修复后由人类决策者合并，具体方式由人类决策者判断。
### 8.3 K8s 部署回滚
```bash
@@ -843,31 +886,32 @@ pnpm --filter identity run migrate:down -- --to <version>
## 九、附录：CICD 与 Edu Git 工作流差异
| 维度 | CICD（Next.js 单应用） | Edu（微服务 monorepo） |
| --------------------- | -------------------------------- | ----------------------------------------------------------------- |
| 仓库结构 | 单一 Next.js 应用 | 多语言 monorepo（pnpm + go.work + uv） |
| 分支策略 | trunk-based | trunk-based，**直接 push main，无分支无 PR** |
| 提交规范 | Conventional Commits | Conventional Commits（沿用，scope 扩展至服务/包） |
| scope 范围 | 模块名（如 `exams`、`homework`） | 服务/包名（如 `iam`、`api-gateway`、`shared-proto`） |
| commitlint scope-enum | 35 个模块 | 26 个 scope（含服务/包/工具/平台级，与 `.commitlintrc.js` 同步） |
| 代码审查 | PR Reviewer 1 人 | **事后 review**（无 PR，通过 commit history 追溯） |
| 合并策略 | Squash Merge | **直接 push main**（无合并操作） |
| 版本号 | 单一应用版本 | 双层（平台版本 + 服务独立版本，仅记录不打 tag） |
| 发布粒度 | 整体发布 | 按服务独立发布 |
| Docker 镜像 | 单一镜像 | 每服务一镜像（no-push 本地构建，见 project_rules §15） |
| 回滚粒度 | 整体回滚 | 按服务回滚 |
| 数据库迁移 | Drizzle 单库 | 每服务独立库 + 独立迁移 |
| 文档同步 | `npm run arch:scan` | `pnpm run arch:scan`（多语言扫描） |
| CI 检查 | lint + tsc + test | lint + typecheck + test（按语言分别执行） |
| 紧急回滚 | `git revert` + 重新部署 | `git revert` + push main 触发 CI，或 `workflow_dispatch` 指定 SHA |
| 事故复盘 | known-issues.md | `incidents/` 目录独立记录 |
| 维度 | CICD（Next.js 单应用） | Edu（微服务 monorepo） |
| --------------------- | -------------------------------- | --------------------------------------------------------------------------- |
| 仓库结构 | 单一 Next.js 应用 | 多语言 monorepo（pnpm + go.work + uv） |
| 分支策略 | trunk-based | **分支开发，AI 不切换分支，人类维护** |
| 提交规范 | Conventional Commits | Conventional Commits（沿用，scope 扩展至服务/包） |
| scope 范围 | 模块名（如 `exams`、`homework`） | 服务/包名（如 `iam`、`api-gateway`、`shared-proto`） |
| commitlint scope-enum | 35 个模块 | 26 个 scope（含服务/包/工具/平台级，与 `.commitlintrc.js` 同步） |
| 代码审查 | PR Reviewer 1 人 | **事后 review**（无 PR，通过分支 commit history 追溯） |
| 合并策略 | Squash Merge | **人类决策者手动合并分支到 main**（AI 不合并） |
| 版本号 | 单一应用版本 | 双层（平台版本 + 服务独立版本，仅记录不打 tag） |
| 发布粒度 | 整体发布 | 按服务独立发布 |
| Docker 镜像 | 单一镜像 | 每服务一镜像（no-push 本地构建，见 project_rules §15） |
| 回滚粒度 | 整体回滚 | 按服务回滚 |
| 数据库迁移 | Drizzle 单库 | 每服务独立库 + 独立迁移 |
| 文档同步 | `npm run arch:scan` | `pnpm run arch:scan`（多语言扫描） |
| CI 检查 | lint + tsc + test | lint + typecheck + test（按语言分别执行） |
| 紧急回滚 | `git revert` + 重新部署 | 人类在 main 上 `git revert` + push 触发 CI，或 `workflow_dispatch` 指定 SHA |
| 事故复盘 | known-issues.md | `incidents/` 目录独立记录 |
---
## 变更记录
| 版本 | 日期 | 变更内容 |
| ---- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1.0 | 2026-07-07 | 基线发布，从 CICD 单应用规范迁移至微服务多语言 monorepo |
| 1.1 | 2026-07-08 | scope-enum 对齐实际服务名（identity→iam、teaching→core-edu 等）；新增 §4.7 模块 Owner 与 CODEOWNERS；husky hooks 与实际文件对齐；新增 pre-push hook 说明 |
| 1.2 | 2026-07-10 | 因 Gitea 问题移除分支/PR 流程：§1 改为直接 push main（移除特性/发布/hotfix 分支命名与保护）；§4 改为事后 Code Review（移除 PR 流程/标题/模板/合并策略，保留 Code Review 清单与 CODEOWNERS 追溯）；§7 改为版本管理（移除 release 分支与 tag 发布，用 commit SHA 追溯）；§8 移除 hotfix 分支回滚，改为直接 git revert + push main；§9 更新差异表 |
| 版本 | 日期 | 变更内容 |
| ---- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1.0 | 2026-07-07 | 基线发布，从 CICD 单应用规范迁移至微服务多语言 monorepo |
| 1.1 | 2026-07-08 | scope-enum 对齐实际服务名（identity→iam、teaching→core-edu 等）；新增 §4.7 模块 Owner 与 CODEOWNERS；husky hooks 与实际文件对齐；新增 pre-push hook 说明 |
| 1.2 | 2026-07-10 | 因 Gitea 问题移除分支/PR 流程：§1 改为直接 push main（移除特性/发布/hotfix 分支命名与保护）；§4 改为事后 Code Review（移除 PR 流程/标题/模板/合并策略，保留 Code Review 清单与 CODEOWNERS 追溯）；§7 改为版本管理（移除 release 分支与 tag 发布，用 commit SHA 追溯）；§8 移除 hotfix 分支回滚，改为直接 git revert + push main；§9 更新差异表 |
| 1.3 | 2026-07-10 | 恢复分支开发模式（AI 不切换分支）：§1 改为分支开发（人类决策者维护分支，AI 禁止 `git checkout -b`/`git switch`/`git branch`/`git merge`/`git push origin main`，AI 只做 `git add`→`git commit`→通知人类合并）；§4 review 依据改为分支 commit history，移除 AI 身份标注；§8 回滚由人类在 main 上 `git revert`，不使用 hotfix 分支；§9 分支策略改为"分支开发，AI 不切换分支，人类维护"；§5.4 经验沉淀不标注 AI 身份 |