Files
Edu/docs/architecture/ai-allocation.md

38 KiB
Raw Permalink Blame History

AI 分配方案与架构设计外包流程

版本2.0 日期2026-07-10 适用范围Edu 微服务项目15 AI + 1 coord 全并行开发模式) 关联文档:多 AI 协作指南004 架构影响地图待开发功能路线图总裁最终裁决AI 工作顺序协同规划coord 仲裁汇总总工作安排上下游对接总矩阵

状态说明:架构设计外包三阶段(模块理解 → 模块架构设计 → 按图实施)已实施完成。当前进入全并行开发模式:各 AI 一口气完成自己模块从 P2 到 P6 的所有代码,开发期间用 mock最后统一集成测试。


1. 全并行开发模式

各 AI 独立开发(全并行)                    coord 协调
     │                                        │
  读取自己的 contract.md                     维护 proto 契约
  在 workline.md 规划全阶段任务              仲裁异议objections/
  开发期间用 mock见 contract.md §4       汇总就绪信号matrix.md §8
     │                                        │
     ▼                                        ▼
  交付:完整代码 + 就绪信号               交付:契约 + 仲裁 + 总矩阵
     │                                        │
     └──────────► 统一集成测试 ◄─────────────┘

核心原则

  • 各 AI 一口气完成自己模块从 P2 到 P6 的所有代码
  • 开发期间消费上游的 mockgRPC 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-eduai08 负责),不再独立分配 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 教学场景域 BFFGraphQL schema + DataLoader + ActionState + admin 命名空间
ai04 独立负责 student-bff 学习场景域 BFFGraphQL + 考试作答 + 作业提交
ai05 独立负责 parent-bff 家长场景域 BFFGraphQL + 多子女切换 + 成绩趋势
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 §10multi-ai-collaboration §2.2

  • 模块开发:只读自己模块的架构与服务 README不读其他模块内部实现
  • 全局工作coord、跨模块契约、基础设施、文档体系读全局架构文档
  • 功能开发/文档书写等强依赖场景:必须读对应架构
  • 严格模块边界AI 只读自己负责模块的文档与源码仅在确认跨模块契约时才读对方的对外接口proto/API/事件),不读对方内部实现

4.1 全员必读(所有 AI无论模块开发还是全局工作

顺序 文档 说明
1 project_rules.md 项目强制约束(架构规则、编码规范、提交规范、多 AI 协作、分支开发)
2 coding-standards.md 多语言编码标准
3 multi-ai-collaboration.md 多 AI 协作指南§2.1 严格模块边界、§2.2 按需阅读、§3 分支开发规则)
4 president-final-rulings.md 总裁最终裁决70+ 问题逐个裁决 + 时间统筹 + 15 AI 工作清单)

4.2 模块开发按需阅读(只读自己模块,禁止读其他模块内部实现)

AI 必读文档 说明
ai01 services/api-gateway/README.md、004 §网关层章节、contract Go 网关层架构
ai02 services/push-gateway/README.md、004 §push-gateway 章节、contract Go 推送网关架构
ai03 services/teacher-bff/README.md、004 §teacher-bff 章节、contract 教学场景域 BFF
ai04 004 §student-bff 章节、contract 学习场景域 BFF
ai05 004 §parent-bff 章节、contract 家长场景域 BFF
ai06 services/iam/README.md、004 §iam 章节、contract 身份认证架构
ai08 services/core-edu/README.md、004 §core-edu 章节、contract 教学核心架构
ai09 004 §content 章节、contract 内容资源架构
ai10 004 §msg 章节、contract 消息通知架构
ai11 services/data-ana/README.md、004 §data-ana 章节、contract Python 数据分析
ai12 004 §ai 章节、contract Python AI 网关
ai13 apps/teacher-portal/README.md、004 §前端章节、contract 教师端前端
ai14 004 §前端章节、contract 学生端前端
ai15 004 §前端章节、contract 家长端前端
ai16 004 §前端章节、contract 管理端前端

