447 lines
30 KiB
Markdown
447 lines
30 KiB
Markdown
# AI 分配方案与架构设计外包流程
|
||
|
||
> 版本：1.1
|
||
> 日期：2026-07-10
|
||
> 适用范围：Edu 微服务项目（架构设计外包三阶段已实施，进入持续开发阶段）
|
||
> 关联文档：[多 AI 协作指南](../standards/multi-ai-collaboration.md)、[004 架构影响地图](./004_architecture_impact_map.md)、[待开发功能路线图](./roadmap/pending-features.md)
|
||
>
|
||
> **状态说明**：架构设计外包三阶段（模块理解 → 模块架构设计 → 按图实施）已实施完成，各模块设计文档见 `services/<service>/docs/` 与 `apps/<app>/docs/`。当前进入持续开发阶段，所有 AI 工作默认按多 AI 协作模式进行。
|
||
|
||
---
|
||
|
||
## 1. 外包总流程：三阶段（已实施）
|
||
|
||
```
|
||
阶段 1：模块理解 阶段 2：模块架构设计 阶段 3：按图实施
|
||
(每个 AI 独立) (每个 AI 独立) (并行开发)
|
||
│ │ │
|
||
按需阅读模块架构文档 产出模块内部架构图 按自己画的图写代码
|
||
理解边界与契约 定义内部模块/数据流 coord 定期巡检一致性
|
||
理解与其他模块的接口 标注与其他模块的交互点 遇到偏差更新架构图
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
交付：理解确认书 交付：模块架构设计文档 交付：代码 + 更新图
|
||
```
|
||
|
||
> **三阶段已实施完成**。阶段 1 产出见各模块 `docs/01-understanding.md`，阶段 2 产出见各模块 `docs/02-architecture-design.md`，阶段 3 持续进行中。
|
||
|
||
**阶段 1 目标**：每个 AI 读懂自己负责的模块在架构中的位置、边界、契约（按需阅读，见 §4）。
|
||
**阶段 2 目标**：每个 AI 产出自己模块的内部架构设计，经过 coord 交叉审查后放行。
|
||
**阶段 3 目标**：按设计文档写代码，coord 定期巡检一致性。
|
||
|
||
---
|
||
|
||
## 2. 完整服务清单
|
||
|
||
| 类别 | 服务名 | 语言/框架 | 限界上下文 | 阶段 | 状态 |
|
||
| ---- | -------------- | ---------------- | ---------------------- | ------ | ----------------- |
|
||
| 网关 | api-gateway | Go (Gin) | API 网关 | P1 | ✅ 已实现 |
|
||
| 网关 | push-gateway | Go (Gin) | 推送网关 | P5 | 📐 需设计 |
|
||
| BFF | teacher-bff | TS (NestJS) | 教学场景域聚合 | P2 | ✅ 已实现 |
|
||
| BFF | student-bff | TS (NestJS) | 学习场景域聚合 | P3 | 📐 需设计 |
|
||
| BFF | parent-bff | TS (NestJS) | 家长场景域聚合 | P4 | 📐 需设计 |
|
||
| 业务 | iam | TS (NestJS) | 身份认证 | P2 | ✅ 已实现 |
|
||
| 业务 | core-edu | TS (NestJS) | 教学核心（含 classes） | P3 | 📐 待合并 classes |
|
||
| 业务 | content | TS (NestJS) | 内容资源 | P4 | 📐 需设计 |
|
||
| 业务 | msg | TS (NestJS) | 消息通知 | P5 | 📐 需设计 |
|
||
| 业务 | data-ana | Python (FastAPI) | 数据分析 | P4 | 📐 需设计 |
|
||
| 业务 | ai | Python (FastAPI) | AI 网关 | P5 | 📐 需设计 |
|
||
| 前端 | teacher-portal | TS (Next.js) | 教学场景域前端 | P2 | ✅ 已实现 |
|
||
| 前端 | student-portal | TS (Next.js) | 学习场景域前端 | P3 | 📐 需设计 |
|
||
| 前端 | parent-portal | TS (Next.js) | 家长场景域前端 | P4 | 📐 需设计 |
|
||
| 前端 | admin-portal | TS (Next.js) | 管理场景域前端 | P6 | 📐 需设计 |
|
||
| 共享 | shared-proto | protobuf | 契约 | 跨阶段 | ✅ 部分 |
|
||
| 共享 | shared-ts | TS | TS 共享工具 | 跨阶段 | — |
|
||
| 共享 | shared-go | Go | Go 共享工具 | 跨阶段 | — |
|
||
| 共享 | shared-py | Python | Python 共享工具 | 跨阶段 | — |
|
||
| 基础 | infra | — | K8s/Grafana/WAF | 跨阶段 | ✅ 部分 |
|
||
|
||
> 状态标记：✅ 已实现需审计 | 📐 需架构设计（本次外包核心产出）
|
||
|
||
---
|
||
|
||
## 3. AI 分配方案（7 AI + 1 coord）
|
||
|
||
### 3.1 分配原则
|
||
|
||
- **同语言内聚**：一个 AI 负责多个同语言服务，学习成本只付一次
|
||
- **领域亲缘性**：同类业务放一起（BFF 归 BFF、Python 归 Python）
|
||
- **工作负载均衡**：Neo4j+ES 的内容服务、ClickHouse 的分析服务复杂度高，不绑太多其他服务
|
||
- **前端统一**：Module Federation 微前端由一人设计，保证 shell + remote 架构一致
|
||
- **黄金模板对齐**：已实现的 services 负责 AI 需审计并对齐 classes 标准
|
||
|
||
### 3.2 分配矩阵
|
||
|
||
| AI 标识 | 语言 | 服务 | 数量 | 阶段归属 |
|
||
| --------- | ------ | ----------------------------------------------------------- | ---- | -------- |
|
||
| **ai01** | Go | api-gateway、push-gateway | 2 | P1 + P5 |
|
||
| **ai02** | TS | iam | 1 | P2 |
|
||
| **ai03** | TS | teacher-bff、core-edu | 2 | P2 + P3 |
|
||
| **ai04** | TS | student-bff、parent-bff | 2 | P3 + P4 |
|
||
| **ai05** | TS | content、msg | 2 | P4 + P5 |
|
||
| **ai06** | Python | data-ana、ai | 2 | P4 + P5 |
|
||
| **ai07** | TS | teacher-portal、student-portal、parent-portal、admin-portal | 4 | P2-P6 |
|
||
| **coord** | — | shared-proto、shared-*、infra/、docs/、CI/CD | — | 跨阶段 |
|
||
|
||
### 3.3 为什么这样拆
|
||
|
||
| 决策 | 理由 |
|
||
| ----------------------------- | ------------------------------------------------------------------------------- |
|
||
| ai02 独立负责 iam | RBAC 三层角色 + DataScope 6 级 + 视口 4 层是整个系统的权限中枢，复杂度最高 |
|
||
| ai03 teacher-bff + core-edu | 教学域全栈：BFF 聚合 + 核心业务。考试/作业/成绩状态机在一个人手里，不跨 AI 协调 |
|
||
| ai04 student-bff + parent-bff | 两个 BFF 都是纯聚合层，技术同质（GraphQL + DataLoader），设计模式完全复用 |
|
||
| ai05 content + msg | 都依赖 ES，content 建索引、msg 查索引，一人设计避免 ES 索引冲突 |
|
||
| ai07 前端 4 端 | Module Federation shell + remote 架构需一人统一设计，4 端共享组件库和权限体系 |
|
||
| coord 不写业务代码 | 专注契约管理 + 交叉审查，保证 7 份设计文档的接口一致性 |
|
||
|
||
---
|
||
|
||
## 4. 各 AI 阶段 1 文档阅读清单（按需阅读）
|
||
|
||
> **架构文档按需阅读原则**（见 [project_rules §10](../../.trae/rules/project_rules.md) 与 [multi-ai-collaboration §2.2](../standards/multi-ai-collaboration.md)）：
|
||
>
|
||
> - **模块开发**：只读自己模块的架构与服务 README，不读其他模块内部实现
|
||
> - **全局工作**（coord、跨模块契约、基础设施、文档体系）：读全局架构文档
|
||
> - **功能开发/文档书写等强依赖场景**：必须读对应架构
|
||
> - **严格模块边界**：AI 只读自己负责模块的文档与源码，仅在确认跨模块契约时才读对方的对外接口（proto/API/事件），不读对方内部实现
|
||
|
||
### 4.1 全员必读（所有 AI，无论模块开发还是全局工作）
|
||
|
||
| 顺序 | 文档 | 说明 |
|
||
| ---- | ------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
||
| 1 | [project_rules.md](../../.trae/rules/project_rules.md) | 项目强制约束（架构规则、编码规范、提交规范、多 AI 协作、分支开发） |
|
||
| 2 | [coding-standards.md](../standards/coding-standards.md) | 多语言编码标准 |
|
||
| 3 | [multi-ai-collaboration.md](../standards/multi-ai-collaboration.md) | 多 AI 协作指南（§2.1 严格模块边界、§2.2 按需阅读、§3 分支开发规则） |
|
||
|
||
### 4.2 模块开发按需阅读（只读自己模块，禁止读其他模块内部实现）
|
||
|
||
| AI | 必读文档 | 说明 |
|
||
| ---- | ------------------------------------------------------------------------------------ | ------------------- |
|
||
| ai01 | `services/api-gateway/README.md`、`services/push-gateway/README.md`、004 §网关层章节 | Go 网关层架构 |
|
||
| ai02 | `services/iam/README.md`、004 §iam 章节 | 身份认证架构 |
|
||
| ai03 | `services/teacher-bff/README.md`、`services/core-edu/README.md`、004 §教学场景域章节 | 教学场景域架构 |
|
||
| ai04 | 004 §student-bff / parent-bff 章节（待建立服务，无 README） | 学习+家长场景域 BFF |
|
||
| ai05 | 004 §content / msg 章节（待建立服务，无 README） | 内容+通知架构 |
|
||
| ai06 | `services/data-ana/README.md`、`services/ai/README.md`、004 §数据分析/AI 章节 | Python 数据+AI 架构 |
|
||
| ai07 | `apps/teacher-portal/README.md`、004 §前端章节 | 前端 4 端架构 |
|
||
|
||
> **禁止越界阅读**：上表只列自己模块。如需确认与某模块的契约，走 §4.4 跨模块契约阅读，不读对方内部源码与 README。
|
||
|
||
### 4.3 全局工作必读（仅 coord，以及 AI 执行跨模块/全局任务时）
|
||
|
||
| 顺序 | 文档 | 说明 |
|
||
| ---- | --------------------------------------------------------- | ---------------------------------------------------- |
|
||
| 1 | [README.md](../../README.md) | 项目总览 |
|
||
| 2 | [MIGRATION_GUIDE.md](../../MIGRATION_GUIDE.md) | 迁移指南 |
|
||
| 3 | [004 架构影响地图](./004_architecture_impact_map.md) 全文 | 全局架构与依赖（coord 必读；模块开发只读 §4.2 章节） |
|
||
| 4 | [pending-features.md](./roadmap/pending-features.md) | 六阶段路线图 |
|
||
|
||
> 模块开发 AI **不需要**通读上述全局文档，仅在任务涉及跨模块协调、基础设施变更、文档体系维护时按需阅读。
|
||
|
||
### 4.4 跨模块契约按需阅读（仅涉及 proto 变更或确认接口时）
|
||
|
||
| 场景 | 必读文档 |
|
||
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
|
||
| 修改/新增 proto message | `packages/shared-proto/proto/` 中**相关** .proto 文件（不读全部，只读变更涉及的文件） |
|
||
| 确认与其他模块的接口 | 004 §跨模块交互章节 + 对方服务的**对外接口**（proto / API 端点 / Kafka 事件名），**不读对方内部实现** |
|
||
|
||
### 4.5 黄金模板参考（仅 TS 服务首次实现新服务时）
|
||
|
||
| AI | 参考文档 |
|
||
| ------------------ | ---------------------------------------------------------------------------------- |
|
||
| ai02-05（TS 服务） | `services/classes/src/` 黄金模板源码（首次实现新服务时参考横切关注点，不强制全读） |
|
||
| ai01 / ai06 / ai07 | 按需参考 classes 的横切关注点实现模式（错误处理/可观测/健康检查等），不强制读源码 |
|
||
|
||
---
|
||
|
||
## 5. 各 AI 阶段 2 设计重点
|
||
|
||
### ai01 — Go 网关层
|
||
|
||
| 服务 | 设计重点 |
|
||
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| api-gateway | 路由表矩阵（路径 → 下游服务 + 端口，需覆盖全部 6 个业务服务 + 3 个 BFF）；限流策略表（每路由 QPS）；熔断阈值配置（错误率/延迟阈值）；JWT RS256 公钥校验流程；CORS 白名单；请求 ID 注入 |
|
||
| push-gateway | WebSocket 连接生命周期（认证 → 心跳 → 断线重连）；与 msg 的 gRPC 推送通道协议；用户 session 映射（在线用户 → WebSocket 连接）；水平扩展方案（Redis Pub/Sub 跨实例广播） |
|
||
|
||
### ai02 — 身份认证
|
||
|
||
| 服务 | 设计重点 |
|
||
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| iam | RBAC 权限点枚举（全部模块的 CRUD 权限常量）；三层角色模型（系统/组织/临时）权限合并规则；DataScope 6 级 SQL WHERE 注入规则（每级对应的过滤条件）；视口 4 层配置表设计（导航/路由/组件/数据）；JWT RS256 私钥签发 + 公钥暴露端点；refresh_token 轮换策略；权限解析 API（getEffectivePermissions → permissions + viewports + dataScope） |
|
||
|
||
### ai03 — 教学场景域
|
||
|
||
| 服务 | 设计重点 |
|
||
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| teacher-bff | GraphQL schema（Query/Mutation，按场景域组织）；DataLoader 批量去重策略；并行 gRPC 调用编排；聚合结果缓存 TTL 策略（5-30s 短缓存）；教师角色差异化（教师 vs 教导主任 vs 教研组长 → 视口推导） |
|
||
| core-edu | classes 模块黄金模板对齐；考试生命周期状态机（草稿 → 已发布 → 作答中 → 批改中 → 已出分 → 已归档）；Outbox 事件定义（ExamPublished、HomeworkSubmitted、GradeRecorded）；成绩计算公式与配置化；作业提交高并发优化（Redis 分布式锁 + 排队）；排课/考勤数据模型 |
|
||
|
||
### ai04 — 学习 + 家长场景域 BFF
|
||
|
||
| 服务 | 设计重点 |
|
||
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| student-bff | 学生端 GraphQL schema（与 teacher-bff 对比差异）；DataLoader 复用 teacher-bff 模式；权限区分（学生只能看自己的数据，DataScope=SELF）；考试/作业/成绩的学生视角 API |
|
||
| parent-bff | 家长端 GraphQL schema；与 iam 的学生-家长关联查询；多子女账户切换设计；家长通知偏好配置 |
|
||
|
||
### ai05 — 内容 + 通知
|
||
|
||
| 服务 | 设计重点 |
|
||
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| content | Neo4j 图模型（知识点 → 知识点前置依赖 → 教材关联）；ES 索引 mapping 设计（题库全文检索 + 标签过滤）；题库 CRUD 完整 API（含批量导入）；与 ai 服务的 gRPC 接口（查询知识点/题库用于 AI 出题）；教材/章节结构树 |
|
||
| msg | 通知渠道抽象（站内信/邮件/短信，策略模式）；ES 降级查询策略（DB 不可用时走 ES）；Kafka 消费幂等设计（event_id 去重）；与 push-gateway 的推送通道协议；通知模板管理；已读/未读状态管理 |
|
||
|
||
### ai06 — Python 数据 + AI
|
||
|
||
| 服务 | 设计重点 |
|
||
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| data-ana | ClickHouse 宽表设计（考试、作业、成绩、掌握度、出勤 5 张宽表）；CDC 消费者架构（Debezium → Kafka → ClickHouse）；学情分析 API（班级统计/个人趋势/预警阈值）；掌握度计算算法（加权滑动平均）；Dashboard 数据聚合 |
|
||
| ai | LLM Provider 适配器模式（OpenAI/百川/本地模型）；SSE 流式响应（题目逐字生成）；出题 Prompt 模板管理；备课工作流（分析学情 → 推荐知识点 → 生成题目 → 教师审核 → 入库）；用量计费/频率限制 |
|
||
|
||
### ai07 — 前端 4 端
|
||
|
||
| 服务 | 设计重点 |
|
||
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| teacher-portal | 现有代码审计对齐黄金标准；Module Federation shell 暴露的共享组件 |
|
||
| 全部 4 端 | Module Federation shell + remote 架构设计；路由骨架（4 端路由表对照）；共享组件库（错误边界 ErrorBoundary、Loading 骨架屏、Empty 空态、权限控制组件）；`usePermission().hasPermission()` 统一权限 Hook；API 请求层统一错误处理（toast 提示）；4 端差异化对比表（导航菜单/路由/组件/数据 4 层差异） |
|
||
|
||
### coord — 协调 AI
|
||
|
||
| 职责 | 具体内容 |
|
||
| ---------------- | ------------------------------------------------------------------------------------------------------- |
|
||
| proto 契约维护 | 统一管理 `packages/shared-proto/`，跨 AI 的 proto 变更唯一入口 |
|
||
| 设计文档交叉审查 | 审查 7 份模块架构设计文档的跨模块接口一致性（接口签名匹配、topic 不重复、端口不冲突、错误码前缀不重叠） |
|
||
| 黄金模板维护 | 维护 classes 黄金模板标准，审查其他服务对齐情况 |
|
||
| 架构文档同步 | 各 AI 产出设计文档后，同步更新 `004_architecture_impact_map.md` |
|
||
| 共享包管理 | shared-ts / shared-go / shared-py 建立与维护 |
|
||
| CI/CD | `.github/workflows/ci.yml` 覆盖全部 15 服务 |
|
||
| 基础设施 | `infra/` K8s/Grafana/WAF/灾备（可由 SRE AI 协助） |
|
||
|
||
---
|
||
|
||
## 6. 阶段 1 交付物模板
|
||
|
||
每个 AI 按需阅读完 §4 对应文档后，必须产出以下确认书：
|
||
|
||
```markdown
|
||
## 模块理解确认书 — [模块名]
|
||
|
||
### 1. 我在架构中的位置
|
||
|
||
- 层级：Gateway / BFF / Service / Data / Frontend
|
||
- 上游：谁调用我？
|
||
- 下游：我调用谁？
|
||
- 通信方式：HTTP / gRPC / Kafka / WebSocket / 直接 DB？
|
||
|
||
### 2. 我的限界上下文
|
||
|
||
- 我负责哪些聚合/实体？
|
||
- 我的数据属于哪个业务领域（D1-D6 中的哪个）？
|
||
- 我不负责什么（明确边界外的东西）？
|
||
|
||
### 3. 我与外部的契约
|
||
|
||
- 我消费哪些 proto message（从 shared-proto）？
|
||
- 我暴露哪些 API 端点或 gRPC 方法或 Kafka 事件？
|
||
- 错误码前缀是什么？
|
||
|
||
### 4. 我的技术栈
|
||
|
||
- 语言 / 框架 / ORM / 存储
|
||
|
||
### 5. 我的阶段归属
|
||
|
||
- 属于 P1-P6 哪个阶段？
|
||
- 当前阶段目标是什么？
|
||
- 依赖哪些上游阶段的产出？
|
||
|
||
### 6. 我需要对齐的黄金模板项（对照 classes 服务）
|
||
|
||
- [ ] 权限装饰器 @RequirePermission（全部 Controller 方法）
|
||
- [ ] 错误码前缀统一
|
||
- [ ] logger / metrics / tracer 三支柱
|
||
- [ ] /healthz + /readyz 健康检查
|
||
- [ ] 优雅关闭（SIGTERM）
|
||
- [ ] 测试覆盖率 ≥ 80%
|
||
- [ ] Dockerfile 多阶段构建
|
||
- [ ] Zod 输入验证
|
||
- [ ] GlobalErrorFilter 统一兜底
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 阶段 2 交付物模板
|
||
|
||
每个 AI 在阶段 1 确认书通过 coord 审核后，产出以下架构设计文档：
|
||
|
||
```markdown
|
||
## 模块架构设计文档 — [模块名]
|
||
|
||
### 1. 模块内部分层图
|
||
|
||
[画图：Controller → Guard → Service → Repository → DB 调用链]
|
||
[标注中间件、Guard、Filter 的拦截点]
|
||
|
||
### 2. 领域模型
|
||
|
||
- 聚合根：有哪些？
|
||
- 实体/值对象：有哪些？
|
||
- 聚合间如何通信？（同服务内直接调用 / 跨服务走事件）
|
||
|
||
### 3. 数据模型
|
||
|
||
- 有哪些表？（列出 schema，标注字段类型、约束）
|
||
- 每张表的索引策略（主键、唯一索引、查询索引）
|
||
- 读写分离策略（哪些走主库、哪些走读模型）
|
||
|
||
### 4. API 设计
|
||
|
||
| method | path | 权限 | 请求/响应结构 | 说明 |
|
||
| ------ | ---- | ---------- | ------------- | ---- |
|
||
| POST | /xxx | XXX_CREATE | { ... } | ... |
|
||
|
||
### 5. 事件设计（如适用）
|
||
|
||
- 我发布哪些领域事件？触发时机是什么？
|
||
- 我消费哪些外部事件？消费后做什么？
|
||
- 事件 Topic 名称（遵循 `edu.<domain>.<aggregate>.<action>` 格式）
|
||
|
||
### 6. 横切关注点对齐清单
|
||
|
||
- [ ] 权限装饰器（列出所有端点及对应权限常量）
|
||
- [ ] 错误码清单（带前缀，每个错误码 → 触发条件 → HTTP 状态码）
|
||
- [ ] Logger 初始化位置与配置（pino/zap/structlog）
|
||
- [ ] Metrics 指标清单（指标名 / 类型 / 标签 / 描述）
|
||
- [ ] Tracer 初始化位置（OTLP endpoint）
|
||
- [ ] /healthz 检查逻辑
|
||
- [ ] /readyz 检查逻辑（DB SELECT 1 / Redis PING / Kafka 连接）
|
||
- [ ] 优雅关闭顺序（HTTP server → DB → Redis → Kafka）
|
||
|
||
### 7. 与其他模块的交互点（契约清单）
|
||
|
||
| 方向 | 对方服务 | 协议 | 接口/事件 | 用途 |
|
||
| ------ | -------- | ----- | --------- | ---- |
|
||
| 调用 | xxx | gRPC | XxxMethod | ... |
|
||
| 被调用 | xxx | gRPC | YyyMethod | ... |
|
||
| 发布 | — | Kafka | topic 名 | ... |
|
||
| 消费 | — | Kafka | topic 名 | ... |
|
||
|
||
### 8. 风险与假设
|
||
|
||
- 我假设 [某服务] 提供了 [某接口]，如果没提供我的 fallback 是什么？
|
||
- 我的模块有哪些技术风险？（性能瓶颈、数据一致性、外部依赖）
|
||
- 有哪些未决的设计决策需要协调 AI 仲裁？
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 交叉审查规则
|
||
|
||
coord 收到全部 7 份设计文档后，执行以下审查：
|
||
|
||
### 8.1 接口一致性检查
|
||
|
||
```markdown
|
||
| 服务 A 说 | 服务 B 说 | 是否匹配 |
|
||
| --------------------------------------------------------- | ---------------------------------------------- | --------- |
|
||
| ai02 iam: 暴露 getUserInfo(userId) | ai03 teacher-bff: 调用 iam.getUserInfo(userId) | ✅ |
|
||
| ai03 core-edu: 调用 content.getKnowledgePoints(subjectId) | ai05 content: ??? | ⚠️ 待确认 |
|
||
```
|
||
|
||
### 8.2 全局冲突检查
|
||
|
||
| 检查项 | 检查方式 |
|
||
| -------------------- | ---------------------------------------------------------------------- |
|
||
| 端口不冲突 | 对照 [full-stack-runbook](../standards/full-stack-runbook.md) 端口矩阵 |
|
||
| Topic 不重复 | 汇总全部 AI 的 §5 事件设计，去重检查 |
|
||
| 错误码前缀不重叠 | 汇总全部 AI 的 §6 错误码清单，前缀唯一性检查 |
|
||
| Proto message 不遗漏 | 检查全部"跨模块交互点"是否在 proto 中有对应定义 |
|
||
|
||
### 8.3 黄金模板对齐检查
|
||
|
||
| 检查项 | 全部 TS NestJS 服务 |
|
||
| ----------------------- | ---------------------- |
|
||
| @RequirePermission 覆盖 | 每个 Controller 方法 |
|
||
| 错误码前缀 | 用服务名大写前缀 |
|
||
| /healthz + /readyz | 存在且逻辑正确 |
|
||
| Zod 输入验证 | Controller 层解析 body |
|
||
| GlobalErrorFilter | 注册到 AppModule |
|
||
| Dockerfile 多阶段 | builder + runtime |
|
||
|
||
---
|
||
|
||
## 9. 协作规则
|
||
|
||
> **默认多 AI 协作**：所有 AI 工作默认按多 AI 合作模式进行，详见 [multi-ai-collaboration.md](../standards/multi-ai-collaboration.md)。
|
||
|
||
### 9.1 分支并行开发
|
||
|
||
采用**分支开发**模式，人类决策者维护分支：
|
||
|
||
- 人类决策者为每个任务/模块创建分支并分配给 AI
|
||
- **AI 禁止** `git checkout -b`、`git switch`、`git branch`、`git merge`、`git push origin main`
|
||
- AI 在分配的分支上 `git add` → `git commit` 提交，完成后通知人类合并
|
||
- 每个 AI 只能修改自己负责的目录（见 §3.2）
|
||
- `packages/shared-proto/` 仅 coord 修改，其他 AI 只读
|
||
- `docs/`、`.trae/`、`infra/`、`.github/` 仅 coord 修改
|
||
|
||
### 9.2 唯一冲突文件处理
|
||
|
||
`pnpm-lock.yaml` 是唯一可能多 AI 同时修改的文件，冲突时由**人类决策者**在合并时解决：
|
||
|
||
```bash
|
||
# 人类决策者操作（AI 不执行）
|
||
git checkout main
|
||
git merge <branch>
|
||
# 冲突时：
|
||
git checkout --theirs pnpm-lock.yaml # 取分支版本
|
||
pnpm install # 重新生成
|
||
git add pnpm-lock.yaml
|
||
git commit
|
||
```
|
||
|
||
### 9.3 提交规范
|
||
|
||
```bash
|
||
# 每个 AI 在自己的服务目录内工作（在分配的分支上）
|
||
git add services/<service>/...
|
||
git commit -m "docs(<service>): 模块架构设计文档"
|
||
|
||
# 或
|
||
git commit -m "docs(<service>): 阶段1理解确认书"
|
||
# 完成后通知人类决策者合并
|
||
```
|
||
|
||
> **不标注 AI 身份**：commit message 不追加 `AI-Agent:` 等身份字段，经验沉淀不出现 AI 标识。
|
||
|
||
### 9.4 proto 变更流程
|
||
|
||
任何 AI 需要新增/修改 proto：
|
||
|
||
1. 在共享协调渠道声明需求（格式：`# proto-change: <描述>`）
|
||
2. coord 统一修改 `packages/shared-proto/`
|
||
3. coord 通知受影响 AI 更新设计文档
|
||
|
||
---
|
||
|
||
## 10. 审计模板（阶段 1 自检用）
|
||
|
||
每个 AI 审计自己负责的已实现服务时，填写下表：
|
||
|
||
```markdown
|
||
## 服务审计表 — [AI标识]
|
||
|
||
| 服务 | 权限装饰器 | 错误码前缀 | logger | metrics | tracer | /healthz | /readyz | 优雅关闭 | 测试覆盖率 | Dockerfile |
|
||
| ---- | ---------- | ---------- | -------- | -------- | -------- | -------- | -------- | -------- | ---------- | ---------- |
|
||
| xxx | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | XX% | ✅/❌/⚠️ |
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 相关文档
|
||
|
||
- [多 AI 协作指南](../standards/multi-ai-collaboration.md) — 日常开发协作流程
|
||
- [004 架构影响地图](./004_architecture_impact_map.md) — 全局架构与依赖
|
||
- [项目规则](../../.trae/rules/project_rules.md) — 强制约束
|
||
- [编码规范](../standards/coding-standards.md) — 多语言编码标准
|
||
- [待开发功能路线图](./roadmap/pending-features.md) — 六阶段目标
|