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

docs(docs): 新增本地启动/多AI协作/CI-CD 使用手册

Browse Source 
- local-dev-runbook.md: 8 章本地启动手册（环境依赖/端口分配/开发模式/生产模式/裸机运行/常见问题）

- multi-ai-collaboration.md: 15 章多AI协作文档（角色定义/模块分工/分支策略/PR流程/审核合并/跨模块变更）

- cicd-runbook.md: 10 章 CI/CD 使用手册（架构总览/一次性配置/日常使用/镜像管理/部署验证/回滚）

- README.md: 文档清单新增三个 runbook 链接
This commit is contained in:
SpecialX
2026-07-08 15:14:30 +08:00
parent 3b88e9cca5
commit d19285a977
4 changed files with 1516 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
README.md
View File

@@ -38,6 +38,9 @@ pnpm dev
- [编码规范](docs/standards/coding-standards.md)
- [UI 设计系统](docs/standards/ui-design-system.md)
- [Git 工作流](docs/standards/git-workflow.md)
- [本地启动手册](docs/standards/local-dev-runbook.md)
- [多 AI 协作指南](docs/standards/multi-ai-collaboration.md)
- [CI/CD 使用手册](docs/standards/cicd-runbook.md)
- [已知问题](docs/troubleshooting/known-issues.md)
- [项目规则](.trae/rules/project_rules.md)
- [迁移指南](MIGRATION_GUIDE.md)

445
docs/standards/cicd-runbook.md Normal file
View File