禁止越界阅读:上表只列自己模块。如需确认与某模块的契约,走 §4.4 跨模块契约阅读,不读对方内部源码与 README。

4.3 全局工作必读(仅 coord以及 AI 执行跨模块/全局任务时)

顺序 文档 说明
1 README.md 项目总览
2 MIGRATION_GUIDE.md 迁移指南
3 004 架构影响地图 全文 全局架构与依赖coord 必读;模块开发只读 §4.2 章节)
4 pending-features.md 六阶段路线图
5 ai-work-orchestration.md AI 工作顺序协同规划
6 issues/coord.md coord 仲裁汇总
7 issues/matrix.md 上下游对接总矩阵

4.4 跨模块契约按需阅读(仅涉及 proto 变更或确认接口时)

场景 必读文档
修改/新增 proto message packages/shared-proto/proto/相关 .proto 文件(不读全部,只读变更涉及的文件)
确认与其他模块的接口 issues/contracts/ 中对方模块的 contract.md + 004 §跨模块交互章节
确认上下游依赖 issues/matrix.md §1 服务依赖图 + §2-§5 接口矩阵

4.5 黄金模板参考(仅 TS 服务首次实现新服务时)

AI 参考文档
ai03-05, ai08-10TS 服务) services/classes/src/ 黄金模板源码(首次实现新服务时参考横切关注点,不强制全读)
ai01 / ai02 / ai06 / ai11-16 按需参考 classes 的横切关注点实现模式(错误处理/可观测/健康检查等),不强制读源码

5. 各 AI 全阶段设计重点

ai01 — api-gatewayGo

