xiner/Edu

Files

SpecialX 9ba368477d refactor(docs): 移除 ai07 classes 合并到 core-edu，16 AI 降为 15 AI

2026-07-10 14:04:49 +08:00

36 KiB

Raw 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 的所有代码
开发期间消费上游的 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 与 multi-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-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 项依赖检查

设计重点

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）

设计重点

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 全并行开发工作流

各 AI 读取自己的 contracts/[模块名]_contract.md 了解上下游接口
各 AI 在 worklines/[模块名]_workline.md 详细规划全阶段任务
开发期间消费上游的 mock（见 contract.md §4 mock 策略）
上游就绪后在 matrix.md §8 更新就绪信号
所有模块就绪后统一集成测试（见 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 的接口时：

读 AI B 的 contracts/[B模块名]_contract.md
如有疑问，在 objections/cross_issue.md 追加条目
coord 仲裁后在 coord.md 写入结论

8. 协作规则

默认多 AI 协作：所有 AI 工作默认按多 AI 合作模式进行，详见 multi-ai-collaboration.md。

8.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 修改

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：

在 objections/cross_issue.md 声明需求
coord 统一修改 packages/shared-proto/
coord 通知受影响 AI 更新 contract.md

9. 审计模板（自检用）

每个 AI 审计自己负责的服务时，填写下表：

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

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

10. 相关文档

多 AI 协作指南 — 日常开发协作流程
004 架构影响地图 — 全局架构与依赖
总裁最终裁决 — 70+ 问题逐个裁决 + 时间统筹 + 15 AI 工作清单
AI 工作顺序协同规划 — 6 批次并行规划（历史参考）
coord 强制裁决 — 80+ 项强制裁决
coord 交叉审查 — 交叉审查结果
coord 仲裁汇总 — 新流程仲裁记录
总工作安排 — 15 AI 甘特图
上下游对接总矩阵 — 服务依赖 + 接口矩阵 + mock 策略
项目规则 — 强制约束
编码规范 — 多语言编码标准
待开发功能路线图 — 六阶段目标
端口分配 — 端口矩阵

36 KiB Raw Blame History Unescape Escape