xiner/Edu

Fork 0

Files

SpecialX 0a71b02e04

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

26 KiB

Raw Blame History

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

版本：1.0 日期：2026-07-09 适用范围：Edu 微服务项目模块架构设计外包阶段关联文档：多 AI 协作指南、004 架构影响地图、待开发功能路线图

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	★	★	★	★	★	★	★	★
2	MIGRATION_GUIDE.md	★	★	★	★	★	★	★	★
3	004 架构影响地图	★	★	★	★	★	★	★	★
4	pending-features.md	★	★	★	★	★	★	★	★
5	project_rules.md	★	★	★	★	★	★	★	★
6	coding-standards.md	★	★	★	★	★	★	★	★
7	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 的文档清单后，必须产出以下确认书：

## 模块理解确认书 — [模块名]

### 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 审核后，产出以下架构设计文档：

## 模块架构设计文档 — [模块名]

### 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 接口一致性检查

| 服务 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 端口矩阵
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 同时修改的文件，冲突时：

git pull origin main --rebase
# 冲突时：
git checkout --theirs pnpm-lock.yaml   # 取远程版本
pnpm install                           # 重新生成
git add pnpm-lock.yaml
git rebase --continue

9.3 提交规范

# 每个 AI 在自己的服务目录内工作
git add services/<service>/...
git commit -m "docs(<service>): 模块架构设计文档"

# 或
git commit -m "docs(<service>): 阶段1理解确认书"

9.4 proto 变更流程

任何 AI 需要新增/修改 proto：

在共享协调渠道声明需求（格式：# proto-change: <描述>）
coord 统一修改 packages/shared-proto/
coord 通知受影响 AI 更新设计文档

10. 审计模板（阶段 1 自检用）

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

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

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

11. 相关文档

多 AI 协作指南 — 日常开发协作流程
004 架构影响地图 — 全局架构与依赖
项目规则 — 强制约束
编码规范 — 多语言编码标准
待开发功能路线图 — 六阶段目标

26 KiB Raw Blame History Unescape Escape

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

1. 外包总流程：三阶段

2. 完整服务清单

3. AI 分配方案（7 AI + 1 coord）

3.1 分配原则

3.2 分配矩阵

3.3 为什么这样拆

4. 各 AI 阶段 1 必读文档清单

5. 各 AI 阶段 2 设计重点

ai01 — Go 网关层

ai02 — 身份认证

ai03 — 教学场景域

ai04 — 学习 + 家长场景域 BFF

ai05 — 内容 + 通知

ai06 — Python 数据 + AI

ai07 — 前端 4 端

coord — 协调 AI

6. 阶段 1 交付物模板

7. 阶段 2 交付物模板

8. 交叉审查规则

8.1 接口一致性检查

8.2 全局冲突检查

8.3 黄金模板对齐检查

9. 协作规则

9.1 单仓库并行开发

9.2 唯一冲突文件处理

9.3 提交规范

9.4 proto 变更流程

10. 审计模板（阶段 1 自检用）

11. 相关文档

26 KiB

Raw Blame History