docs(docs): project_rules 新增多AI协作与CICD规范章节

- §14 多 AI 协作规范：角色权限矩阵、模块单一负责制、分支命名、PR/合并规则、跨模块变更顺序、冲突处理、AI 身份标注、敏感文件保护 - §15 CI/CD 规范：流水线阶段、触发条件、镜像规范、部署策略、Secrets 管理、必需 CI 文件
2026-07-08 15:15:14 +08:00
parent d19285a977
commit a3f00c882a
1 changed files with 143 additions and 0 deletions
--- a/.trae/rules/project_rules.md
+++ b/.trae/rules/project_rules.md
@@ -369,4 +369,147 @@ services/[service]/src/

 ---

+## 14. 多 AI 协作规范
+
+> 详细流程见 [多 AI 协作指南](../../docs/standards/multi-ai-collaboration.md)，本节为强制约束摘要。
+
+### 14.1 角色与权限
+
+| 角色                       | 职责                                     | push 特性分支 | 创建 PR | 合并 PR     | push main | force push main |
+| -------------------------- | ---------------------------------------- | ------------- | ------- | ----------- | --------- | --------------- |
+| **协调 AI（Coordinator）** | PR 审核、合并、冲突仲裁、发布            | ✅            | ✅      | ✅          | ❌        | ⚠️（仅事故）    |
+| **开发 AI（Dev）**         | 按模块分工写代码、提 PR                  | ✅            | ✅      | ❌          | ❌        | ❌              |
+| **SRE AI**                 | `infra/` 维护、部署                      | ✅（infra）   | ✅      | ✅（infra） | ❌        | ⚠️（仅事故）    |
+| **人类决策者**             | 架构决策、Breaking Change 审批、发布确认 | —             | —       | —           | —         | —               |
+
+### 14.2 模块单一负责制
+
+- 每个模块（限界上下文）只有一个 AI 负责，禁止并行修改同一模块
+- `shared-proto`、`shared-tokens`、`docs/` 由协调 AI 维护，开发 AI 只读引用
+- `infra/` 由 SRE AI 专门负责，业务 AI 不直接修改
+
+### 14.3 分支命名规范（强制）
+
+```
+<type>/<scope>-<task-id>-<ai-id>
+```
+
+- `type`：feat / fix / refactor / docs / chore / test
+- `scope`：见 §7 提交规范 scope-enum（26 项）
+- `task-id`：任务简短描述（kebab-case）
+- `ai-id`：AI 唯一标识符（如 `ai01`、`ai02`、`coord`）
+
+**示例**：`feat/classes-add-pagination-ai01`
+
+### 14.4 PR 与合并规则（强制）
+
+1. **禁止直接 push 到 `main`**：所有变更通过 PR
+2. **PR 必须通过 CI**：lint / typecheck / build / test 全绿
+3. **PR 必须通过 CODEOWNERS review**：至少 1 人 approve
+4. **合并策略**：Squash Merge（默认），Rebase Merge（保留多 commit 历史），**禁止 Merge Commit**
+5. **特性分支寿命 ≤ 3 天**：超期需 rebase 最新 main
+6. **跨模块变更拆分**：按依赖顺序拆多个 PR（proto → service → gateway → frontend），协调 AI 按序合并
+
+### 14.5 跨模块变更顺序（强制）
+
+修改涉及多模块时，必须按以下顺序拆分 PR 并顺序合并：
+
+1. `shared-proto`（proto 契约）
+2. 业务服务（classes / iam / core-edu 等）
+3. `api-gateway`（路由）
+4. BFF（teacher-bff 等）
+5. 微前端（teacher-portal 等）
+
+> 每合并一个 PR，后续 PR 的开发 AI 必须 rebase 最新 main 并重新校验。
+
+### 14.6 冲突处理规则
+
+- **文件冲突**：后合并的 PR rebase 最新 main，`git push --force-with-lease`（仅自己的分支）
+- **架构冲突**：由协调 AI 仲裁保留方案
+- **禁止 `git push --force` 到 main 或他人分支**
+
+### 14.7 AI 身份标注（强制）
+
+每个 PR 描述末尾必须追加：
+
+```markdown
+---
+
+**AI Agent**: <ai-id> (<负责模块>)
+**Branch**: <分支名>
+**Coordinator**: <协调 AI ai-id>
+```
+
+每个 AI 完成任务后，在 `docs/troubleshooting/known-issues.md` "工作经验日志"区追加记录（见 §9.3）。
+
+### 14.8 敏感文件保护
+
+以下文件修改需人类决策者额外审批：
+
+- `.env`、`.env.example`、`infra/security/secrets.example.env`
+- `infra/k8s/`（生产部署）
+- `.github/workflows/`（CI 配置）
+- `.trae/rules/project_rules.md`（项目规则）
+
+---
+
+## 15. CI/CD 规范
+
+> 详细配置见 `.github/workflows/`，本节为强制约束。
+
+### 15.1 流水线阶段（强制）
+
+所有 PR 与 main 分支推送必须通过以下阶段：
+
+| 阶段             | 并行         | 内容                                       | 失败策略 |
+| ---------------- | ------------ | ------------------------------------------ | -------- |
+| **lint**         | ✅（按语言） | TS ESLint / Go vet / Python ruff           | 失败阻断 |
+| **typecheck**    | ✅           | TS `tsc --noEmit`                          | 失败阻断 |
+| **test**         | ✅（按服务） | Go test / Vitest / pytest                  | 失败阻断 |
+| **build**        | ✅（按服务） | Go build / nest build / next build         | 失败阻断 |
+| **arch:scan**    | ✅           | `pnpm run arch:scan` + 校验 arch.db 一致性 | 失败阻断 |
+| **docker-build** | ✅（按服务） | 构建镜像（不推送）                         | 失败阻断 |
+
+> main 分支额外阶段：`docker-push`（推送镜像）+ `deploy`（部署到服务器）
+
+### 15.2 触发条件
+
+| 事件         | 触发阶段                                                   | 触发条件   |
+| ------------ | ---------------------------------------------------------- | ---------- |
+| PR 创建/更新 | lint + typecheck + test + build + arch:scan + docker-build | 所有路径   |
+| push 到 main | 上述全部 + docker-push + deploy                            | 合并后自动 |
+| tag `v*`     | docker-push（tag 镜像）+ deploy（生产）                    | 手动打 tag |
+
+### 15.3 镜像规范
+
+- **镜像名**：`edu/<service>:<tag>`
+- **tag 策略**：
+  - `latest`：main 分支最新
+  - `<git-sha>`：每次构建的 commit SHA（可追溯）
+  - `v<version>`：正式发布 tag
+- **镜像扫描**：docker-push 后自动运行 Trivy 扫描，CRITICAL 漏洞阻断部署
+
+### 15.4 部署策略
+
+- **目标环境**：服务器 Docker Compose（P1-P2 阶段），K8s（P3+ 阶段）
+- **部署方式**：SSH 到服务器，`docker compose pull && docker compose up -d`
+- **健康检查**：部署后轮询 `/healthz` 端点，连续 3 次失败回滚
+- **回滚**：`docker compose rollback`（上一版本镜像 tag）
+
+### 15.5 Secrets 管理
+
+- **CI Secrets**：存于 GitHub Actions secrets / Gitea Actions secrets
+- **部署服务器**：`.env` 文件由 SRE AI 管理，不进版本库
+- **JWT_SECRET**：生产环境强随机值，不与开发环境共享
+
+### 15.6 必需的 CI 文件
+
+| 文件                           | 用途                                        |
+| ------------------------------ | ------------------------------------------- |
+| `.github/workflows/ci.yml`     | 主流水线（lint + typecheck + test + build） |
+| `.github/workflows/docker.yml` | Docker 镜像构建与推送（main + tag 触发）    |
+| `.github/workflows/deploy.yml` | 部署到服务器（main 触发，需环境审批）       |
+
+---
+
 **本规则文件是项目的强制约束，所有 contributor（含 AI）必须遵守。规则变更需同步更新 004 与 arch.db。**