@@ -0,0 +1,445 @@
# CI/CD 使用手册（CI/CD Runbook）
> 版本：1.0
> 日期：2026-07-08
> 适用范围：Edu 微服务项目（Gitea Actions + Gitea Container Registry + Runner 直接部署）
> 关联文档：[project_rules §15](../../.trae/rules/project_rules.md)、[本地启动手册](./local-dev-runbook.md)、[多 AI 协作指南](./multi-ai-collaboration.md)
---
## 1. 架构总览
```
开发 AI 推送 PR 协调 AI 合并到 main
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ ci-*.yml │ │ docker.yml │
│ lint+test+ │ │ build+push │
│ build+scan │ │ 镜像到 Gitea│
└─────────────┘ │ Registry │
└──────┬──────┘
│
▼
┌─────────────┐
│ deploy.yml │
│ Runner 直接 │
│ docker │
│ compose up │
└─────────────┘
```
### 1.1 组件清单
| 组件 | 说明 |
| ---------------------------- | --------------------------------------------------------------- |
| **Gitea** | `git.eazygame.cn`，代码托管 + Actions + Container Registry |
| **Gitea Actions** | CI 运行器，兼容 GitHub Actions 语法 |
| **Gitea Container Registry** | 镜像仓库，地址 `git.eazygame.cn/xiner/edu/<service>:<tag>` |
| **Deploy Runner** | 跑在服务器上的 self-hosted runner，标签 `[self-hosted, deploy]` |
| **服务器 MySQL** | 已有容器，端口 3306，容器名 `edu-mysql`（假设） |
| **服务器 Redis** | 已有容器，端口 6379，容器名 `edu-redis`（假设） |
### 1.2 流水线文件
| 文件 | 触发 | 作用 |
| -------------------------------- | ------------------------ | ---------------------------------------------------------- |
| `.github/workflows/ci-ts.yml` | TS 路径变更 | lint + typecheck + test + build + arch:scan + docker-build |
| `.github/workflows/ci-go.yml` | Go 路径变更 | vet + build + test + docker-build |
| `.github/workflows/ci-py.yml` | Python 路径变更 | ruff + pytest（P4 阶段） |
| `.github/workflows/ci-proto.yml` | proto 变更 | buf lint + buf breaking |
| `.github/workflows/docker.yml` | push main / tag `v*` | 构建并推送镜像到 Gitea Registry |
| `.github/workflows/deploy.yml` | docker.yml 完成后 / 手动 | Runner 执行 docker compose up |
---
## 2. 一次性配置（SRE AI 或人类执行）
### 2.1 启用 Gitea Actions
在 Gitea 仓库 `xiner/Edu` 设置：
1. **仓库设置 → Actions → 启用**
2. 安装 actrunner（若未安装）：
```bash
# 在服务器上
wget https://gitea.com/gitea/act_runner/raw/branch/main/act_runner
chmod +x act_runner
./act_runner register --instance https://git.eazygame.cn --token <TOKEN>
```
3. 配置 runner 标签为 `self-hosted,deploy`（部署用）和 `self-hosted,linux`（CI 用）
### 2.2 启用 Gitea Container Registry
Gitea 1.20+ 自带 Container Registry，无需额外启用。确认：
```bash
# 测试登录
docker login git.eazygame.cn -u <你的用户名>
# 输入密码或 token
```
### 2.3 准备服务器网络
确保 MySQL/Redis 容器与应用容器在同一 Docker 网络：
```bash
# 创建共享网络（若不存在）
docker network create edu-shared
# 将已有的 MySQL/Redis 加入网络（容器名按实际替换）
docker network connect edu-shared edu-mysql # 或实际容器名
docker network connect edu-shared edu-redis # 或实际容器名
```
> 查看实际容器名：`docker ps --format "{{.Names}}" | grep -E "mysql|redis"`
### 2.4 初始化部署目录
```bash
# 1. 创建部署目录
sudo mkdir -p /opt/edu
sudo chown -R $USER:$USER /opt/edu
# 2. 拷贝 compose 文件
cd /path/to/Edu
cp infra/docker-compose.deploy.yml /opt/edu/docker-compose.yml
# 3. 创建生产 .env（从模板）
cp infra/deploy.env.example /opt/edu/.env
vim /opt/edu/.env
# 必须修改：
# JWT_SECRET=<openssl rand -hex 32 生成的随机值>
# DATABASE_URL=mysql://<user>:<pass>@<mysql容器名>:3306/<db>
# REDIS_URL=redis://<redis容器名>:6379
# 4. 登录 Gitea Container Registry（Runner 用户）
docker login git.eazygame.cn -u <user> -p <token>
# token 在 Gitea → 设置 → 应用 → 生成新 token
```
### 2.5 配置 Gitea Secrets
在 Gitea 仓库 → 设置 → Actions → Secrets，添加：
| Secret 名 | 用途 | 必填 |
| ---------------------- | -------------------------------- | ---- |
| `GITHUB_TOKEN` | Gitea 自动注入，推送镜像用 | 自动 |
| `GITEA_REGISTRY_USER` | deploy.yml 登录 registry（可选） | 否 |
| `GITEA_REGISTRY_TOKEN` | deploy.yml 登录 registry（可选） | 否 |
> `GITHUB_TOKEN` 由 Gitea Actions 自动注入，无需手动配置。`docker.yml` 用它推送镜像。
> `deploy.yml` 中 Runner 已在服务器上，若已 `docker login` 过则无需 secrets。
---
## 3. 日常使用
### 3.1 开发 AI 提 PR
开发 AI 推送特性分支后创建 PR，自动触发 CI：
```
PR 创建 → ci-ts.yml / ci-go.yml 运行
├─ quality（lint + typecheck + test + build）
├─ arch-scan（架构扫描）
└─ docker-build（构建不推送）
CI 全绿 → 协调 AI 审核合并
```
### 3.2 协调 AI 合并 PR
PR 合并到 main 后，自动触发：
```
push main →
├─ ci-*.yml（确保 main 稳定）
└─ docker.yml → 构建并推送镜像到 git.eazygame.cn/xiner/edu/<service>:latest
│
▼
deploy.yml → Runner 执行 docker compose pull && up -d
│
▼
健康检查（轮询 /healthz）
```
### 3.3 手动部署
在 Gitea → Actions → Deploy → Run workflow：
| 参数 | 说明 |
| ----------- | --------------------------------------- |
| `image_tag` | 部署指定 tag（默认 `latest`） |
| `rollback` | 勾选则跳过 pull，用本地已有镜像重新启动 |
### 3.4 发布正式版本（tag）
```bash
git tag -a v1.0.0 -m "P1 阶段首次发布"
git push origin v1.0.0
```
触发 `docker.yml` 推送 `v1.0.0` tag 镜像，再手动触发 deploy.yml 部署 `v1.0.0`。
---
## 4. 镜像管理
### 4.1 镜像地址
```
git.eazygame.cn/xiner/edu/<service>:<tag>
```
| service | 说明 |
| ---------------- | --------------- |
| `api-gateway` | Go 网关 |
| `classes` | NestJS 班级服务 |
| `teacher-portal` | Next.js 前端 |
### 4.2 Tag 策略
| tag | 来源 | 用途 |
| ------------------ | ----------------- | ---------- |
| `latest` | main 分支最新构建 | 默认部署 |
| `main-<sha>` | main 分支每次构建 | 可追溯 |
| `v<version>` | 打 `v*` tag 触发 | 正式版本 |
| `v<major>.<minor>` | 打 `v*` tag 触发 | 大版本追踪 |
### 4.3 查看与清理镜像
在 Gitea → 用户设置 → Packages，可查看与管理所有镜像。
清理旧 tag（手动）：
```bash
# 列出所有 tag
docker images git.eazygame.cn/xiner/edu/classes --format "{{.Tag}}"
# 删除本地旧镜像
docker rmi git.eazygame.cn/xiner/edu/classes:main-abc1234
```
---
## 5. 部署验证
### 5.1 CI 自动验证
`deploy.yml` 部署后会自动轮询健康检查（最多 10 次，每次间隔 6 秒）：
- `http://localhost:8080/healthz` — api-gateway
- `http://localhost:3001/healthz` — classes
- `http://localhost:3000/` — teacher-portal
失败时输出容器日志，方便排查。
### 5.2 手动验证
```bash
# SSH 到服务器后
cd /opt/edu
# 容器状态
docker compose ps
# 健康检查
curl http://localhost:8080/healthz # api-gateway
curl http://localhost:3001/healthz # classes
curl http://localhost:3000/ # teacher-portal
# 鉴权验证（生产模式 dev-token 应被拒绝）
curl -H "Authorization: Bearer dev-token" http://localhost:8080/api/v1/classes
# 预期：401 INVALID_TOKEN
# 查看日志
docker compose logs -f api-gateway
docker compose logs -f classes
docker compose logs -f teacher-portal
```
### 5.3 外部访问
若服务器有公网 IP（如 `1.2.3.4`）：
- 前端：`http://1.2.3.4:3000`
- API 网关：`http://1.2.3.4:8080`
- 健康检查：`http://1.2.3.4:8080/healthz`
---
## 6. 回滚
### 6.1 CI 回滚（推荐）
在 Gitea → Actions → Deploy → Run workflow：
- `image_tag`：填入上一个稳定版本的 tag（如 `main-abc1234`）
- `rollback`：勾选（跳过 pull，用本地已有镜像）
### 6.2 手动回滚
```bash
cd /opt/edu
# 查看本地镜像
docker images git.eazygame.cn/xiner/edu/classes --format "{{.Tag}}"
# 回滚到指定版本
IMAGE_TAG=main-abc1234 docker compose up -d
```
### 6.3 紧急回滚（Git revert）
若代码有问题：
```bash
git revert <bad-commit>
git push origin main
# CI 自动重新构建部署
```
---
## 7. 常见问题
### 7.1 CI: pnpm install 失败
**症状**：`pnpm install --frozen-lockfile` 报错。
**排查**：
1. `pnpm-lock.yaml` 未提交：`git add pnpm-lock.yaml && git commit -m "chore(deps): 更新 lockfile"`
2. Node 版本不匹配：确认 CI 用 Node 20，本地一致
### 7.2 CI: docker-build 失败
**症状**：`docker/build-push-action` 报错。
**排查**：
1. Dockerfile 语法错误：本地 `docker build` 验证
2. 路径错误：确认 `context` 与 `file` 参数
### 7.3 CD: 镜像拉取失败
**症状**：`docker compose pull` 报 `unauthorized`。
**修复**：
```bash
# 服务器上重新登录
docker login git.eazygame.cn -u <user> -p <token>
# 或配置 Gitea secrets GITEA_REGISTRY_USER / GITEA_REGISTRY_TOKEN
```
### 7.4 CD: 健康检查失败
**症状**：`deploy.yml` 健康检查 10 次后失败。
**排查**：
1. 查看日志：`cd /opt/edu && docker compose logs api-gateway`
2. 常见原因：
- `DATABASE_URL` 连不上 MySQL（检查容器名与网络）
- `JWT_SECRET` 未配置
- 端口被占用：`docker ps` 检查冲突
### 7.5 CD: 连不上 MySQL/Redis
**症状**：classes 容器报 `ECONNREFUSED edu-mysql:3306`。
**修复**：
```bash
# 1. 确认 MySQL 容器名
docker ps --format "{{.Names}}" | grep mysql
# 2. 确认 MySQL 在 edu-shared 网络
docker network inspect edu-shared | grep -A5 Containers
# 3. 若不在，加入网络
docker network connect edu-shared <实际mysql容器名>
# 4. 修改 /opt/edu/.env 的 DATABASE_URL
# DATABASE_URL=mysql://edu:changeme@<实际容器名>:3306/next_edu_cloud
```
### 7.6 Gitea Actions 未触发
**症状**：push 后 Actions 不运行。
**排查**：
1. 仓库设置 → Actions → 确认已启用
2. Runner 在线：Gitea → 设置 → Actions → Runners
3. workflow 文件在 `.github/workflows/` 目录（非 `.gitea/workflows/`）
4. `on:` 触发条件匹配（paths 过滤）
### 7.7 workflow_run 不触发
**症状**：`docker.yml` 完成后 `deploy.yml` 不自动运行。
**原因**：Gitea Actions 对 `workflow_run` 触发支持可能不完整。
**解决**：
- 改用手动触发：Actions → Deploy → Run workflow
- 或在 `docker.yml` 末尾加 job 调用 deploy（需要 `workflow_call`）
---
## 8. 排查命令速查
```bash
# === 在服务器上 ===
# 查看所有 edu 容器
docker compose -f /opt/edu/docker-compose.yml ps
# 查看实时日志
docker compose -f /opt/edu/docker-compose.yml logs -f
# 重启单个服务
docker compose -f /opt/edu/docker-compose.yml restart api-gateway
# 进入容器
docker exec -it edu-api-gateway sh
docker exec -it edu-classes sh
# 查看网络
docker network inspect edu-shared
# 查看镜像列表
docker images git.eazygame.cn/xiner/edu
# === 在 Gitea Web UI ===
# 仓库 → Actions → 查看流水线运行记录
# 用户设置 → Packages → 管理镜像
# 仓库 → 设置 → Secrets → 管理 CI 密钥
# 仓库 → 设置 → Actions → Runners → 查看 Runner 状态
```
---
## 9. 安全注意事项
1. **`.env` 文件不入库**：`.gitignore` 已忽略，仅存在于服务器 `/opt/edu/.env`
2. **JWT_SECRET 强随机**：生产必须用 `openssl rand -hex 32` 生成
3. **DEV_MODE=false**：docker-compose.deploy.yml 强制设为 `false`
4. **Gitea Token 权限最小化**：仅给 `package:write` 和 `contents:read`
5. **Runner 隔离**：deploy runner 仅跑在目标服务器，不暴露公网 SSH
6. **镜像扫描**（P6）：`docker.yml` 后续加 Trivy 扫描步骤
---
## 10. 相关文档
- [project_rules §15 CI/CD 规范](../../.trae/rules/project_rules.md)
- [project_rules §14 多 AI 协作规范](../../.trae/rules/project_rules.md)
- [本地启动手册](./local-dev-runbook.md)
- [多 AI 协作指南](./multi-ai-collaboration.md)
- [Git 工作流](./git-workflow.md)
- [known-issues](../troubleshooting/known-issues.md)