设计重点
路由表矩阵(路径 → 下游服务 + 端口,需覆盖全部 6 个业务服务 + 3 个 BFF限流策略表每路由 QPS熔断阈值配置错误率/延迟阈值JWT RS256 公钥校验流程shared-go/jwksCORS 白名单;请求 ID 注入;接入 shared-goenv/logger/tracer

ai02 — push-gatewayGo

设计重点
HTTP /internal/* + Kafka 双通道WebSocket/SSE 连接生命周期(认证 → 心跳 → 断线重连多设备会话隔离策略Redis Pub/Sub 跨实例广播X-Internal-Key 认证审计表6 字段ActionState 信封响应

ai03 — teacher-bffTS

设计重点
GraphQL schemaSDL-first存放 packages/shared-ts/contracts/graphql/DataLoader 批量去重策略;并行 gRPC 调用编排ActionState 信封 + 降级模式 Badmin schema 命名空间预留P6DownstreamClient 抽象depth ≤ 7 + cost ≤ 1000

ai04 — student-bffTS

设计重点
学生端 GraphQL schemaDataLoader 复用 teacher-bff 模式权限区分学生只能看自己的数据DataScope=SELF考试/作业/成绩的学生视角 APIDownstreamClient 复用

ai05 — parent-bffTS

设计重点
家长端 GraphQL schema与 iam 的学生-家长关联查询GetChildrenByParent多子女账户切换设计家长通知偏好配置DataScope=CHILDREN 过滤

ai06 — iamTS

设计重点
RBAC 权限点枚举(全部模块的 CRUD 权限常量);三层角色模型(系统/组织/临时权限合并规则DataScope 6 级 SQL WHERE 注入规则;视口 4 层配置表设计JWT RS256 私钥签发 + 公钥暴露端点GetPublicKey RPCgRPC 50052 + 12 RPCiam_student_guardians 表审计日志AuditEvent + topic edu.iam.audit.createdshared-ts Outbox 接入;/readyz 5 项依赖检查

ai08 — core-eduTS

设计重点
classes 模块黄金模板对齐gRPC 50053 + 5 Service 22 RPCClassService + ExamService + HomeworkService + GradeService + AttendanceService考试生命周期状态机Outbox 事件定义ExamEvent/HomeworkEvent/GradeEvent/ClassEventTOPIC_MAP 修订edu.teaching.* 命名);成绩计算公式与配置化

ai09 — contentTS

设计重点
gRPC 50054 + 4 Service 18 RPCTextbookService + ChapterService + KnowledgeGraphService + QuestionServiceNeo4j 图模型(知识点 → 前置依赖 → 教材关联ES 索引 mapping 设计(题库全文检索 + 标签过滤OutboxKnowledgePointEvent + QuestionEventNeo4j Sync Worker + ES Sync Worker/readyzMySQL + Neo4j + Kafka

ai10 — msgTS

设计重点
gRPC 50056 + 3 Service 13 RPCNotificationService + NotificationPreferenceService + NotificationTemplateService通知渠道抽象站内信/邮件/短信策略模式Kafka 消费幂等设计event_id 去重OutboxNotificationEvent与 push-gateway 的 /internal/push 通道;通知模板管理;已读/未读状态管理

ai11 — data-anaPython

设计重点
gRPC 50055 + 12 RPC含 Server Streaming SubscribeMasteryUpdateClickHouse 宽表设计(考试、作业、成绩、掌握度、出勤 5 张宽表CDC 消费者架构Debezium → Kafka → ClickHouse学情分析 API班级统计/个人趋势/预警阈值掌握度计算算法加权滑动平均Dashboard 数据聚合降级模式ClickHouse 不可用时降级MasteryEvent + AIUsageEvent豁免 Outbox

ai12 — aiPython

设计重点
gRPC 50057 + 6 RPC含 StreamGenerateQuestion + StreamChatLLM Provider 适配器模式OpenAI/百川/本地模型SSE 流式响应(题目逐字生成);出题 Prompt 模板管理;备课工作流(分析学情 → 推荐知识点 → 生成题目 → 教师审核 → 入库);用量计费/频率限制AIUsageEvent豁免 Outbox接入 content + data-ana gRPC

ai13 — teacher-portalTS

设计重点
Module Federation Shell 配置exposes + shared无 remotesGraphQLProvider + urql client 单例AppShell 改造REST → GraphQL登录页 + Dashboard + 班级列表共享组件库packages/ui-components + packages/hooks + packages/ui-tokensfeature flag NEXT_PUBLIC_MF_ENABLEDP3+ 扩展(考试/作业/成绩/学情/推送/AI 页面)

ai14 — student-portalTS

设计重点
MF Remote7 页dashboard/homework/exams/take/result/grades/my-schedule复用 teacher-portal Shell 暴露的 GraphQLProvider + AppShell + 共享组件学生端权限DataScope=SELF

ai15 — parent-portalTS

设计重点
MF RemoteDashboard + 孩子列表 + 考试/作业/成绩 + 通知偏好 UI 占位;复用 teacher-portal Shell多子女切换 UI家长端权限DataScope=CHILDREN

ai16 — admin-portalTS

设计重点
MF Remote用户管理 + 角色权限管理 + 学校设置 + 组织管理 + 审计日志消费;复用 teacher-bff GraphQL endpointadmin 命名空间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 端口矩阵
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

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 addgit commit 提交
  • AI 禁止 git checkout -bgit switchgit branchgit mergegit 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 同时修改的文件,冲突时由人类决策者在合并时解决:

# 人类决策者操作AI 不执行)
git checkout main
git merge <branch>
# 冲突时:
git checkout --theirs pnpm-lock.yaml   # 取分支版本
pnpm install                           # 重新生成
git add pnpm-lock.yaml
git commit

8.3 提交规范

# 每个 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 审计自己负责的服务时,填写下表:

## 服务审计表 — [AI标识]

| 服务 | 权限装饰器 | 错误码前缀 | logger   | metrics  | tracer   | /healthz | /readyz  | 优雅关闭 | 测试覆盖率 | Dockerfile |
| ---- | ---------- | ---------- | -------- | -------- | -------- | -------- | -------- | -------- | ---------- | ---------- |
| xxx  | ✅/❌/⚠️   | ✅/❌/⚠️   | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | ✅/❌/⚠️ | XX%        | ✅/❌/⚠️   |

10. 相关文档