465 lines
38 KiB
Markdown
465 lines
38 KiB
Markdown
# AI 分配方案与架构设计外包流程
|
||
|
||
> 版本：2.0
|
||
> 日期：2026-07-10
|
||
> 适用范围：Edu 微服务项目（15 AI + 1 coord 全并行开发模式）
|
||
> 关联文档：[多 AI 协作指南](../standards/multi-ai-collaboration.md)、[004 架构影响地图](./004_architecture_impact_map.md)、[待开发功能路线图](./roadmap/pending-features.md)、[总裁最终裁决](./president-final-rulings.md)、[AI 工作顺序协同规划](./ai-work-orchestration.md)、[coord 仲裁汇总](./issues/coord.md)、[总工作安排](./issues/workline.md)、[上下游对接总矩阵](./issues/matrix.md)
|
||
>
|
||
> **状态说明**：架构设计外包三阶段（模块理解 → 模块架构设计 → 按图实施）已实施完成。当前进入**全并行开发模式**：各 AI 一口气完成自己模块从 P2 到 P6 的所有代码，开发期间用 mock，最后统一集成测试。
|
||
|
||
---
|
||
|
||
## 1. 全并行开发模式
|
||
|
||
```
|
||
各 AI 独立开发（全并行） coord 协调
|
||
│ │
|
||
读取自己的 contract.md 维护 proto 契约
|
||
在 workline.md 规划全阶段任务 仲裁异议（objections/）
|
||
开发期间用 mock（见 contract.md §4） 汇总就绪信号（matrix.md §8）
|
||
│ │
|
||
▼ ▼
|
||
交付：完整代码 + 就绪信号 交付：契约 + 仲裁 + 总矩阵
|
||
│ │
|
||
└──────────► 统一集成测试 ◄─────────────┘
|
||
```
|
||
|
||
**核心原则**：
|
||
|
||
- 各 AI 一口气完成自己模块从 P2 到 P6 的所有代码
|
||
- 开发期间消费上游的 mock（gRPC mock / MSW / Kafka mock）
|
||
- 上游就绪后在 `issues/matrix.md` §8 更新就绪信号
|
||
- 所有模块就绪后统一集成测试（见 `issues/matrix.md` §9 检查清单）
|
||
|
||
---
|
||
|
||
## 2. 完整服务清单
|
||
|
||
| 类别 | 服务名 | 语言/框架 | 限界上下文 | 阶段 | HTTP 端口 | gRPC 端口 | 负责 AI |
|
||
| ---- | -------------- | ---------------- | ---------------------- | ------ | --------- | --------- | ------- |
|
||
| 网关 | api-gateway | Go (Gin) | API 网关 | P2 | 8080 | — | ai01 |
|
||
| 网关 | push-gateway | Go (Gin) | 推送网关 | P5 | 8081 | — | ai02 |
|
||
| BFF | teacher-bff | TS (NestJS) | 教学场景域聚合 | P2 | 3003 | — | ai03 |
|
||
| BFF | student-bff | TS (NestJS) | 学习场景域聚合 | P3 | 3009 | — | ai04 |
|
||
| BFF | parent-bff | TS (NestJS) | 家长场景域聚合 | P4 | 3010 | — | ai05 |
|
||
| 业务 | iam | TS (NestJS) | 身份认证 | P2 | 3002 | 50052 | ai06 |
|
||
| 业务 | core-edu | TS (NestJS) | 教学核心（含 classes） | P3 | 3004 | 50053 | ai08 |
|
||
| 业务 | content | TS (NestJS) | 内容资源 | P4 | 3005 | 50054 | ai09 |
|
||
| 业务 | msg | TS (NestJS) | 消息通知 | P5 | 3007 | 50056 | ai10 |
|
||
| 业务 | data-ana | Python (FastAPI) | 数据分析 | P4 | 3006 | 50055 | ai11 |
|
||
| 业务 | ai | Python (FastAPI) | AI 网关 | P5 | 3008 | 50057 | ai12 |
|
||
| 前端 | teacher-portal | TS (Next.js) | 教学场景域前端 | P2 | 4000 | — | ai13 |
|
||
| 前端 | student-portal | TS (Next.js) | 学习场景域前端 | P3 | 4001 | — | ai14 |
|
||
| 前端 | parent-portal | TS (Next.js) | 家长场景域前端 | P4 | 4002 | — | ai15 |
|
||
| 前端 | admin-portal | TS (Next.js) | 管理场景域前端 | P6 | 4003 | — | ai16 |
|
||
| 共享 | shared-proto | protobuf | 契约 | 跨阶段 | — | — | coord |
|
||
| 共享 | shared-ts | TS | TS 共享工具 | 跨阶段 | — | — | coord |
|
||
| 共享 | shared-go | Go | Go 共享工具 | 跨阶段 | — | — | coord |
|
||
| 共享 | shared-py | Python | Python 共享工具 | 跨阶段 | — | — | coord |
|
||
| 共享 | ui-tokens | TS | 设计令牌 | 跨阶段 | — | — | coord |
|
||
| 共享 | ui-components | TS | UI 组件库 | 跨阶段 | — | — | ai13 |
|
||
| 共享 | hooks | TS | React Hooks 库 | 跨阶段 | — | — | ai13 |
|
||
| 基础 | infra | — | K8s/Grafana/WAF | 跨阶段 | — | — | coord |
|
||
|
||
> **注**：classes 模块已合并到 core-edu（ai08 负责），不再独立分配 AI。
|
||
|
||
---
|
||
|
||
## 3. AI 分配方案（15 AI + 1 coord）
|
||
|
||
### 3.1 分配原则
|
||
|
||
- **单一负责制**：每个模块（限界上下文）只有一个 AI 负责，禁止并行修改同一模块
|
||
- **同语言内聚**：一个 AI 负责同语言服务，学习成本只付一次
|
||
- **领域亲缘性**：同类业务放一起（BFF 归 BFF、Python 归 Python）
|
||
- **工作负载均衡**：复杂服务（Neo4j+ES 的 content、ClickHouse 的 data-ana）独立分配
|
||
- **前端统一**：Module Federation 微前端由各自 AI 负责，teacher-portal 作为 Shell 由 ai13 统一设计
|
||
- **coord 不写业务代码**：专注契约管理 + 仲裁 + 共享包
|
||
|
||
### 3.2 分配矩阵
|
||
|
||
| AI 标识 | 语言 | 服务 | 阶段 | gRPC 端口 |
|
||
| --------- | ------ | ----------------------- | --------- | --------- |
|
||
| **ai01** | Go | api-gateway | P2 | — |
|
||
| **ai02** | Go | push-gateway | P5 | — |
|
||
| **ai03** | TS | teacher-bff | P2+扩展 | — |
|
||
| **ai04** | TS | student-bff | P3 | — |
|
||
| **ai05** | TS | parent-bff | P4 | — |
|
||
| **ai06** | TS | iam | P2.1+P2.2 | 50052 |
|
||
| **ai08** | TS | core-edu | P3 | 50053 |
|
||
| **ai09** | TS | content | P4 | 50054 |
|
||
| **ai10** | TS | msg | P5 | 50056 |
|
||
| **ai11** | Python | data-ana | P4 | 50055 |
|
||
| **ai12** | Python | ai | P5 | 50057 |
|
||
| **ai13** | TS | teacher-portal | P2+扩展 | — |
|
||
| **ai14** | TS | student-portal | P3 | — |
|
||
| **ai15** | TS | parent-portal | P4 | — |
|
||
| **ai16** | TS | admin-portal | P6 | — |
|
||
| **coord** | — | shared-* / infra / docs | 跨阶段 | — |
|
||
|
||
### 3.3 为什么这样拆
|
||
|
||
| 决策 | 理由 |
|
||
| ---------------------------- | ------------------------------------------------------------------------------- |
|
||
| ai01 独立负责 api-gateway | Go 网关层，路由 + JWT 验签 + 限流，接入 shared-go |
|
||
| ai02 独立负责 push-gateway | Go 推送网关，WebSocket/SSE + 多设备会话隔离 + 审计表 |
|
||
| ai03 独立负责 teacher-bff | 教学场景域 BFF，GraphQL schema + DataLoader + ActionState + admin 命名空间 |
|
||
| ai04 独立负责 student-bff | 学习场景域 BFF，GraphQL + 考试作答 + 作业提交 |
|
||
| ai05 独立负责 parent-bff | 家长场景域 BFF，GraphQL + 多子女切换 + 成绩趋势 |
|
||
| ai06 独立负责 iam | RBAC + DataScope + JWT RS256 + gRPC 12 RPC + 审计日志，权限中枢复杂度最高 |
|
||
| ai08 独立负责 core-edu | 教学核心（含原 classes 模块），5 Service 22 RPC + Outbox + 考试/作业/成绩状态机 |
|
||
| ai09 独立负责 content | 内容资源，4 Service 18 RPC + Neo4j 知识图谱 + ES 题库检索 |
|
||
| ai10 独立负责 msg | 消息通知，3 Service 13 RPC + Outbox + 多渠道通知 |
|
||
| ai11 独立负责 data-ana | Python 数据分析，12 RPC + ClickHouse 宽表 + CDC 消费 |
|
||
| ai12 独立负责 ai | Python AI 网关，6 RPC + ES 检索 + LLM 网关 + 流式响应 |
|
||
| ai13 独立负责 teacher-portal | MF Shell + GraphQL client 单例 + AppShell + 共享组件库 |
|
||
| ai14 独立负责 student-portal | MF Remote + 考试作答 + 作业提交 |
|
||
| ai15 独立负责 parent-portal | MF Remote + Dashboard + 多子女切换 |
|
||
| ai16 独立负责 admin-portal | MF Remote + 用户管理 + 角色权限 + 审计日志 |
|
||
| coord 不写业务代码 | 专注 proto 契约 + 仲裁 + shared-* 包 + infra + 文档体系 |
|
||
|
||
---
|
||
|
||
## 4. 各 AI 文档阅读清单（按需阅读）
|
||
|
||
> **架构文档按需阅读原则**（见 [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 | [president-final-rulings.md](./president-final-rulings.md) | 总裁最终裁决（70+ 问题逐个裁决 + 时间统筹 + 15 AI 工作清单） |
|
||
|
||
### 4.2 模块开发按需阅读（只读自己模块，禁止读其他模块内部实现）
|
||
|
||
| AI | 必读文档 | 说明 |
|
||
| ---- | ------------------------------------------------------------------------------------------------------------------ | --------------- |
|
||
| ai01 | `services/api-gateway/README.md`、004 §网关层章节、[contract](./issues/contracts/api-gateway_contract.md) | Go 网关层架构 |
|
||
| ai02 | `services/push-gateway/README.md`、004 §push-gateway 章节、[contract](./issues/contracts/push-gateway_contract.md) | Go 推送网关架构 |
|
||
| ai03 | `services/teacher-bff/README.md`、004 §teacher-bff 章节、[contract](./issues/contracts/teacher-bff_contract.md) | 教学场景域 BFF |
|
||
| ai04 | 004 §student-bff 章节、[contract](./issues/contracts/student-bff_contract.md) | 学习场景域 BFF |
|
||
| ai05 | 004 §parent-bff 章节、[contract](./issues/contracts/parent-bff_contract.md) | 家长场景域 BFF |
|
||
| ai06 | `services/iam/README.md`、004 §iam 章节、[contract](./issues/contracts/iam_contract.md) | 身份认证架构 |
|
||
| ai08 | `services/core-edu/README.md`、004 §core-edu 章节、[contract](./issues/contracts/core-edu_contract.md) | 教学核心架构 |
|
||
| ai09 | 004 §content 章节、[contract](./issues/contracts/content_contract.md) | 内容资源架构 |
|
||
| ai10 | 004 §msg 章节、[contract](./issues/contracts/msg_contract.md) | 消息通知架构 |
|
||
| ai11 | `services/data-ana/README.md`、004 §data-ana 章节、[contract](./issues/contracts/data-ana_contract.md) | Python 数据分析 |
|
||
| ai12 | 004 §ai 章节、[contract](./issues/contracts/ai_contract.md) | Python AI 网关 |
|
||
| ai13 | `apps/teacher-portal/README.md`、004 §前端章节、[contract](./issues/contracts/teacher-portal_contract.md) | 教师端前端 |
|
||
| ai14 | 004 §前端章节、[contract](./issues/contracts/student-portal_contract.md) | 学生端前端 |
|
||
| ai15 | 004 §前端章节、[contract](./issues/contracts/parent-portal_contract.md) | 家长端前端 |
|
||
| ai16 | 004 §前端章节、[contract](./issues/contracts/admin-portal_contract.md) | 管理端前端 |
|
||
|
||
> **禁止越界阅读**：上表只列自己模块。如需确认与某模块的契约，走 §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) | 六阶段路线图 |
|
||
| 5 | [ai-work-orchestration.md](./ai-work-orchestration.md) | AI 工作顺序协同规划 |
|
||
| 6 | [issues/coord.md](./issues/coord.md) | coord 仲裁汇总 |
|
||
| 7 | [issues/matrix.md](./issues/matrix.md) | 上下游对接总矩阵 |
|
||
|
||
### 4.4 跨模块契约按需阅读（仅涉及 proto 变更或确认接口时）
|
||
|
||
| 场景 | 必读文档 |
|
||
| ----------------------- | --------------------------------------------------------------------------------------- |
|
||
| 修改/新增 proto message | `packages/shared-proto/proto/` 中**相关** .proto 文件（不读全部，只读变更涉及的文件） |
|
||
| 确认与其他模块的接口 | [issues/contracts/](./issues/contracts/) 中对方模块的 contract.md + 004 §跨模块交互章节 |
|
||
| 确认上下游依赖 | [issues/matrix.md](./issues/matrix.md) §1 服务依赖图 + §2-§5 接口矩阵 |
|
||
|
||
### 4.5 黄金模板参考（仅 TS 服务首次实现新服务时）
|
||
|
||
| AI | 参考文档 |
|
||
| ---------------------------- | ---------------------------------------------------------------------------------- |
|
||
| ai03-05, ai08-10（TS 服务） | `services/classes/src/` 黄金模板源码（首次实现新服务时参考横切关注点，不强制全读） |
|
||
| ai01 / ai02 / ai06 / ai11-16 | 按需参考 classes 的横切关注点实现模式（错误处理/可观测/健康检查等），不强制读源码 |
|
||
|
||
---
|
||
|
||
## 5. 各 AI 全阶段设计重点
|
||
|
||
### ai01 — api-gateway（Go）
|
||
|
||
| 设计重点 |
|
||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 路由表矩阵（路径 → 下游服务 + 端口，需覆盖全部 6 个业务服务 + 3 个 BFF）；限流策略表（每路由 QPS）；熔断阈值配置（错误率/延迟阈值）；JWT RS256 公钥校验流程（shared-go/jwks）；CORS 白名单；请求 ID 注入；接入 shared-go（env/logger/tracer） |
|
||
|
||
### ai02 — push-gateway（Go）
|
||
|
||
| 设计重点 |
|
||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| HTTP /internal/* + Kafka 双通道；WebSocket/SSE 连接生命周期（认证 → 心跳 → 断线重连）；多设备会话隔离策略；Redis Pub/Sub 跨实例广播；X-Internal-Key 认证；审计表（6 字段）；ActionState 信封响应 |
|
||
|
||
### ai03 — teacher-bff（TS）
|
||
|
||
| 设计重点 |
|
||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| GraphQL schema（SDL-first，存放 packages/shared-ts/contracts/graphql/）；DataLoader 批量去重策略；并行 gRPC 调用编排；ActionState 信封 + 降级模式 B；admin schema 命名空间预留（P6）；DownstreamClient 抽象；depth ≤ 7 + cost ≤ 1000 |
|
||
|
||
### ai04 — student-bff（TS）
|
||
|
||
| 设计重点 |
|
||
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 学生端 GraphQL schema；DataLoader 复用 teacher-bff 模式；权限区分（学生只能看自己的数据，DataScope=SELF）；考试/作业/成绩的学生视角 API；DownstreamClient 复用 |
|
||
|
||
### ai05 — parent-bff（TS）
|
||
|
||
| 设计重点 |
|
||
| --------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 家长端 GraphQL schema；与 iam 的学生-家长关联查询（GetChildrenByParent）；多子女账户切换设计；家长通知偏好配置；DataScope=CHILDREN 过滤 |
|
||
|
||
### ai06 — iam（TS）
|
||
|
||
| 设计重点 |
|
||
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| RBAC 权限点枚举（全部模块的 CRUD 权限常量）；三层角色模型（系统/组织/临时）权限合并规则；DataScope 6 级 SQL WHERE 注入规则；视口 4 层配置表设计；JWT RS256 私钥签发 + 公钥暴露端点（GetPublicKey RPC）；gRPC 50052 + 12 RPC；iam_student_guardians 表；审计日志（AuditEvent + topic edu.iam.audit.created）；shared-ts Outbox 接入；/readyz 5 项依赖检查 |
|
||
|
||
### ai08 — core-edu（TS）
|
||
|
||
| 设计重点 |
|
||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| classes 模块黄金模板对齐；gRPC 50053 + 5 Service 22 RPC（ClassService + ExamService + HomeworkService + GradeService + AttendanceService）；考试生命周期状态机；Outbox 事件定义（ExamEvent/HomeworkEvent/GradeEvent/ClassEvent）；TOPIC_MAP 修订（edu.teaching.* 命名）；成绩计算公式与配置化 |
|
||
|
||
### ai09 — content（TS）
|
||
|
||
| 设计重点 |
|
||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| gRPC 50054 + 4 Service 18 RPC（TextbookService + ChapterService + KnowledgeGraphService + QuestionService）；Neo4j 图模型（知识点 → 前置依赖 → 教材关联）；ES 索引 mapping 设计（题库全文检索 + 标签过滤）；Outbox（KnowledgePointEvent + QuestionEvent）；Neo4j Sync Worker + ES Sync Worker；/readyz（MySQL + Neo4j + Kafka） |
|
||
|
||
### ai10 — msg（TS）
|
||
|
||
| 设计重点 |
|
||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| gRPC 50056 + 3 Service 13 RPC（NotificationService + NotificationPreferenceService + NotificationTemplateService）；通知渠道抽象（站内信/邮件/短信，策略模式）；Kafka 消费幂等设计（event_id 去重）；Outbox（NotificationEvent）；与 push-gateway 的 /internal/push 通道；通知模板管理；已读/未读状态管理 |
|
||
|
||
### ai11 — data-ana（Python）
|
||
|
||
| 设计重点 |
|
||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| gRPC 50055 + 12 RPC（含 Server Streaming SubscribeMasteryUpdate）；ClickHouse 宽表设计（考试、作业、成绩、掌握度、出勤 5 张宽表）；CDC 消费者架构（Debezium → Kafka → ClickHouse）；学情分析 API（班级统计/个人趋势/预警阈值）；掌握度计算算法（加权滑动平均）；Dashboard 数据聚合；降级模式（ClickHouse 不可用时降级）；MasteryEvent + AIUsageEvent（豁免 Outbox） |
|
||
|
||
### ai12 — ai（Python）
|
||
|
||
| 设计重点 |
|
||
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| gRPC 50057 + 6 RPC（含 StreamGenerateQuestion + StreamChat）；LLM Provider 适配器模式（OpenAI/百川/本地模型）；SSE 流式响应（题目逐字生成）；出题 Prompt 模板管理；备课工作流（分析学情 → 推荐知识点 → 生成题目 → 教师审核 → 入库）；用量计费/频率限制；AIUsageEvent（豁免 Outbox）；接入 content + data-ana gRPC |
|
||
|
||
### ai13 — teacher-portal（TS）
|
||
|
||
| 设计重点 |
|
||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| Module Federation Shell 配置（exposes + shared，无 remotes）；GraphQLProvider + urql client 单例；AppShell 改造（REST → GraphQL）；登录页 + Dashboard + 班级列表；共享组件库（packages/ui-components + packages/hooks + packages/ui-tokens）；feature flag NEXT_PUBLIC_MF_ENABLED；P3+ 扩展（考试/作业/成绩/学情/推送/AI 页面） |
|
||
|
||
### ai14 — student-portal（TS）
|
||
|
||
| 设计重点 |
|
||
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| MF Remote；7 页（dashboard/homework/exams/take/result/grades/my-schedule）；复用 teacher-portal Shell 暴露的 GraphQLProvider + AppShell + 共享组件；学生端权限（DataScope=SELF） |
|
||
|
||
### ai15 — parent-portal（TS）
|
||
|
||
| 设计重点 |
|
||
| ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| MF Remote；Dashboard + 孩子列表 + 考试/作业/成绩 + 通知偏好 UI 占位；复用 teacher-portal Shell；多子女切换 UI；家长端权限（DataScope=CHILDREN） |
|
||
|
||
### ai16 — admin-portal（TS）
|
||
|
||
| 设计重点 |
|
||
| --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| MF Remote；用户管理 + 角色权限管理 + 学校设置 + 组织管理 + 审计日志消费；复用 teacher-bff GraphQL endpoint（admin 命名空间）；admin 权限点（ADMIN_ 前缀） |
|
||
|
||
### coord — 协调 AI
|
||
|
||
| 职责 | 具体内容 |
|
||
| -------------- | ----------------------------------------------------------------------------- |
|
||
| proto 契约维护 | 统一管理 `packages/shared-proto/`，跨 AI 的 proto 变更唯一入口 |
|
||
| 仲裁汇总 | 审阅 `issues/objections/` 各 AI 提请的异议，在 `issues/coord.md` 写入仲裁结果 |
|
||
| 总矩阵维护 | 维护 `issues/matrix.md` 上下游对接总矩阵 + 就绪信号跟踪 |
|
||
| 共享包管理 | shared-proto / shared-ts / shared-go / shared-py / ui-tokens 建立与维护 |
|
||
| 架构文档同步 | 各 AI 产出后，同步更新 `004_architecture_impact_map.md` |
|
||
| CI/CD | `.github/workflows/ci.yml` 覆盖全部 15 服务 |
|
||
| 基础设施 | `infra/` K8s/Grafana/WAF/灾备（可由 SRE AI 协助） |
|
||
|
||
---
|
||
|
||
## 6. 协作文档体系
|
||
|
||
### 6.1 目录结构
|
||
|
||
```
|
||
docs/architecture/issues/
|
||
├── coord.md # coord 仲裁汇总
|
||
├── workline.md # 总工作安排（15 AI 甘特图）
|
||
├── matrix.md # 上下游对接总矩阵
|
||
├── objections/ # 各模块问题/异议（AI 提请，coord 仲裁）
|
||
│ ├── [模块名]_issue.md # 15 个模块各一个
|
||
│ └── cross_issue.md # 跨模块问题
|
||
├── worklines/ # 各模块工作排期（AI 自己写，覆盖 P2-P6 全阶段）
|
||
│ └── [模块名]_workline.md # 15 个模块各一个
|
||
└── contracts/ # 各模块对接契约（我提供什么 + 我消费什么 + mock 策略）
|
||
└── [模块名]_contract.md # 15 个模块各一个
|
||
```
|
||
|
||
### 6.2 三类文档职责
|
||
|
||
| 文档类型 | 子文件夹 | 维护方 | 内容 |
|
||
| ---------------- | ------------- | ---------------------- | ---------------------------------------------- |
|
||
| issue（异议） | `objections/` | 各 AI 提请，coord 仲裁 | 遇到问题时追加条目，coord 仲裁后更新状态 |
|
||
| workline（排期） | `worklines/` | 各 AI 自己写 | 全阶段甘特图 + 详细任务 + 依赖与就绪信号 |
|
||
| contract（契约） | `contracts/` | 各 AI 维护 | 我提供什么 + 我消费什么 + mock 策略 + 就绪信号 |
|
||
|
||
### 6.3 全并行开发工作流
|
||
|
||
1. 各 AI 读取自己的 `contracts/[模块名]_contract.md` 了解上下游接口
|
||
2. 各 AI 在 `worklines/[模块名]_workline.md` 详细规划全阶段任务
|
||
3. 开发期间消费上游的 mock（见 contract.md §4 mock 策略）
|
||
4. 上游就绪后在 `matrix.md` §8 更新就绪信号
|
||
5. 所有模块就绪后统一集成测试（见 `matrix.md` §9 检查清单）
|
||
|
||
### 6.4 遇到问题
|
||
|
||
各 AI 在 `objections/[模块名]_issue.md` 追加异议条目 → coord 审阅 → 在 `coord.md` 写入仲裁结果 → 各 AI 按仲裁结果执行。
|
||
|
||
---
|
||
|
||
## 7. 交叉审查规则
|
||
|
||
### 7.1 coord 定期审查
|
||
|
||
coord 收到各 AI 的 contract.md 后，执行以下审查：
|
||
|
||
| 检查项 | 检查方式 |
|
||
| -------------------- | --------------------------------------------------------------- |
|
||
| 端口不冲突 | 对照 [port-allocation](../../infra/port-allocation.md) 端口矩阵 |
|
||
| gRPC 端口不冲突 | 50052-50057 一一对应 |
|
||
| Topic 不重复 | 汇总全部 AI 的 Kafka 事件，去重检查（见 matrix.md §4） |
|
||
| 错误码前缀不重叠 | 汇总全部 AI 的错误码前缀，唯一性检查（见 matrix.md §6） |
|
||
| Proto message 不遗漏 | 检查全部"跨模块交互点"是否在 proto 中有对应定义 |
|
||
| 就绪信号可验证 | 检查每个 AI 的就绪信号是否可验证（见 matrix.md §8） |
|
||
|
||
### 7.2 AI 间契约确认
|
||
|
||
当 AI A 需要确认与 AI B 的接口时：
|
||
|
||
1. 读 AI B 的 `contracts/[B模块名]_contract.md`
|
||
2. 如有疑问，在 `objections/cross_issue.md` 追加条目
|
||
3. coord 仲裁后在 `coord.md` 写入结论
|
||
|
||
---
|
||
|
||
## 8. 协作规则
|
||
|
||
> **默认多 AI 协作**：所有 AI 工作默认按多 AI 合作模式进行，详见 [multi-ai-collaboration.md](../standards/multi-ai-collaboration.md)。
|
||
|
||
### 8.1 分支并行开发
|
||
|
||
采用**长期分支**模式，共 17 个分支（15 模块 + coord + 集成）：
|
||
|
||
| 分支名 | 负责 AI | 用途 |
|
||
| -------------------------- | ------- | --------------------------- |
|
||
| `feat/api-gateway-ai01` | ai01 | api-gateway 开发 |
|
||
| `feat/push-gateway-ai02` | ai02 | push-gateway 开发 |
|
||
| `feat/teacher-bff-ai03` | ai03 | teacher-bff 开发 |
|
||
| `feat/student-bff-ai04` | ai04 | student-bff 开发 |
|
||
| `feat/parent-bff-ai05` | ai05 | parent-bff 开发 |
|
||
| `feat/iam-ai06` | ai06 | iam 开发 |
|
||
| `feat/core-edu-ai08` | ai08 | core-edu 开发（含 classes） |
|
||
| `feat/content-ai09` | ai09 | content 开发 |
|
||
| `feat/msg-ai10` | ai10 | msg 开发 |
|
||
| `feat/data-ana-ai11` | ai11 | data-ana 开发 |
|
||
| `feat/ai-ai12` | ai12 | ai 开发 |
|
||
| `feat/teacher-portal-ai13` | ai13 | teacher-portal 开发 |
|
||
| `feat/student-portal-ai14` | ai14 | student-portal 开发 |
|
||
| `feat/parent-portal-ai15` | ai15 | parent-portal 开发 |
|
||
| `feat/admin-portal-ai16` | ai16 | admin-portal 开发 |
|
||
| `feat/coord-coord` | coord | 共享包 + 契约 + 仲裁 + 文档 |
|
||
| `release/integration` | coord | 集成分支，合并各模块到 main |
|
||
|
||
**分支规则**：
|
||
|
||
- 每个 AI 在自己的分支上 `git add` → `git commit` 提交
|
||
- **AI 禁止** `git checkout -b`、`git switch`、`git branch`、`git merge`、`git push origin main`
|
||
- 各模块分支开发完成后，由 coord 合并到 `release/integration` 进行集成测试
|
||
- 集成测试通过后，由 coord 将 `release/integration` 合并到 `main`
|
||
- 每个 AI 只能修改自己负责的目录（见 §3.2）
|
||
- `packages/shared-proto/` 仅 coord 修改，其他 AI 只读
|
||
- `docs/`、`.trae/`、`infra/`、`.github/` 仅 coord 修改
|
||
|
||
### 8.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
|
||
```
|
||
|
||
### 8.3 提交规范
|
||
|
||
```bash
|
||
# 每个 AI 在自己的服务目录内工作（在分配的分支上）
|
||
git add services/<service>/...
|
||
git commit -m "feat(<service>): 模块架构设计文档"
|
||
```
|
||
|
||
> **不标注 AI 身份**：commit message 不追加 `AI-Agent:` 等身份字段，经验沉淀不出现 AI 标识。
|
||
|
||
### 8.4 proto 变更流程
|
||
|
||
任何 AI 需要新增/修改 proto：
|
||
|
||
1. 在 `objections/cross_issue.md` 声明需求
|
||
2. coord 统一修改 `packages/shared-proto/`
|
||
3. coord 通知受影响 AI 更新 contract.md
|
||
|
||
---
|
||
|
||
## 9. 审计模板（自检用）
|
||
|
||
每个 AI 审计自己负责的服务时，填写下表：
|
||
|
||
```markdown
|
||
## 服务审计表 — [AI标识]
|
||
|
||
| 服务 | 权限装饰器 | 错误码前缀 | logger | metrics | tracer | /healthz | /readyz | 优雅关闭 | 测试覆盖率 | Dockerfile |
|
||
| ---- | ---------- | ---------- | -------- | -------- | -------- | -------- | -------- | -------- | ---------- | ---------- |
|
||
| xxx | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | XX% | ✅/❌/⚠️ |
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 相关文档
|
||
|
||
- [多 AI 协作指南](../standards/multi-ai-collaboration.md) — 日常开发协作流程
|
||
- [004 架构影响地图](./004_architecture_impact_map.md) — 全局架构与依赖
|
||
- [总裁最终裁决](./president-final-rulings.md) — 70+ 问题逐个裁决 + 时间统筹 + 15 AI 工作清单
|
||
- [AI 工作顺序协同规划](./ai-work-orchestration.md) — 6 批次并行规划（历史参考）
|
||
- [coord 强制裁决](./coord-final-decisions.md) — 80+ 项强制裁决
|
||
- [coord 交叉审查](./coord-cross-review.md) — 交叉审查结果
|
||
- [coord 仲裁汇总](./issues/coord.md) — 新流程仲裁记录
|
||
- [总工作安排](./issues/workline.md) — 15 AI 甘特图
|
||
- [上下游对接总矩阵](./issues/matrix.md) — 服务依赖 + 接口矩阵 + mock 策略
|
||
- [项目规则](../../.trae/rules/project_rules.md) — 强制约束
|
||
- [编码规范](../standards/coding-standards.md) — 多语言编码标准
|
||
- [待开发功能路线图](./roadmap/pending-features.md) — 六阶段目标
|
||
- [端口分配](../../infra/port-allocation.md) — 端口矩阵
|