diff --git a/.trae/rules/project_rules.md b/.trae/rules/project_rules.md index 877369d..1fb14f0 100644 --- 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`: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**: (<负责模块>) +**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/:` +- **tag 策略**: + - `latest`:main 分支最新 + - ``:每次构建的 commit SHA(可追溯) + - `v`:正式发布 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。**