333
docs/standards/local-dev-runbook.md Normal file
View File

@@ -0,0 +1,333 @@
# 本地启动手册（Local Dev Runbook）
> 版本：1.0
> 日期：2026-07-08
> 适用范围：Edu 微服务（P1 阶段：api-gateway + classes + teacher-portal）
> 关联文档：[project_rules](../../.trae/rules/project_rules.md)、[004 架构影响地图](../architecture/004_architecture_impact_map.md)、[known-issues](../troubleshooting/known-issues.md)
---
## 1. 环境依赖
| 工具 | 版本要求 | 验证命令 | 说明 |
| -------------- | -------- | ------------------------ | -------------------------- |
| Node.js | ≥ 20 | `node -v` | LTS 版本 |
| pnpm | ≥ 9 | `pnpm -v` | `corepack enable` 自动启用 |
| Go | 1.22+ | `go version` | api-gateway 编译 |
| Docker | 24+ | `docker version` | 基础设施容器化 |
| Docker Compose | v2+ | `docker compose version` | 编排基础设施 |
| Git | 2.30+ | `git --version` | husky hooks 需要 |
> Windows 用户：建议在 PowerShell 或 Git Bash 中执行。Go 工具链若不在 PATH，临时加入：`$env:Path = "C:\Program Files\Go\bin;" + $env:Path`
---
## 2. 服务端口分配
| 服务 | 端口 | 语言/框架 | 启动方式 | 健康检查 |
| -------------- | ---- | ------------ | ------------------- | ----------------- |
| MySQL | 3306 | Docker | `docker compose up` | `mysqladmin ping` |
| Redis | 6379 | Docker | `docker compose up` | `redis-cli ping` |
| api-gateway | 8080 | Go (Gin) | `go run main.go` | `GET /healthz` |
| classes | 3001 | NestJS (TS) | `pnpm dev` | `GET /healthz` |
| teacher-portal | 3000 | Next.js (TS) | `pnpm dev` | `GET /` |
| iam | 3002 | NestJS | P2 阶段 | — |
| teacher-bff | 3003 | NestJS | P2 阶段 | — |
> 端口冲突排查：`netstat -ano \| findstr :8080`（Windows）
---
## 3. 本地开发模式（DEV_MODE）
### 3.1 首次准备
```bash
# 1. 克隆仓库
git clone <repo-url> Edu
cd Edu
# 2. 安装依赖
pnpm install
# 3. 配置环境变量
cp .env.example .env
# 编辑 .env，确认：
# DEV_MODE=true ← 本地联调用
# JWT_SECRET=p1-dev-secret-change-in-production
# DATABASE_URL=mysql://edu:changeme@localhost:3306/next_edu_cloud
# REDIS_URL=redis://localhost:6379
# 4. 架构扫描（更新 arch.db）
pnpm run arch:scan
```
### 3.2 启动基础设施
```bash
# 启动 MySQL + Redis（最小基础设施）
docker compose -f infra/docker-compose.minimal.yml up -d
# 验证健康
docker compose -f infra/docker-compose.minimal.yml ps
# 状态应为 healthy
# （可选）国内镜像源加速：infra/docker-compose.minimal.override.yml 已配置 daocloud 镜像
```
### 3.3 启动应用服务（三个终端）
#### 终端 1：api-gateway（:8080）
```bash
cd services/api-gateway
# Windows：若 Go 不在 PATH，先设置
$env:Path = "C:\Program Files\Go\bin;" + $env:Path
# 设置开发模式环境变量
$env:DEV_MODE="true"
$env:JWT_SECRET="p1-dev-secret-change-in-production"
# 启动
go run main.go
```
验证：`curl http://localhost:8080/healthz` → 200 OK
#### 终端 2：classes 服务（:3001）
```bash
# 在项目根目录
pnpm --filter @edu/classes-service dev
```
验证：`curl http://localhost:3001/healthz` → 200 OK
> 注：classes 的 HealthModule 需注册到 AppModule，当前若返回 404 见 [known-issues]
#### 终端 3：teacher-portal（:3000）
```bash
# 在项目根目录
pnpm --filter @edu/teacher-portal dev
```
验证：浏览器访问 `http://localhost:3000` → 班级管理页面
### 3.4 一键启动（可选）
```bash
# 并行启动所有子包的 dev 脚本（含 api-gateway 需 go run，不会自动启动）
pnpm dev
```
> 注：`pnpm dev` 仅启动 pnpm workspace 内的 TS 服务。api-gateway 是 Go 服务，需单独 `go run`。
### 3.5 联调验证
```bash
# 1. 直接访问 api-gateway（带 dev-token）
curl -H "Authorization: Bearer dev-token" http://localhost:8080/api/v1/classes
# 预期：200 OK + 班级列表 JSON
# 2. 通过 teacher-portal 代理访问
curl -H "Authorization: Bearer dev-token" http://localhost:3000/api/v1/classes
# 预期：200 OK（经 Next.js rewrites → api-gateway → classes）
# 3. 浏览器访问
# http://localhost:3000 → 班级管理页面，自动加载班级列表
```
### 3.6 dev-token 说明
- `DEV_MODE=true` 时，api-gateway 接受 `Authorization: Bearer dev-token`
- 注入固定身份：`x-user-id: dev-user`，`x-user-roles: teacher,admin`
- **仅限本地联调，生产环境必须 `DEV_MODE=false`**
---
## 4. 生产模式（Docker Compose）
### 4.1 构建镜像
```bash
# 构建三个应用服务镜像
docker compose -f infra/docker-compose.prod.yml build
```
### 4.2 启动完整栈
```bash
# 1. 先启动基础设施（MySQL + Redis）
docker compose -f infra/docker-compose.minimal.yml up -d
# 2. 启动应用服务
docker compose -f infra/docker-compose.prod.yml up -d
# 3. 查看状态
docker compose -f infra/docker-compose.prod.yml ps
# 所有服务应为 healthy
# 4. 查看日志
docker compose -f infra/docker-compose.prod.yml logs -f api-gateway
```
### 4.3 生产环境配置要点
| 配置项 | 生产值 | 说明 |
| -------------- | ---------------- | ----------------------------------------------- |
| `DEV_MODE` | `false` | docker-compose.prod.yml 强制设为 false |
| `JWT_SECRET` | 强随机值 | 替换 `p1-dev-secret-change-in-production` |
| `DATABASE_URL` | 生产数据库连接 | 容器内用 `host.docker.internal` 或 compose 网络 |
| `NODE_ENV` | `production` | teacher-portal 启用生产优化 |
| `LOG_LEVEL` | `info` 或 `warn` | 生产日志级别 |
### 4.4 生产验证
```bash
# 健康检查
curl http://localhost:8080/healthz # api-gateway
curl http://localhost:3001/healthz # classes
curl http://localhost:3000/ # teacher-portal
# 鉴权验证（生产模式 dev-token 应被拒绝）
curl -H "Authorization: Bearer dev-token" http://localhost:8080/api/v1/classes
# 预期：401 INVALID_TOKEN
# 真实 JWT 访问（需 IAM 签发）
curl -H "Authorization: Bearer <real-jwt>" http://localhost:8080/api/v1/classes
# 预期：200 OK
```
### 4.5 停止与清理
```bash
# 停止应用服务
docker compose -f infra/docker-compose.prod.yml down
# 停止基础设施
docker compose -f infra/docker-compose.minimal.yml down
# 清理数据卷（谨慎！会删除数据库数据）
docker compose -f infra/docker-compose.minimal.yml down -v
```
---
## 5. 单独构建与运行（裸机生产）
### 5.1 api-gateway
```bash
cd services/api-gateway
# 编译
go build -o bin/api-gateway ./main.go
# 运行（生产环境变量）
DEV_MODE=false JWT_SECRET=<your-secret> ./bin/api-gateway
```
### 5.2 classes 服务
```bash
# 构建
pnpm --filter @edu/classes-service build
# 运行（从 dist/ 启动）
NODE_ENV=production PORT=3001 \
DATABASE_URL=mysql://edu:changeme@localhost:3306/next_edu_cloud \
REDIS_URL=redis://localhost:6379 \
node services/classes/dist/main.js
```
### 5.3 teacher-portal
```bash
# 构建
pnpm --filter @edu/teacher-portal build
# 运行
NODE_ENV=production PORT=3000 \
API_GATEWAY_URL=http://localhost:8080 \
node apps/teacher-portal/node_modules/.bin/next start -p 3000
```
---
## 6. 常见问题
### 6.1 ERR_TOO_MANY_REDIRECTS
**症状**：浏览器访问 `:3000/api/v1/classes` 无限重定向。
**根因**：Gin 默认 `RedirectTrailingSlash=true`，`/classes` → 301 → `/classes/`，Next.js rewrites 代理形成循环。
**修复**：`main.go` 已设 `r.RedirectTrailingSlash = false`，并同时注册无尾斜杠与通配符路由。
### 6.2 Docker Hub 拉取超时
**症状**：`docker compose up` 时 MySQL/Redis 镜像拉取超时。
**修复**：`infra/docker-compose.minimal.override.yml` 已配置 daocloud 镜像源，docker compose 会自动加载。
### 6.3 classes DI 注入失败
**症状**：`TypeError: Cannot read properties of undefined (reading 'create')`。
**根因**：NestJS ESM 模式下 `emitDecoratorMetadata` 不工作。
**修复**：`ClassesService` 构造函数已加 `@Inject(ClassesRepository)` 显式指定 token。
### 6.4 ESM import 缺 .js 后缀
**症状**：`error TS2307: Cannot find module './health.controller'`。
**修复**：ESM 模式下相对 import 必须带 `.js` 后缀（详见 project_rules §3.4）。
### 6.5 JWT 401 INVALID_TOKEN
**症状**：带 `dev-token` 仍返回 401。
**排查**：
1. 确认 `DEV_MODE=true` 环境变量已设置（api-gateway 进程）
2. 确认请求头格式：`Authorization: Bearer dev-token`（注意 Bearer 后空格）
3. 生产模式（`DEV_MODE=false`）下 dev-token 被拒绝是预期行为
### 6.6 Go 工具链不在 PATH
**症状**：Git Bash 或 PowerShell 中 `go: command not found`。
**修复**：
```powershell
$env:Path = "C:\Program Files\Go\bin;" + $env:Path
```
---
## 7. 数据库初始化
classes 服务使用 Drizzle ORM，首次运行需建表：
```bash
# 生成迁移
pnpm --filter @edu/classes-service drizzle-kit generate
# 执行迁移
pnpm --filter @edu/classes-service drizzle-kit migrate
```
> 若 `drizzle-kit` 未配置，可手动执行 `services/classes/src/db/schema.sql`（如存在）。
---
## 8. 相关文档
- [项目规则](../../.trae/rules/project_rules.md) — 强制约束
- [004 架构影响地图](../architecture/004_architecture_impact_map.md) — 服务清单与调用关系
- [known-issues](../troubleshooting/known-issues.md) — 已知问题速查
- [Git 工作流](./git-workflow.md) — 提交与 PR 规范
- [多 AI 协作指南](./multi-ai-collaboration.md) — 多 Agent 并行开发流程

