docs(docs): project_rules 新增多AI协作与CICD规范章节
- §14 多 AI 协作规范:角色权限矩阵、模块单一负责制、分支命名、PR/合并规则、跨模块变更顺序、冲突处理、AI 身份标注、敏感文件保护 - §15 CI/CD 规范:流水线阶段、触发条件、镜像规范、部署策略、Secrets 管理、必需 CI 文件
This commit is contained in:
@@ -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。**
|
**本规则文件是项目的强制约束,所有 contributor(含 AI)必须遵守。规则变更需同步更新 004 与 arch.db。**
|
||||||
|
|||||||
Reference in New Issue
Block a user