xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2a2a56f541df44ec07f99b1a46bd933b81332b2d
Edu/docs/architecture/ai-allocation.md
SpecialX 0a71b02e04
Some checks failed
CI / quality-ts (push) Failing after 48s
Details
CI / quality-go (push) Failing after 4s
Details
CI / quality-proto (push) Failing after 2s
Details
CI / deploy (push) Has been skipped
Details
fix: code compliance audit and fix across all services 
NestJS (6 services): implement @RequirePermission decorator with
SetMetadata+Reflector, register APP_GUARD globally, fix as assertions
to type guards, add explicit return types, fix import type for express,
fix /metrics implicit any, replace native Error with ApplicationError,
remove typeorm remnants, register LifecycleService.

teacher-bff: add logger, ApplicationError, GlobalErrorFilter, forward
real userId to downstream, log downstream failures, migrate health
controller to shared/health.

Go (2 services): interface to any, doc comments, CORS dev whitelist,
JWT secret fail-fast, push-gateway internal API auth, metrics and
readyz endpoints, remove dead code.

Python (2 services): lifespan return type, dev_mode to bool, data-ana
APIRouter, ai POST body model, ClickHouse async wrapping.
2026-07-09 17:28:27 +08:00

402 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AI 分配方案与架构设计外包流程
> 版本：1.0
> 日期：2026-07-09
> 适用范围：Edu 微服务项目模块架构设计外包阶段
> 关联文档：[多 AI 协作指南](../standards/multi-ai-collaboration.md)、[004 架构影响地图](./004_architecture_impact_map.md)、[待开发功能路线图](./roadmap/pending-features.md)
---
## 1. 外包总流程：三阶段
```
阶段 1：全局理解 阶段 2：模块架构设计 阶段 3：按图实施
(每个 AI 独立) (每个 AI 独立) (并行开发)
│ │ │
阅读全局架构文档 产出模块内部架构图 按自己画的图写代码
理解边界与契约 定义内部模块/数据流 coord 定期巡检一致性
理解与其他模块的接口 标注与其他模块的交互点 遇到偏差更新架构图
│ │ │
▼ ▼ ▼
交付：理解确认书 交付：模块架构设计文档 交付：代码 + 更新图
```
**阶段 1 目标**：每个 AI 读懂自己负责的模块在全局架构中的位置、边界、契约。
**阶段 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 必读文档清单
以下为每个 AI 在阶段 1 必须按顺序阅读的文档（标注 ★ 为强制必读）：
| 顺序 | 文档 | ai01 | ai02 | ai03 | ai04 | ai05 | ai06 | ai07 | coord |
| ---- | ------------------------------------------------------------------- | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :---: |
| 1 | [README.md](../../README.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 2 | [MIGRATION_GUIDE.md](../../MIGRATION_GUIDE.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 3 | [004 架构影响地图](./004_architecture_impact_map.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 4 | [pending-features.md](./roadmap/pending-features.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 5 | [project_rules.md](../../.trae/rules/project_rules.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 6 | [coding-standards.md](../standards/coding-standards.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 7 | [multi-ai-collaboration.md](../standards/multi-ai-collaboration.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 8 | 黄金模板 `services/classes/src/` 全部源码 | ★ | ★ | ★ | ★ | — | — | — | ★ |
| 9 | `packages/shared-proto/proto/` 全部 .proto | ★ | ★ | ★ | ★ | ★ | ★ | — | ★ |
**语言特定补充阅读**：
| AI | 语言 | 补充文档 |
| ------- | -------- | --------------------------------------------------------------- |
| ai01 | Go | `services/api-gateway/` 全部源码 |
| ai02-05 | TS | `services/iam/`、`services/teacher-bff/` 源码（参考已实现模板） |
| ai06 | Python | `services/data-ana/`、`services/ai/` 骨架源码 |
| ai07 | TS/React | `apps/teacher-portal/` 全部源码、Module Federation 配置 |
---
## 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. 协作规则
### 9.1 单仓库并行开发
当前阶段采用**单仓库直接 push main**模式，不经过 PR：
- 每个 AI 只能修改自己负责的目录（见 §3.2）
- `packages/shared-proto/` 仅 coord 修改，其他 AI 只读
- `docs/`、`.trae/`、`infra/`、`.github/` 仅 coord 修改
### 9.2 唯一冲突文件处理
`pnpm-lock.yaml` 是唯一可能多 AI 同时修改的文件，冲突时：
```bash
git pull origin main --rebase
# 冲突时：
git checkout --theirs pnpm-lock.yaml # 取远程版本
pnpm install # 重新生成
git add pnpm-lock.yaml
git rebase --continue
```
### 9.3 提交规范
```bash
# 每个 AI 在自己的服务目录内工作
git add services/<service>/...
git commit -m "docs(<service>): 模块架构设计文档"
# 或
git commit -m "docs(<service>): 阶段1理解确认书"
```
### 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) — 六阶段目标
Reference in New Issue View Git Blame Copy Permalink