735
docs/standards/multi-ai-collaboration.md Normal file
View File

@@ -0,0 +1,735 @@
# 多 AI 协作开发指南（Multi-AI Collaboration Guide）
> 版本：1.0
> 日期：2026-07-08
> 适用范围：Edu 微服务项目多 Agent 并行开发
> 关联文档：[Git 工作流](./git-workflow.md)、[项目规则](../../.trae/rules/project_rules.md)、[004 架构影响地图](../architecture/004_architecture_impact_map.md)、[CODEOWNERS](../../.github/CODEOWNERS)
---
## 1. 总体模式
### 1.1 角色定义
| 角色 | 职责 | 数量 | 备注 |
| ----------------------------- | -------------------------------------------- | ---- | ------------------- |
| **协调 AI（Coordinator AI）** | PR 审核、合并、冲突仲裁、分支管理、发布 | 1 | 不直接写业务代码 |
| **开发 AI（Dev AI）** | 按模块分工，写代码、提 PR | N | 每个负责 1-2 个模块 |
| **人类决策者（Human）** | 架构决策、Breaking Change 审批、最终发布确认 | 1 | 只在关键节点介入 |
### 1.2 工作流总览
```
开发 AI-A (classes模块) 开发 AI-B (iam模块) 协调 AI
│ │ │
│ 1.拉取最新 main │ 1.拉取最新 main │
│ 2.创建特性分支 │ 2.创建特性分支 │
│ 3.开发+提交 │ 3.开发+提交 │
│ 4.推送+创建 PR │ 4.推送+创建 PR │
│──────────────────────────────────────────────────────→│
│ │ │ 5.CI校验
│ │ │ 6.代码审核
│ │ │ 7.合并到 main
│ │ │ 8.通知开发 AI 同步
│←─────────────────────────────────────────────────────│
│ 9.拉取最新 main │ │
```
---
## 2. 模块分工矩阵
### 2.1 模块清单与 AI 分配
每个 AI 负责一个"限界上下文"，避免跨模块修改导致冲突。
| 模块 | scope | 路径 | 负责阶段 | 建议 AI 数 |
| -------------- | ---------------- | ------------------------- | -------- | ------------ |
| api-gateway | `api-gateway` | `services/api-gateway/` | P1 | 1 |
| classes | `classes` | `services/classes/` | P1 | 1 |
| teacher-portal | `teacher-portal` | `apps/teacher-portal/` | P1-P2 | 1 |
| iam | `iam` | `services/iam/` | P2 | 1 |
| teacher-bff | `teacher-bff` | `services/teacher-bff/` | P2 | 1 |
| core-edu | `core-edu` | `services/core-edu/` | P3 | 1 |
| content | `content` | `services/content/` | P4 | 1 |
| data-ana | `data-ana` | `services/data-ana/` | P4 | 1 |
| msg | `msg` | `services/msg/` | P5 | 1 |
| ai | `ai` | `services/ai/` | P5 | 1 |
| push-gateway | `push-gateway` | `services/push-gateway/` | P5 | 1 |
| shared-proto | `shared-proto` | `packages/shared-proto/` | 跨阶段 | 协调 AI 维护 |
| shared-tokens | `shared-tokens` | `packages/shared-tokens/` | 跨阶段 | 协调 AI 维护 |
| infra | `infra` | `infra/` | 跨阶段 | 1 (SRE AI) |
| docs | `docs` | `docs/` | 跨阶段 | 协调 AI 维护 |
### 2.2 分工原则
1. **单一负责制**：每个模块只有一个 AI 负责，避免并行修改同一文件
2. **契约集中管理**：`shared-proto` 由协调 AI 维护，开发 AI 只读引用
3. **跨模块变更拆分**：需要修改多个模块时，拆成多个 PR，按依赖顺序合并
4. **基础设施独立**：`infra/` 由 SRE AI 专门负责，业务 AI 不直接修改
---
## 3. 分支策略
### 3.1 分支命名规范
```
<type>/<scope>-<task-id>-<ai-id>
```
| 字段 | 说明 | 示例 |
| --------- | ------------------------------------------- | ---------------- |
| `type` | feat / fix / refactor / docs / chore / test | `feat` |
| `scope` | 模块名（见 §2.1） | `classes` |
| `task-id` | 任务简短描述（kebab-case） | `add-pagination` |
| `ai-id` | AI 标识符（避免多 AI 同名冲突） | `ai01` |
**完整示例**：
- `feat/classes-add-pagination-ai01`
- `fix/api-gateway-redirect-loop-ai02`
- `docs/git-workflow-update-coord`
### 3.2 分支生命周期
1. **创建**：从最新 `main` 拉取：`git checkout main && git pull && git checkout -b feat/classes-xxx-ai01`
2. **开发**：在特性分支上提交（遵循 Conventional Commits）
3. **推送**：`git push -u origin feat/classes-xxx-ai01`
4. **合并后删除**：PR 合并后，删除本地与远程特性分支
> 特性分支寿命 ≤ 3 天（见 git-workflow.md §1）。超期需 rebase 最新 main。
### 3.3 多 AI 分支隔离规则
- **禁止多 AI 共用同一分支**
- **禁止直接 push 到 `main`**（由协调 AI 通过 PR 合并）
- **跨模块变更**：各自在模块分支开发，最后由协调 AI 按依赖顺序合并
---
## 4. 推送与提交流程
### 4.1 提交规范（Conventional Commits）
```bash
git commit -m "feat(classes): 新增班级分页查询"
git commit -m "fix(api-gateway): 修复尾斜杠重定向循环"
git commit -m "docs(standards): 更新多AI协作文档"
```
**scope 必须匹配 `.commitlintrc.js` 的 scope-enum**（26 项，见 git-workflow.md §3.3）。
### 4.2 标准推送流程
开发 AI 执行：
```bash
# 1. 确认在正确的特性分支
git branch --show-current
# 输出：feat/classes-add-pagination-ai01
# 2. 拉取最新 main（rebase 保持线性）
git fetch origin
git rebase origin/main
# 3. 解决冲突（如有）
# 编辑冲突文件 → git add → git rebase --continue
# 4. 本地校验（强制，见 project_rules §7）
pnpm run lint # TS 服务
pnpm run typecheck # TS 服务
cd services/api-gateway && go vet ./... && go build ./... # Go 服务
# 5. 推送
git push -u origin feat/classes-add-pagination-ai01
# 6. 创建 PR（见 §5）
```
### 4.3 多 AI 推送冲突处理
当多个 AI 的 PR 修改了同一文件（如 `package.json`、`004_architecture_impact_map.md`）：
1. **先合并的 PR 正常合并**
2. **后合并的 PR 需 rebase**：
```bash
git fetch origin
git rebase origin/main
# 解决冲突
git push --force-with-lease # 安全强推（仅自己的分支）
```
3. **协调 AI 仲裁**：若冲突涉及架构决策，由协调 AI 决定保留方案
> **禁止 `git push --force` 到 main 或他人分支**。只允许 `--force-with-lease` 到自己的特性分支。
---
## 5. PR 流程
### 5.1 创建 PR
推送后，开发 AI 通过 Git 平台（GitHub/Gitea）创建 PR：
```bash
# 使用 gh CLI（GitHub）
gh pr create \
--title "feat(classes): 新增班级分页查询" \
--body "## 变更说明
- 新增 GET /api/v1/classes?page=&size= 分页参数
- 响应增加 total/hasMore 字段
## 变更类型
- [x] feat（新功能）
## 影响范围
- [x] classes 服务
## 测试
- [x] 单元测试通过
- [x] 本地联调验证
## 校验
- [x] pnpm run lint
- [x] pnpm run typecheck
" \
--base main \
--head feat/classes-add-pagination-ai01
```
### 5.2 PR 标题规范
PR 标题必须与首个 commit 的 subject 一致（Squash Merge 时自动取首个 commit）：
```
<type>(<scope>): <subject>
```
**示例**：
- `feat(classes): 新增班级分页查询`
- `fix(api-gateway): 修复尾斜杠重定向循环`
### 5.3 PR 模板
使用 `.github/pull_request_template.md`（已存在）。必填项：
- 变更说明
- 变更类型
- 影响范围
- 测试情况
- 按语言校验结果
- 文档同步（arch:scan、CODEOWNERS）
### 5.4 PR 标注 AI 身份
在 PR 描述末尾追加（用于统计与审计）：
```markdown
---
**AI Agent**: ai01 (classes-module)
**Branch**: feat/classes-add-pagination-ai01
**Coordinator**: coord-ai
```
---
## 6. 代码审核与合并
### 6.1 Reviewer 分配
由 `.github/CODEOWNERS` 自动分配：
| 模块 | 自动 Reviewer | 实际映射 |
| ------------ | ----------------------- | -------- |
| classes | `@edu-platform/classes` | 协调 AI |
| api-gateway | `@edu-platform/gateway` | 协调 AI |
| shared-proto | `@edu-platform/arch` | 协调 AI |
| infra | `@edu-platform/sre` | SRE AI |
> 当前 `@edu-platform/*` 为占位符。多 AI 场景下，协调 AI 账号加入对应 team 即可自动收到 review 请求。
### 6.2 审核 checklist
协调 AI 审核 PR 时检查：
- [ ] **Commit 格式**：符合 Conventional Commits
- [ ] **Scope 正确**：scope 与修改的模块一致
- [ ] **架构合规**：无跨层依赖、无直接访问他人 DB
- [ ] **权限校验**：Controller 有 `@RequirePermission()`
- [ ] **设计令牌**：无硬编码颜色/字体（project_rules §3.10）
- [ ] **ESM 规则**：相对 import 带 `.js` 后缀（TS 服务）
- [ ] **契约同步**：proto 变更已同步 shared-proto
- [ ] **文档同步**：arch.db 已更新、004 已同步（如涉及）
- [ ] **CI 通过**：lint / typecheck / go vet / ruff 全绿
- [ ] **测试覆盖**：关键逻辑有单测
### 6.3 合并策略
| 策略 | 适用场景 | 操作 |
| ------------------------ | ------------------------------------ | ---------------------- |
| **Squash Merge**（默认） | 单 commit 或多个小 commit 合并为一个 | `gh pr merge --squash` |
| **Rebase Merge** | 多个有意义的 commit 需保留历史 | `gh pr merge --rebase` |
| **Merge Commit**（禁止） | — | 不允许 |
> 项目规则 git-workflow.md §1.4：**禁止 Merge Commit**，保持 main 历史线性。
### 6.4 合并流程（协调 AI 执行）
```bash
# 1. 确认 CI 通过
gh pr checks <PR-NUMBER>
# 2. 确认 review 通过（CODEOWNERS 已 approve）
gh pr view <PR-NUMBER> --json reviews
# 3. Squash 合并（删除源分支）
gh pr merge <PR-NUMBER> --squash --delete-branch
# 4. 通知开发 AI 同步本地 main
# （通过 commit message 或 issue 评论）
```
### 6.5 合并后同步
开发 AI 收到合并通知后：
```bash
# 切回 main
git checkout main
# 拉取最新（含已合并的 PR）
git pull origin main
# 删除本地特性分支
git branch -d feat/classes-add-pagination-ai01
# 开始下一个任务：从最新 main 拉新分支
git checkout -b feat/classes-next-task-ai01
```
---
## 7. 多 AI 并行开发流程
### 7.1 启动并行任务
人类决策者分配任务给多个 AI：
```
任务 1：classes 服务新增分页查询 → 开发 AI-A (ai01)
任务 2：api-gateway 新增限流规则 → 开发 AI-B (ai02)
任务 3：teacher-portal 优化班级列表 → 开发 AI-C (ai03)
```
### 7.2 并行执行
每个 AI 独立工作，互不干扰：
```bash
# AI-A
git checkout -b feat/classes-add-pagination-ai01
# ... 开发 ...
git push -u origin feat/classes-add-pagination-ai01
gh pr create --title "feat(classes): 新增班级分页查询" ...
# AI-B（同时）
git checkout -b feat/api-gateway-rate-limit-ai02
# ... 开发 ...
git push -u origin feat/api-gateway-rate-limit-ai02
gh pr create --title "feat(api-gateway): 新增 IP 级限流规则" ...
# AI-C（同时）
git checkout -b feat/teacher-portal-class-list-ux-ai03
# ... 开发 ...
```
### 7.3 顺序合并（有依赖时）
若 PR 间有依赖（如 AI-C 依赖 AI-A 的接口），协调 AI 按顺序合并：
1. 合并 AI-A 的 PR（classes 分页接口）
2. AI-C rebase 最新 main，解决冲突，更新 PR
3. 合并 AI-C 的 PR（前端调用新接口）
### 7.4 冲突预防
1. **契约先行**：proto 变更先合并，再合并依赖它的服务
2. **通知机制**：修改 `shared-proto/` 或 `004_architecture_impact_map.md` 时，在 PR 描述 @ 所有关联模块 AI
3. **频繁同步**：每天至少 `git pull origin main` 一次，避免长期分叉
---
## 8. 跨模块变更流程
### 8.1 变更拆分原则
修改涉及多模块时，按依赖顺序拆成多个 PR：
```
原始任务：classes 服务新增"班级导入"功能
涉及：
1. shared-proto 新增 ImportClassesRequest message
2. classes 服务实现 import 接口
3. api-gateway 路由 /api/v1/classes/import
4. teacher-portal 前端上传按钮
```
### 8.2 拆分与合并顺序
| 顺序 | PR | scope | 负责人 | 依赖 |
| ---- | ----------------------------------------------- | -------------- | --------- | ---- |
| 1 | `feat(shared-proto): 新增 ImportClassesRequest` | shared-proto | 协调 AI | 无 |
| 2 | `feat(classes): 实现班级批量导入` | classes | 开发 AI-A | PR-1 |
| 3 | `feat(api-gateway): 新增 import 路由` | api-gateway | 开发 AI-B | PR-2 |
| 4 | `feat(teacher-portal): 新增班级导入按钮` | teacher-portal | 开发 AI-C | PR-3 |
协调 AI 按顺序合并，每合并一个，后续 PR 的开发 AI rebase 最新 main。
### 8.3 Breaking Change 流程
涉及 Breaking Change（proto 字段删除、API 签名变更）：
1. **人类决策者审批**：在 issue 中讨论，获批准后才开发
2. **版本号升级**：proto 加 `v2` 后缀，服务同时支持 v1/v2 过渡期
3. **迁移文档**：更新 `MIGRATION_GUIDE.md`
4. **协调 AI 通知所有相关 AI**：在 PR 描述中列出影响范围
---
## 9. 完整工作流示例
### 9.1 场景：开发 AI-A 为 classes 新增分页查询
```bash
# ============ 开发 AI-A ============
# 1. 同步 main
git checkout main
git pull origin main
# 2. 创建特性分支
git checkout -b feat/classes-add-pagination-ai01
# 3. 开发
# 编辑 services/classes/src/classes/classes.controller.ts
# 编辑 services/classes/src/classes/classes.service.ts
# 编辑 services/classes/src/classes/classes.repository.ts
# 4. 本地校验
pnpm --filter @edu/classes-service lint
pnpm --filter @edu/classes-service typecheck
pnpm --filter @edu/classes-service test
# 5. 架构扫描（若新增了导出函数/路由）
pnpm run arch:scan
# 6. 提交
git add services/classes/
git commit -m "feat(classes): 新增班级分页查询
- GET /api/v1/classes 支持 page、size 参数
- 响应增加 total、hasMore 字段
- 单测覆盖分页逻辑"
# 7. 推送
git push -u origin feat/classes-add-pagination-ai01
# 8. 创建 PR
gh pr create \
--title "feat(classes): 新增班级分页查询" \
--body "..." \
--base main
# ============ 协调 AI ============
# 9. 收到 PR 通知，审核
gh pr view <PR-NUMBER>
gh pr checks <PR-NUMBER>
# 10. 代码审核（见 §6.2 checklist）
# 若需修改，评论要求开发 AI-A 修改
# 11. 合并
gh pr merge <PR-NUMBER> --squash --delete-branch
# 12. 通知开发 AI-A
# 评论："已合并，请同步本地 main"
# ============ 开发 AI-A ============
# 13. 同步
git checkout main
git pull origin main
git branch -d feat/classes-add-pagination-ai01
```
---
## 10. 常见问题与解决方案
### 10.1 多 AI 修改同一文件冲突
**场景**：AI-A 和 AI-B 都修改了 `package.json` 添加依赖。
**解决**：
1. AI-A 的 PR 先合并
2. AI-B 执行：
```bash
git fetch origin
git rebase origin/main
# 解决 package.json 冲突（保留两边依赖）
git add package.json
git rebase --continue
git push --force-with-lease
```
3. 协调 AI 重新审核
### 10.2 CI 失败但本地通过
**场景**：开发 AI 本地 lint 通过，CI 报错。
**排查**：
1. 检查 Node/Go/pnpm 版本是否一致（见 local-dev-runbook §1）
2. 检查 `pnpm-lock.yaml` 是否最新（`pnpm install --frozen-lockfile`）
3. 检查环境变量是否齐全（`.env` vs CI secrets）
**修复后**：
```bash
git add <fixed-files>
git commit -m "fix(classes): 修复 CI lint 失败"
git push
```
### 10.3 husky pre-commit hook 失败
**场景**：commit 时 hook 报错（lint-staged、commitlint）。
**排查**：
1. commitlint：检查 commit message 格式（type 小写、scope 在 enum 内、subject 不大写开头）
2. lint-staged：检查暂存文件是否通过 ESLint/gofmt
3. husky 9 Windows bug：若 pre-push hook "Bad file descriptor"，见 known-issues
**修复**：修正后重新 `git commit`，不要用 `--no-verify` 跳过。
### 10.4 proto 变更导致下游编译失败
**场景**：shared-proto 合并后，classes 服务 `buf generate` 报错。
**解决**：
1. 协调 AI 合并 proto PR 前，先在 PR 评论中通知所有依赖服务的 AI
2. 下游 AI 在自己的分支 rebase 最新 main 后重新 `buf generate`
3. 更新生成代码并提交：
```bash
git add packages/shared-proto/gen/
git commit -m "chore(shared-proto): 重新生成 TS 类型"
```
### 10.5 分支长期未合并（超 3 天）
**场景**：特性分支超过 3 天未合并。
**处理**：
1. rebase 最新 main：`git rebase origin/main`
2. 解决冲突后 `git push --force-with-lease`
3. 若仍无法合并，协调 AI 介入评估是否拆分 PR
### 10.6 误推到 main
**场景**：开发 AI 误将 commit 推到 main。
**修复**（协调 AI 执行）：
```bash
# 1. 确认误推的 commit
git log origin/main -5
# 2. 回退（保留误推 commit 到临时分支）
git checkout origin/main -b temp/backup-mispush
git checkout main
git reset --hard origin/main~1 # 回退 1 个 commit
# 3. 强推（仅协调 AI 有权限）
git push --force-with-lease origin main
# 4. 通知开发 AI 从 temp 分支重新提 PR
```
> **禁止开发 AI 自行 force push main**。只有协调 AI 有权操作。
### 10.7 AI 身份冲突（同名分支）
**场景**：两个 AI 都叫 "ai01"，创建了同名分支。
**预防**：每个 AI 启动前分配唯一 `ai-id`（如 `ai01`、`ai02`、`coord`）。
**修复**：后启动的 AI 重命名分支：
```bash
git branch -m feat/classes-xxx-ai01 feat/classes-xxx-ai01b
git push -u origin feat/classes-xxx-ai01b
```
---
## 11. AI 协作通信约定
### 11.1 通信渠道
| 场景 | 方式 |
| -------- | ----------------------------- |
| PR 审核 | PR 评论（`@ai01 请修改 xxx`） |
| 任务分配 | Issue（`@ai01 负责实现 xxx`） |
| 紧急通知 | PR 评论 + @ 相关人员 |
| 架构讨论 | Issue 标签 `discussion` |
### 11.2 PR 评论规范
协调 AI 审核评论格式：
```
## 审核结果：需修改 / 通过 / 拒绝
### 需修改项
1. [classes.controller.ts:42] 缺少 @RequirePermission() 装饰器
2. [classes.service.ts:88] 返回值未标注 Promise<T>
### 建议
- 考虑抽取分页逻辑到 shared-ts
---
协调 AI（coord）
```
### 11.3 AI 工作日志
每个 AI 完成任务后，在 `docs/troubleshooting/known-issues.md` "工作经验日志"区追加（project_rules §9.3）：
```markdown
| 日期 | 模块 | 做了什么 + 学到什么 |
| ---------------- | ------- | ----------------------------------------------- |
| 2026-07-08 14:00 | classes | 实现分页查询，学到 Drizzle 的 limit/offset 用法 |
```
---
## 12. 安全与权限
### 12.1 分支保护规则（main）
- **禁止直接 push**：必须通过 PR
- **必须 PR review**：至少 1 人（CODEOWNERS 自动分配）
- **必须 CI 通过**：lint / typecheck / build
- **禁止 force push**：开发 AI 无权，仅协调 AI 在事故时操作
### 12.2 AI 账号权限
| 角色 | push 特性分支 | 创建 PR | 合并 PR | push main | force push main |
| ------- | ------------- | ------- | ----------- | --------- | --------------- |
| 开发 AI | ✅ | ✅ | ❌ | ❌ | ❌ |
| 协调 AI | ✅ | ✅ | ✅ | ❌ | ⚠️（仅事故） |
| SRE AI | ✅（infra） | ✅ | ✅（infra） | ❌ | ⚠️（仅事故） |
### 12.3 敏感文件保护
以下文件修改需人类决策者额外审批：
- `.env`、`.env.example`（密钥相关）
- `infra/security/secrets.example.env`
- `infra/k8s/`（生产部署）
- `.github/workflows/`（CI 配置）
---
## 13. 发布流程
### 13.1 版本号规则（见 git-workflow.md §7）
- 平台版本：`v{阶段}.{迭代}.{patch}`（如 `v1.2.0`）
- 服务版本：`{service}:{semver}`（如 `classes:1.0.1`）
### 13.2 发布步骤（协调 AI 执行）
```bash
# 1. 确认 main 稳定（CI 全绿）
gh run list --branch main --limit 5
# 2. 打 tag
git tag -a v1.2.0 -m "P1 阶段第 2 次迭代发布"
git push origin v1.2.0
# 3. 触发 CI 构建镜像
# （CI 由 tag push 触发，见 .github/workflows/）
# 4. 人类决策者确认部署到生产
```
### 13.3 回滚（见 git-workflow.md §8）
```bash
# K8s 回滚
kubectl rollout undo deployment/api-gateway -n edu-system
# Git 回退（紧急）
git revert <bad-commit>
git push origin main
```
---
## 14. 快速参考卡
### 开发 AI 日常工作流
```bash
# 拉新分支
git checkout main && git pull && git checkout -b feat/<scope>-<task>-<ai-id>
# 开发 → 校验 → 提交
pnpm run lint && pnpm run typecheck
git add . && git commit -m "feat(<scope>): <subject>"
# 推送 → 创建 PR
git push -u origin feat/<scope>-<task>-<ai-id>
gh pr create --title "feat(<scope>): <subject>" --body "..."
# 等待审核 → 修改 → 重新推送
# （协调 AI 合并后）
git checkout main && git pull && git branch -d feat/<scope>-<task>-<ai-id>
```
### 协调 AI 日常工作流
```bash
# 查看待审核 PR
gh pr list --state open --reviewer @edu-platform/arch
# 审核
gh pr view <PR-NUMBER>
gh pr checks <PR-NUMBER>
# 合并
gh pr merge <PR-NUMBER> --squash --delete-branch
# 发布
git tag -a v<version> -m "..." && git push origin v<version>
```
---
## 15. 相关文档
- [Git 工作流](./git-workflow.md) — 提交规范、分支策略、CODEOWNERS
- [本地启动手册](./local-dev-runbook.md) — 手动启动服务
- [项目规则](../../.trae/rules/project_rules.md) — 强制约束
- [004 架构影响地图](../architecture/004_architecture_impact_map.md) — 模块与依赖关系
- [CODEOWNERS](../../.github/CODEOWNERS) — Reviewer 自动分配
- [PR 模板](../../.github/pull_request_template.md) — PR 必填项
- [known-issues](../troubleshooting/known-issues.md) — 已知问题速查