xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: ai 协作文档体系重构与多 ai 仲裁结果落地

Browse Source 
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md)

2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration)

3.各服务 01/02 文档补全

4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens)

5.Proto 契约补全

6.004 架构影响地图更新

7.端口分配表

8.设计规格文档
This commit is contained in:
SpecialX
2026-07-10 12:58:22 +08:00
parent 2a2a56f541
commit faaaf29f67
120 changed files with 23201 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

356
docs/architecture/ai-work-orchestration.md Normal file
View File

@@ -0,0 +1,356 @@
# AI 工作顺序协同规划
> 版本：1.0
> 日期：2026-07-09
> 决策者：coord（经用户确认）
> 适用范围：Edu 项目 16 个 AI（ai01-ai16）+ coord
> 关联文档：[coord-final-decisions.md](./coord-final-decisions.md)、[ai-allocation.md](./ai-allocation.md)、[004 §16](./004_architecture_impact_map.md)、[issues.md](../issues.md)
---
## 0. 背景
coord-final-decisions.md 强制"首次实现即最终方案，不分阶段"，但实际执行中存在**工作先后排序问题**：
- teacher-bff 裁决"P2 起 GraphQL + gRPC 调下游"，但 core-edu P3 才启用 gRPC → P2 启动时 teacher-bff 调谁？
- shared-ts Outbox 工具包谁建？什么时候建？iam P2 即用
- parent-bff P4 依赖 iam.GetChildrenByParent，iam 何时补全？
本文档规划 **AI 工作顺序协同**，**尽量保证并行**，有依赖的才串行，并识别"跨度过大"问题记录到 [issues.md](../issues.md)。
---
## 1. 协同原则
| # | 原则 | 说明 |
| --- | ------------------ | -------------------------------------------------------------------------------------------- |
| 1 | **批次并行** | 同批次 AI 可同时启动，互不阻塞 |
| 2 | **批次间串行** | 下批次依赖上批次产出，必须等待 |
| 3 | **coord 前置** | coord 负责的 proto 契约 / 工具包 / 端口表必须在 AI 启动前就位 |
| 4 | **双向依赖协调** | 同批次内有双向依赖的 AI（如 BFF ⟷ Portal schema 契约），coord 仲裁第一版契约后并行 |
| 5 | **跨阶段扩展例外** | BFF 跨阶段补 gRPC 调用是**允许的例外**（因下游服务按阶段启用本身合理），不视为"中间过渡方案" |
| 6 | **疑问记录** | AI 觉得有疑问（前置依赖、跨度过大）可在 [issues.md](../issues.md) 记录，coord 统一解决 |
---
## 2. 批次总览
| 批次 | 阶段 | 可并行 AI 数 | 关键产出 | 跨度过大风险 |
| ---- | ------------ | --------------------------------------------- | -------------------------------------------------------- | ------------------------------------------ |
| 0 | 全 AI 启动前 | coord 独立 | proto 契约 + shared-ts Outbox + 端口表统一 | shared-ts Outbox 工具包遗漏（已修正） |
| 1 | P2 | 4（ai01/ai06 + ai03⟷ai13） | iam gRPC + teacher-bff GraphQL + teacher-portal MF shell | 高（teacher-bff 调下游断裂，见 issues #4） |
| 2 | P3 | 4（ai08 + ai04⟷ai14 + ai07 交接 + ai03 扩展） | core-edu gRPC + student-bff GraphQL | 中（student-bff 调 content/data-ana 断裂） |
| 3 | P4 | 5（ai09/ai11 + ai05⟷ai15 + ai03/ai04 扩展） | content gRPC + data-ana gRPC + parent-bff GraphQL | 中（teacher-bff 跨阶段改造） |
| 4 | P5 | 4（ai10⟷ai02 + ai12 + ai03 扩展） | msg gRPC + ai gRPC + push-gateway HTTP | 低（核心依赖已前置解决） |
| 5 | P6 | 1+（ai16 + 持续优化） | admin-portal MVP + P6 硬化 | 低 |
---
## 3. 批次 0：coord + ai13 协同完成（全 AI 启动前）
> **总裁裁决 §6.2 最终版**：批次 0 共 15 项任务，coord 负责 0.1-0.14，ai13 负责 0.15。
> 完成期限：3-5 天。批次 0 全部完成后才启动批次 1（见总裁裁决 §4.1 批次 0 完成信号机制）。
### 3.1 批次 0 详细任务清单（15 项）
| # | 责任方 | 任务 | 完成信号 | 阻塞批次 |
| ---- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------ |
| 0.1 | coord | `pnpm run arch:scan` 更新 arch.db | arch.db 已更新 | — |
| 0.2 | coord | 修订 coord-cross-review.md（补 coord 交叉审查结论） | 文档已更新 | — |
| 0.3 | coord | 补全 `iam.proto` 8 RPC（GetViewports / GetEffectivePermissions / GetEffectiveAccess / Logout / GetPublicKey / BatchGetUsers / GetEffectiveDataScope / GetChildrenByParent） | proto 文件已提交 | 批次 1（ai06） |
| 0.4 | coord | 建立 `shared-ts` Outbox 工具包（含设计草案 + 实现，`@edu/shared-ts/outbox`） | packages/shared-ts/src/outbox/ 已建立 | 批次 1（ai06） |
| 0.5 | coord | 补全 `content.proto`（ChapterService / QuestionService.* / TextbookService.ListTextbooks） | proto 文件已提交 | 批次 3（ai09） |
| 0.6 | coord | 补全 `msg.proto` 基础（5 RPC + NotificationPreferenceService + NotificationTemplateService + 3 message） | proto 文件已提交 | 批次 4（ai10） |
| 0.7 | coord | 补全 `analytics.proto` 基础 | proto 文件已提交 | 批次 3（ai11） |
| 0.8 | coord | 补全 `core_edu.proto`（AttendanceService / GetClassesByTeacher / BatchGetClasses） | proto 文件已提交 | 批次 2（ai08） |
| 0.9 | coord | `buf.gen.yaml` 补 gRPC 插件 | buf generate 可运行 | 批次 1+ |
| 0.10 | coord | 补全 `events.proto`（含 AuditEvent message，总裁裁决 §5.5） | proto 文件已提交 | 批次 5（ai16 admin-portal 审计日志） |
| 0.11 | coord | `analytics.proto` 扩展（4 端 Dashboard + Warning + MasteryDistribution + SubscribeMasteryUpdate Stream RPC） | proto 文件已提交 | 批次 3（ai11） |
| 0.12 | coord | 补全 `ai.proto`（GenerateLessonPlan / StreamGenerateQuestion） | proto 文件已提交 | 批次 4（ai12） |
| 0.13 | coord | 补全 `msg.proto`（5 RPC + NotificationPreferenceService + NotificationTemplateService + 3 message） | proto 文件已提交 | 批次 4（ai10） |
| 0.14 | coord | 建立 `packages/shared-go` 包骨架（tracer/logger/jwks/env 4 模块的接口定义 + 默认实现，总裁裁决 §2.13） | packages/shared-go/ 已建立 | 批次 1（ai01 Gateway 接入） |
| 0.15 | ai13 | 建立 `packages/ui-tokens` + `packages/ui-components` + `packages/hooks` 骨架（总裁裁决 §2.12） | 3 个 packages 已建立 | 批次 1（ai13 teacher-portal） |
### 3.2 批次 0 完成信号机制（总裁裁决 §4.1）
1. **coord 维护"批次 0 任务进度表"**：在 ai-work-orchestration.md §3.1 表格"完成信号"列勾选
2. **批次 0 全部 15 项完成后，coord 发布批次 1 启动公告**（在本文件 §9 时间线末尾追加"批次 0 已完成，批次 1 启动"）
3. **建立"前置依赖就绪检查清单"**：coord 在批次 1/2/3/4/5 启动前逐项确认
4. **批次 1 启动条件**：0.1-0.15 全部完成 + teacher-bff GraphQL schema 第一版仲裁完成 + MF shell 暴露清单仲裁完成
---
## 4. 批次 1：P2 并行批
### 4.1 前置条件
- 批次 0 中 0.1-0.7 全部就位
### 4.2 可并行 AI（4 个 + 1 双向依赖对）
| AI | 服务 | 核心工作 | 依赖 | 产出 |
| ------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------ |
| **ai01** | api-gateway | 补 GW_ 前缀 + /parent 路由 + W1-W8 整改 | 独立 | /parent 路由块 |
| **ai06** | iam | gRPC server 50052 + 8 RPC + iam_student_guardians 表 + DB 驱动 PermissionGuard + AuthMiddleware + shared-ts Outbox 接入 | 批次 0.3 + 0.4 | iam gRPC 50052 可用（含 GetChildrenByParent） |
| **ai03** ⟷ **ai13** | teacher-bff ⟷ teacher-portal | GraphQL schema 契约双向依赖，coord 仲裁第一版 schema 后并行 | ai03 依赖 ai06 gRPC；ai13 依赖 ai03 schema | teacher-bff GraphQL endpoint + DownstreamClient 抽象 + teacher-portal MF shell |
### 4.3 协调点
- **ai03 ⟷ ai13 GraphQL schema**：coord 在批次 1 启动前仲裁 schema 第一版（含 Query/Mutation 清单），ai03 实现 server，ai13 实现 client，同步开发
- **ai03 DownstreamClient 抽象**：ai03 P2 必须产出可复用的 DownstreamClient 抽象（B8 裁决），供 ai04/ai05 复用，coord 验收时检查
### 4.4 跨度过大问题（见 [issues.md](../issues.md) #4-#8）
- teacher-bff P2 只能 gRPC 调 iam，调 core-edu/content/data-ana/ai/msg 全部断裂 → 见 issues #4
- teacher-bff 跨阶段持续改造与"不分阶段"原则矛盾 → 见 issues #5（coord 已裁定为例外）
---
## 5. 批次 2：P3 并行批
### 5.1 前置条件
- 批次 1 完成（iam gRPC 50052 + GetChildrenByParent 已就绪）
- 批次 0 中 0.8-0.9 全部就位（core_edu.proto + buf.gen.yaml gRPC 插件）
### 5.2 可并行 AI（4 个 + 1 双向依赖对 + 1 交接）
| AI | 服务 | 核心工作 | 依赖 | 产出 |
| ------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
| **ai08** | core-edu | 合并 classes + gRPC server 50053 + AttendanceService + GetClassesByTeacher + BatchGetClasses + C1-C11 整改 | ai07 classes 黄金模板代码 | core-edu gRPC 50053 可用；classes 服务下线 |
| **ai07** | classes | 在 ai08 启动前完成 classes 代码交接 | — | classes 代码交接完成 |
| **ai04** ⟷ **ai14** | student-bff ⟷ student-portal | GraphQL schema 契约双向依赖 | ai04 依赖 ai06 gRPC + ai08 gRPC + ai03 DownstreamClient 抽象；ai14 依赖 ai04 schema + ai13 MF 共享组件 | student-bff GraphQL endpoint + student-portal MF remote |
| **ai03** | teacher-bff | P3 扩展，补 gRPC 调 core-edu 50053 | ai08 core-edu gRPC | teacher-bff gRPC 调 core-edu 链路打通 |
### 5.3 协调点
- **ai07 → ai08 classes 交接**：ai07 在 ai08 启动前完成 classes 代码交接（C1 裁决"P3 开始前直接合并"）
- **ai04 ⟷ ai14 GraphQL schema**：coord 仲裁 student-bff schema 第一版
- **ai03 跨阶段扩展**：ai03 P3 补 gRPC 调 core-edu（跨阶段扩展例外，见 issues #5）
### 5.4 跨度过大问题
- student-bff P3 仍无法 gRPC 调 content / data-ana（P4 才启用）→ 见 issues #6
---
## 6. 批次 3：P4 并行批
### 6.1 前置条件
- 批次 0 中 0.10-0.11 全部就位（content.proto + analytics.proto 补全）
- 批次 2 完成（core-edu gRPC 50053 可用）
- iam.GetChildrenByParent 已就绪（批次 1 已完成）
### 6.2 可并行 AI（5 个 + 1 双向依赖对 + 2 跨阶段扩展）
| AI | 服务 | 核心工作 | 依赖 | 产出 |
| ------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| **ai09** | content | gRPC server 50054 + ChapterService + QuestionService proto 补全（N3 裁决 P4 即补，不等到 P5）+ N1-N5 整改 | 批次 0.10 | content gRPC 50054 可用（含 QuestionService） |
| **ai11** | data-ana | gRPC server 50055 + 4 端 Dashboard + Warning + MasteryDistribution + SubscribeMasteryUpdate Stream + D1-D5 整改 | 批次 0.11 | data-ana gRPC 50055 可用 |
| **ai05** ⟷ **ai15** | parent-bff ⟷ parent-portal | GraphQL schema 契约双向依赖 | ai05 依赖 iam.GetChildrenByParent（已就绪）+ core-edu gRPC + ai03 DownstreamClient 抽象 | parent-bff GraphQL endpoint + parent-portal MF remote |
| **ai03** | teacher-bff | P4 扩展，补 gRPC 调 content + data-ana | ai09 + ai11 | teacher-bff gRPC 调 content + data-ana 链路打通 |
| **ai04** | student-bff | P4 扩展，补 gRPC 调 content + data-ana | ai09 + ai11 | student-bff gRPC 调 content + data-ana 链路打通 |
### 6.3 协调点
- **ai05 ⟷ ai15 GraphQL schema**：coord 仲裁 parent-bff schema 第一版
- **ai03 / ai04 跨阶段扩展**：补 gRPC 调 content + data-ana（跨阶段扩展例外）
- **coord 验收 ai09 P4**：强制检查 QuestionService RPC 已落地（阻塞 ai12 P5 出题）
### 6.4 跨度过大问题
- teacher-bff P4 仍需扩展 gRPC 调 ai（P5）+ msg（P5）→ 见 issues #6
---
## 7. 批次 4：P5 并行批
### 7.1 前置条件
- 批次 0 中 0.12-0.13 全部就位（ai.proto + msg.proto 补全）
- 批次 3 完成（content.QuestionService RPC 已补全 + content gRPC 50054 可用）
### 7.2 可并行 AI（4 个 + 1 双向依赖对 + 1 跨阶段扩展）
| AI | 服务 | 核心工作 | 依赖 | 产出 |
| ------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **ai10** ⟷ **ai02** | msg ⟷ push-gateway | HTTP /internal/push 契约双向依赖 | ai10 依赖批次 0.13；ai02 独立 | msg gRPC 50056 + push-gateway HTTP /internal/push |
| **ai12** | ai | gRPC server 50058 + GenerateLessonPlan + StreamGenerateQuestion + Prompt DB 存储 + FastAPI BackgroundTasks + A1-A8 整改 + 调 content.QuestionService + 调 core-edu.ExamService.GetExam + 调 data-ana | 批次 0.12 + content.QuestionService（已就绪）+ core-edu gRPC（已就绪）+ data-ana gRPC（已就绪） | ai gRPC 50058 可用 |
| **ai03** | teacher-bff | P5 扩展，补 gRPC 调 ai + msg | ai10 + ai12 | teacher-bff gRPC 调 ai + msg 链路打通（全部下游 gRPC 调用完成） |
### 7.3 协调点
- **ai10 ⟷ ai02 HTTP /internal/push 契约**：coord 仲裁第一版接口契约（path/body/status code），ai02 优先 1-2 天启动 /internal/push 端点，ai10 后启动调用方
- **ai12 跨服务调用**：调 content.QuestionService（已就绪）+ core-edu.ExamService.GetExam（已就绪）+ data-ana（已就绪），无阻塞 ✓
### 7.4 无跨度过大问题
- 核心依赖已通过前置裁决解决（content.QuestionService P4 补全、core-edu P3 启用、data-ana P4 启用）
---
## 8. 批次 5：P6 并行批
### 8.1 前置条件
- 批次 4 完成
### 8.2 可并行 AI（1 个 + 持续优化）
| AI | 服务 | 核心工作 | 依赖 | 产出 |
| -------- | ------------ | ------------------------------------------------------------ | ----------------------------------------- | ------------------ |
| **ai16** | admin-portal | MF remote + 管理端路由骨架 + P6+ 评估 X1-X10 事项 | events.proto（P6 实施时补 admin 8 topic） | admin-portal MVP |
| 其他 AI | 持续优化 | /readyz 补下游探针、Python ErrorFilter 对齐等 §16.7.6 持续项 | — | 各服务 P6 硬化完成 |
### 8.3 跨度过大问题
- admin-portal 8 个新 Kafka topic 在 P6 实施时才补 events.proto message → 见 issues #14
---
## 9. 批次时间线（总裁裁决 §6.1 最终版）
> **总裁裁决最终版**：总时间线 49-64 天（约 10-13 周）。
> 实际进度以各 AI 交付为准，但批次启动必须满足前置条件（见各批次 §1-§7 前置条件章节）。
| 批次 | 阶段 | 预计工作日 | 参与 AI | 关键里程碑 | 启动条件 |
| ---------- | ---------- | ---------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| **批次 0** | coord 前置 | 3-5 天 | coord（0.1-0.14）+ ai13（0.15） | proto 契约 + shared-ts Outbox + shared-go + packages 骨架 | 本裁决发布后立即 |
| **批次 1** | P2 | 7-10 天 | ai01 + ai06 + ai03⟷ai13 | iam P2.1 + teacher-bff Must Have + teacher-portal P2 + Gateway 路由 | 批次 0 全部完成 |
| **批次 2** | P3 | 7-10 天 | ai08 + ai07 交接 + ai04⟷ai14 + ai03 扩展 | core-edu gRPC 50053 + student-bff + student-portal P3（7 页）+ teacher-bff P3 扩展 | 批次 1 P2.1 完成 + ai03 DownstreamClient 抽象就绪 |
| **批次 3** | P4 | 10-12 天 | ai09 + ai11 + ai05⟷ai15 + ai03/ai04 扩展 | content gRPC 50054 + data-ana gRPC 50055 + parent-bff + parent-portal P4 + teacher/student-bff P4 扩展 | 批次 2 完成 |
| **批次 4** | P5 | 12-15 天 | ai10⟷ai02 + ai12 + ai03 扩展 | msg gRPC 50056 + push-gateway + ai 服务 + teacher-bff P5 扩展 + 通知功能启用 | 批次 3 完成 |
| **批次 5** | P6 | 10-12 天 | ai16 + 持续优化 | admin-portal + 审计日志 + iam P2.2 补全 + 持续优化 | 批次 4 完成 |
**总时间线**：49-64 天（约 10-13 周）
### 9.1 批次启动前 coord 仲裁清单
| 批次 | 仲裁内容 | 完成期限 |
| ------ | --------------------------------------------------------------------------------------------------- | ------------- |
| 批次 1 | teacher-bff GraphQL schema 第一版（含 admin 命名空间）+ MF shell 暴露清单（含 GraphQL client 单例） | 批次 1 启动前 |
| 批次 2 | student-bff GraphQL schema 第一版 | 批次 2 启动前 |
| 批次 3 | parent-bff GraphQL schema 第一版 | 批次 3 启动前 |
| 批次 4 | /internal/push 契约（采纳 ai02 02 §4.2 作为第一版） | 批次 4 启动前 |
| 批次 5 | admin-portal schema 命名空间（复用 teacher-bff GraphQL endpoint） | 批次 5 启动前 |
### 9.2 批次完成信号
> **新流程**（2026-07-09 起）：批次排期详见 [issues/workline.md](./issues/workline.md)，仲裁异议详见 [issues/coord.md](./issues/coord.md)。各 AI 在 `issues/[模块名]_workline.md` 维护自己模块的甘特图。
- **批次 0 已完成**：✅ 2026-07-09 coord 完成全部 14 项任务（0.1-0.14）+ ai13 完成 0.15 并回写。**批次 1 启动公告**：批次 0 全部就绪，批次 1（P2）正式启动。
- 0.1 arch:scan ✅（TS 14 模块 / Go 2 模块 / Proto 297 契约）
- 0.2 coord-cross-review.md 修订 ✅（§8 总裁裁决落实记录）
- 0.3 iam.proto 8 RPC ✅（12 RPC 总计）
- 0.4 shared-ts Outbox 工具包 ✅（6 文件，typecheck/lint 零错误）
- 0.5 content.proto ✅（4 service / 22 RPC）
- 0.6/0.13 msg.proto ✅（3 service / 13 RPC）
- 0.7/0.11 analytics.proto ✅（12 RPC 含 Stream）
- 0.8 core_edu.proto ✅（5 service，+ClassService +AttendanceService）
- 0.9 buf.gen.yaml gRPC 插件 ✅（go + python）
- 0.10 events.proto AuditEvent ✅（9 message）
- 0.12 ai.proto ✅（6 RPC，+GenerateLessonPlan +StreamGenerateQuestion）
- 0.14 shared-go 包骨架 ✅（tracer/logger/jwks/env 4 模块）
- 0.15 packages 骨架 ✅ **ai13 已完成并回写**（known-issues.md L677 + 03-long-term-architecture.md §14.1）：
- ui-tokens：coord 建立（colors/typography/spacing/shadows）
- ui-components：ai13 建立（cn/ErrorBoundary/Loading/Empty/RequirePermission 5 组件）
- hooks：ai13 建立（useAuth/usePermission/useViewports/useApi/useA11yId/useAriaLive/useToast/useTraceId 8 hooks + types）
- ISSUE-036-ai13 已闭合（删除 REST→GraphQL 过渡方案，替换为 GraphQL 客户端架构最终方案）
- **批次 1 已完成**：⏳
- **批次 2 已完成**：⏳
- **批次 3 已完成**：⏳
- **批次 4 已完成**：⏳
- **批次 5 已完成**：⏳
---
## 10. coord 验收清单
每个批次完成时，coord 必须验收以下项：
### 10.1 批次 1 验收（P2）
- [ ] iam gRPC 50052 可用，8 个 RPC 全部实现
- [ ] iam.GetChildrenByParent 已落地（阻塞 parent-bff P4）
- [ ] iam_student_guardians 表已建立
- [ ] iam 已接入 shared-ts Outbox 工具包
- [ ] teacher-bff GraphQL endpoint 可用
- [ ] teacher-bff DownstreamClient 抽象已产出（供 ai04/ai05 复用）
- [ ] teacher-portal MF shell + 共享组件已产出
- [ ] api-gateway /parent 路由块已配置
- [ ] api-gateway 错误码已补 GW_ 前缀
### 10.2 批次 2 验收（P3）
- [ ] core-edu gRPC 50053 可用
- [ ] AttendanceService + GetClassesByTeacher + BatchGetClasses 已实现
- [ ] classes 服务已下线，代码合并到 core-edu
- [ ] student-bff GraphQL endpoint 可用
- [ ] student-portal MF remote 接入完成
- [ ] teacher-bff gRPC 调 core-edu 链路打通
### 10.3 批次 3 验收（P4）
- [ ] content gRPC 50054 可用
- [ ] content.QuestionService RPC 已落地（阻塞 ai P5 出题）
- [ ] data-ana gRPC 50055 可用
- [ ] parent-bff GraphQL endpoint 可用
- [ ] parent-portal MF remote 接入完成
- [ ] teacher-bff / student-bff gRPC 调 content + data-ana 链路打通
### 10.4 批次 4 验收（P5）
- [ ] msg gRPC 50056 可用
- [ ] ai gRPC 50058 可用
- [ ] push-gateway HTTP /internal/push 可用
- [ ] teacher-bff gRPC 调 ai + msg 链路打通（全部下游 gRPC 调用完成）
- [ ] ai 调 content.QuestionService + core-edu.ExamService.GetExam + data-ana 链路打通
### 10.5 批次 5 验收（P6）
- [ ] admin-portal MVP 可用
- [ ] admin 8 个新 Kafka topic + events.proto message 已补
- [ ] 各服务 P6 硬化完成（/readyz 下游探针、Python ErrorFilter 对齐等）
---
## 11. AI 疑问记录机制
各 AI 在执行过程中若发现以下问题，**必须**记录到 [docs/issues.md](../issues.md)：
1. **前置依赖未就绪**：本 AI 工作依赖的上游产出未到位
2. **跨度过大**：裁决要求的工作跨度超出当前阶段合理范围
3. **裁决冲突**：发现 coord-final-decisions.md 内部或与其他文档冲突
4. **契约不明确**：与协作 AI 的接口契约未协调清楚
5. **工作归属不明**：某项工作应该由谁负责不明确
### 11.1 记录格式（见 issues.md 模板）
```markdown
### ISSUE-XXX: <问题标题>
- **提请 AI**：aiXX
- **类别**：前置依赖未就绪 / 跨度过大 / 裁决冲突 / 契约不明确 / 工作归属不明
- **阶段**：P2/P3/P4/P5/P6
- **问题描述**：<详细描述>
- **影响**：<对工作的影响>
- **建议方案**：<AI 建议的解决方案>
- **状态**：待 coord 仲裁 / coord 已裁决 / 已解决
- **coord 裁决**：<coord 的裁决结果（coord 填写）>
```
### 11.2 coord 处理流程
1. AI 在 issues.md 追加问题记录（状态：待 coord 仲裁）
2. coord 定期（每批次结束）统一仲裁，填写 coord 裁决字段
3. 状态改为"coord 已裁决"
4. AI 按 coord 裁决执行，完成后状态改为"已解决"
---
## 12. 变更记录
| 日期 | 变更 | 决策者 |
| ---------- | -------------------------------------------------------- | ----------------- |
| 2026-07-09 | 初始创建，规划批次 0-5 + 14 个已识别问题（见 issues.md） | coord（用户确认） |

325
docs/architecture/coord-cross-review.md Normal file
View File

@@ -0,0 +1,325 @@
# coord 交叉审查报告（架构设计外包阶段 2）
> 版本：1.0
> 日期：2026-07-09
> 审查执行：coord（协调 AI）
> 关联文档：
>
> - [004 架构影响地图](./004_architecture_impact_map.md) — 架构设计意图唯一源
> - [AI 分配方案](./ai-allocation.md) §8 交叉审查规则
> - [项目规则](../../.trae/rules/project_rules.md)
>
> **本文档定位**：架构设计外包阶段 2 的过程性审查产物，记录 coord 对 18 份模块架构设计文档的跨模块一致性审查与裁决。裁决中涉及"架构设计意图"的结论已同步沉淀到 [004 架构影响地图](./004_architecture_impact_map.md) 对应章节，本文件保留完整审查过程与裁决依据作为追溯凭证。
---
## 1. 审查范围
| 维度 | 内容 |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 审查文档 | 18 份 AI 架构设计文档（`services/*/docs/01-understanding.md` + `02-architecture-design.md` + `apps/teacher-portal/README.md`） |
| 审查维度 | ① 跨模块接口签名一致性 ② Kafka topic 不重复 ③ 端口不冲突 ④ 错误码前缀不重叠 |
| 审查方式 | 4 个 search subagent 并行提取 4 类信息，coord 整合裁决 |
| 审查依据 | [004 架构影响地图](./004_architecture_impact_map.md)、[project_rules](../../.trae/rules/project_rules.md)、[ai-allocation §8](./ai-allocation.md) |
---
## 2. 接口签名一致性审查
### 2.1 Proto 包名规范冲突（P0 全局）
| 实际使用 | 规则要求 | 涉及 proto | 裁决 |
| ---------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `next_edu_cloud.<domain>.v1` | `edu.<domain>.v1`（project_rules §5） | iam.proto / content.proto / msg.proto / core_edu.proto / analytics.proto / ai.proto / events.proto / push.proto（全部 8 份） | **裁决：保持现状 `next_edu_cloud.*`**。理由：全量迁移成本高且无功能收益，仅 project_rules §5 文字与实际不符。**整改**：修订 project_rules §5 包名规范为 `next_edu_cloud.<domain>.v1`，同步 004 §11.2 契约规则表。 |
### 2.2 Proto 契约缺口（P0 阻塞 parent-bff / P1 高优）
| # | 缺口 proto | 缺失内容 | 阻塞方 | 裁决 |
| --- | -------------- | ------------------------------------------------------------------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------- |
| 1 | iam.proto | `GetViewports` / `GetEffectivePermissions` / `Logout` / `GetPublicKey`（JWKS） | teacher-bff / student-bff / parent-bff | **P2 补全**：iam 在 proto 补 4 个 RPC，REST 已实现 |
| 2 | iam.proto | `GetChildrenByParent` / `GetParentsByStudent`（家长-学生关联） | **parent-bff P0 阻塞** | **P4 前必须补全**：iam 新增 `ParentStudentService` 或扩展 `IamService`，parent-bff 核心场景依赖 |
| 3 | iam.proto | `GetEffectiveDataScope` | data-ana（DataScope 解析） | **P4 补全**：iam 新增 RPC，data-ana gRPC 调用 |
| 4 | content.proto | `ChapterService` / `QuestionService` 域 | student-bff / content 自身 | **P4 补全**：content 新增 2 个 service |
| 5 | core_edu.proto | `AttendanceService`（出勤） | parent-bff / core-edu | **P3 补全**：core-edu 新增 service |
| 6 | events.proto | `NotificationEvent` / `AIUsageEvent` / `UserEvent` / `RoleEvent` | msg / ai / iam | **P2-P5 分阶段补全**：events.proto 按事件类型补 message |
| 7 | buf.gen.yaml | 缺 gRPC 插件 | 全部 | **P3 补全**：coord 在 buf.gen.yaml 加 `grpc-node` / `grpc-python` / `grpc-go` 插件 |
### 2.3 gRPC 启用时机（P1 高优）
**现状**：所有 6 个业务服务 proto 已定义 gRPC service，但全部仅实现 HTTP REST，gRPC server 未落地。004 §4.1 明确"BFF → 业务服务走 gRPC"，但 teacher-bff 实际用 REST fetch。
**裁决**：
| 阶段 | gRPC 启用范围 | 理由 |
| ---- | --------------------------------- | ----------------------------------------- |
| P2 | 不启用 | teacher-bff REST 已跑通，无阻塞 |
| P3 | iam + core-edu 启用 gRPC server | student-bff / parent-bff 将依赖，需先就绪 |
| P4 | content + data-ana 启用 | ai07 student-portal / parent-portal 依赖 |
| P5 | ai 启用（含 StreamChat 流式 RPC） | teacher-portal AI 辅助出题依赖 |
**整改**：004 §4.1 补充"gRPC 启用阶段矩阵"小节。
### 2.4 前端与后端端点不一致（P1 高优）
| # | 前端文档声明 | 后端实际端点 | 冲突类型 | 裁决 |
| --- | ------------------------------------------ | ----------------------------------------------------- | ----------------- | --------------------------------------------------- |
| 1 | `GET /api/v1/ai/generate-questions`（SSE） | `POST /ai/chat/stream` + `POST /ai/generate/question` | 路径 + 方法不一致 | **以 ai 服务为准**，ai07 修正 teacher-portal README |
| 2 | `GET /iam/effective-permissions` | `GET /iam/permissions/effective` | 路径不一致 | **以 iam 为准**，ai07 修正 |
| 3 | `GET /iam/rbac/...` | `GET /iam/viewports` / `/iam/roles` 等 | 路径不一致 | **以 iam 为准**，ai07 修正 |
| 4 | `POST /parent/switch-child` | `POST /parent/children/:childId/select` | 路径不一致 | **以 parent-bff 为准**，ai07 修正 |
### 2.5 BFF API 风格：REST vs GraphQL（P1 高优）
**现状**：004 §11.3 提到 BFF GraphQL Yoga + DataLoader，但 teacher-bff 实际是 REST fetch。
**裁决**：**P2-P3 用 REST，P4 起若 BFF 切 GraphQL 再引入 urql**。004 §11.3 标注为"目标态"，当前阶段以 REST 为准。
---
## 3. Kafka Topic 一致性审查
### 3.1 core-edu 教学事件 topic 命名双轨（P0 最严重）
| 004 §7.2 规范 | core-edu 代码实际 | 消费方文档 | 冲突 |
| ----------------------------- | ----------------- | ------------------------------------------------- | ---------------------------------------------------- |
| `edu.teaching.exam.published` | `edu.exam.events` | msg 按规范消费，student-bff/parent-bff 按代码消费 | **契约破裂**：msg 订阅不上 core-edu 实际发布的 topic |
**裁决**：**统一为 `edu.teaching.<aggregate>.<action>` 风格**（遵循 004 §7.2）。core-edu 修改 `TOPIC_MAP`，student-bff / parent-bff 修改订阅 topic 名。
**整改清单**：
- core-edu `shared/outbox/outbox.publisher.ts`：`edu.exam.events` → `edu.teaching.exam.published` 等 4 个 topic
- student-bff / parent-bff 文档：同步更新订阅 topic 名
- msg 文档：已按规范，无需修改
### 3.2 004 §7.2 需补登的 topic（P1）
| Topic | 发布方 | 消费方 | 裁决 |
| -------------------------------------------- | -------- | ----------------------------- | ------------------------------------------------ |
| `edu.identity.user.deleted` | iam | core-edu / msg / push-gateway | ✅ 补登 |
| `edu.identity.user.role_changed` | iam | 自身缓存 / msg | ✅ 补登 |
| `edu.identity.role.created` | iam | msg | ✅ 补登 |
| `edu.identity.role.updated` | iam | 自身缓存 / msg | ✅ 补登 |
| `edu.notification.events` | msg | push-gateway | ✅ 补登（msg 必须明确发布此 topic） |
| `edu.insight.ai.usage` | ai | data-ana | ✅ 补登 + events.proto 补 `AIUsageEvent` message |
| `edu-cdc.next_edu_cloud.*`（5 个 CDC topic） | Debezium | data-ana | ✅ 补登 CDC topic 命名规范段 |
### 3.3 Python 服务 Outbox 豁免（P1）
**现状**：004 §12.2 禁止直接 Kafka producer，但 data-ana / ai 是 Python 服务无 MySQL 写事务，Outbox 不适用。
**裁决**：**派生数据事件（非业务事务写）允许直接 producer**。data-ana 的 `MasteryUpdated`、ai 的 `AIUsageRecorded` 属于派生数据，豁免 Outbox 约束。
**整改**：004 §12.2 补充"派生数据事件豁免条款"。
### 3.4 content Outbox 缺失（P1）
**现状**：004 §7.2 列 content 发 `edu.content.question.published`，但 content 骨架无 Outbox / Kafka 实现。
**裁决**：**ai05 在 P4 阶段 2 设计中补全 content Outbox**。
### 3.5 NotificationRequested 事件发布方未明确（P1）
**现状**：push-gateway 消费 `edu.notification.events`，但 msg 文档未明确发布此 topic。
**裁决**：**msg 服务为 `edu.notification.events` 的唯一发布方**，使用 Outbox 模式（msg 有 MySQL 写事务）。
---
## 4. 端口冲突审查
### 4.1 严重前后端端口冲突（P0）
| 端口 | 前端占用 | 后端占用 | 冲突性质 |
| ---- | -------------- | ------------------------------------- | --------------- |
| 3001 | student-portal | classes（legacy，P3 合并入 core-edu） | dev server 冲突 |
| 3002 | parent-portal | iam | dev server 冲突 |
| 3003 | admin-portal | teacher-bff | dev server 冲突 |
**裁决**：**前端 4 端改用 4000-4003 端口区间**。理由：后端 3001-3010 已成事实基线（api-gateway 路由表 + 各服务自声明），前端迁移成本更低。
**整改清单**：
- ai07 修正 `apps/teacher-portal/README.md` §9.1 端口矩阵：3000→4000（teacher-portal）、3001→4001（student-portal）、3002→4002（parent-portal）、3003→4003（admin-portal）
- ai07 修正 §9.1 备注"3001-3003 已被避让"的错误描述
- ai07 修正 MF 配置示例中的 remoteEntry.js URL 端口
### 4.2 端口缺口（P1）
| 服务 | 缺失项 | 裁决 |
| ----------------------------- | ----------------------------------------- | ------------------------------------------------ |
| push-gateway | docs/01 + docs/02 未声明端口（实际 8081） | ai01 补充端口声明 |
| core-edu | gRPC 端口未正式声明 | ai03 声明为 50053 |
| content / msg / data-ana / ai | gRPC 端口未声明 | 各 AI 在 gRPC 启用阶段补充 |
| 004 §1.2 | 完全未声明端口 | **coord 在 §1.2 新增 HTTP 端口 + gRPC 端口两列** |
### 4.3 全局端口矩阵（coord 裁决基线，已同步至 004 §1.2）
| 端口 | 服务 | 用途 | 阶段 |
| ----- | -------------- | ------------------------------------ | ---- |
| 4000 | teacher-portal | HTTP（Shell） | P2 |
| 4001 | student-portal | HTTP（Remote） | P3 |
| 4002 | parent-portal | HTTP（Remote） | P4 |
| 4003 | admin-portal | HTTP（Remote） | P6 |
| 8080 | api-gateway | HTTP + /healthz + /readyz + /metrics | P1 |
| 8081 | push-gateway | HTTP + WebSocket | P5 |
| 3002 | iam | HTTP/REST | P2 |
| 50052 | iam | gRPC | P3 |
| 3003 | teacher-bff | HTTP | P2 |
| 3009 | student-bff | HTTP | P3 |
| 3010 | parent-bff | HTTP | P4 |
| 3004 | core-edu | HTTP | P3 |
| 50053 | core-edu | gRPC | P3 |
| 3005 | content | HTTP | P4 |
| 50054 | content | gRPC（待声明） | P4 |
| 3006 | data-ana | HTTP | P4 |
| 50055 | data-ana | gRPC（待声明） | P4 |
| 3007 | msg | HTTP | P5 |
| 50056 | msg | gRPC（待声明） | P5 |
| 3008 | ai | HTTP | P5 |
| 50057 | ai | gRPC（待声明） | P5 |
---
## 5. 错误码前缀审查
### 5.1 前缀不重叠审查结果
**当前已声明业务前缀互不重叠**（无两个服务声明相同前缀）：
`IAM_` / `CORE_EDU_` / `CLASSES_` / `CONTENT_` / `MSG_` / `AI_` / `DATA_ANA_` / `STUDENT_BFF_` / `PARENT_BFF_` / `PUSH_`
### 5.2 P0 问题：teacher-bff 无自有前缀
**现状**：teacher-bff 用 `BAD_GATEWAY`（无前缀），与 student-bff（`STUDENT_BFF_`）/ parent-bff（`PARENT_BFF_`）不一致，且与前端期望 `BFF_TEACHER_` 冲突。
**裁决**：**3 个 BFF 统一为 `BFF_XXX_` 风格**（BFF 在前，符合前端期望）：
- teacher-bff：`BFF_TEACHER_*`
- student-bff：`BFF_STUDENT_*`（从 `STUDENT_BFF_` 迁移）
- parent-bff：`BFF_PARENT_*`（从 `PARENT_BFF_` 迁移）
**整改**：ai03 / ai04 / ai07 同步更新文档与代码。
### 5.3 P0 问题：Python 服务信封偏离 ActionState
**现状**：data-ana / ai 用 `{success, data, degraded}` 而非 `{success, error:{code, message}}`，错误时无 `error.code`，前端无法用统一前缀路由 i18n。
**裁决**：**Python 服务统一为 ActionState 信封**：
- 成功：`{success: true, data: T}`
- 失败：`{success: false, error: {code, message, details?}}`
- 降级：`degraded` 作为 `details` 子字段（`details: {degraded: true}`）而非顶层字段
**整改**：ai06 修正 data-ana / ai 的 02-architecture-design.md §6.2 错误响应信封定义。
### 5.4 P0 问题：前端 `GW_` 期望与 api-gateway 无前缀冲突
**现状**：前端 README §9.4 声明 `GW_` → api-gateway（"ai01 已用"），但 api-gateway 文档明确"无业务错误码前缀"。
**裁决**：**api-gateway 加 `GW_` 前缀**。理由：前端 i18n 路由需要统一前缀匹配，`UNAUTHORIZED` 等纯语义码改为 `GW_UNAUTHORIZED` 等。
**整改**：ai01 修正 api-gateway 01/02 文档错误码清单，加 `GW_` 前缀。
### 5.5 P1 问题：core-edu 子模块前缀
**现状**：core-edu 主体用 `CORE_EDU_*`，classes 子模块用 `CLASSES_*`（黄金模板历史遗留）。前端期望 `EXAMS_` / `HOMEWORK_` / `GRADES_` 分前缀。
**裁决**：**core-edu 统一用 `CORE_EDU_*`**（含 exams/homework/grades 子域），classes 模块保留 `CLASSES_*`（黄金模板历史遗留，P3 合并入 core-edu 后仍保留）。前端删除 `EXAMS_` / `HOMEWORK_` / `GRADES_` 期望。
**整改**：ai07 修正 teacher-portal README §9.4 前缀期望表。
### 5.6 P1 问题：push-gateway 01/02 前缀不一致
**现状**：01 用 `UNAUTHORIZED` / `PUSH_FAILED`（混用），02 统一 `PUSH_*`。
**裁决**：**以 02 的 `PUSH_*` 为准**，ai01 修正 01 文档。
### 5.7 P2 问题：错误信封结构不一致
| 服务 | 信封结构 | 裁决 |
| ------------- | ----------------------------------------------------------- | ---------------------------------------- |
| iam | `{success:false, error:{code, message, details?, traceId}}` | ✅ 基准 |
| api-gateway | `{success:false, error:{code, message}}` | 补 `traceId` / `details` |
| push-gateway | 无信封定义 | 明确为 ActionState 对齐 |
| data-ana / ai | `{success, data, degraded}` | 改为 ActionState（见 §5.3） |
| msg | ZodError 走默认 500 | 补 `ZodError` 分支返回 400 + ActionState |
---
## 6. 裁决整改清单汇总
| # | 优先级 | 整改项 | 责任方 | 涉及文件 |
| --- | ------ | -------------------------------------------------------------------------- | --------- | ------------------------------------------------------------ |
| 1 | P0 | core-edu topic 命名统一为 `edu.teaching.*` | ai03 | core-edu `outbox.publisher.ts` + student-bff/parent-bff 文档 |
| 2 | P0 | 前端 4 端端口改用 4000-4003 | ai07 | teacher-portal README §9.1 + MF 配置 |
| 3 | P0 | teacher-bff 补 `BFF_TEACHER_` 前缀 + student/parent-bff 迁移为 `BFF_XXX_` | ai03/ai04 | 3 BFF 文档 + 代码 |
| 4 | P0 | Python 服务信封改为 ActionState | ai06 | data-ana/ai 02 文档 + 代码 |
| 5 | P0 | api-gateway 加 `GW_` 前缀 | ai01 | api-gateway 01/02 文档 + 代码 |
| 6 | P0 | iam 补 `GetChildrenByParent` / `GetParentsByStudent` proto RPC | ai02 | iam.proto + iam 02 文档 |
| 7 | P1 | 004 §7.2 补登 6 个 topic + CDC 命名规范 | coord | 004 §7.2 |
| 8 | P1 | 004 §1.2 新增 HTTP/gRPC 端口两列 | coord | 004 §1.2 |
| 9 | P1 | 004 §4.1 补充 gRPC 启用阶段矩阵 | coord | 004 §4.1 |
| 10 | P1 | 004 §12.2 补充派生数据事件 Outbox 豁免条款 | coord | 004 §12.2 |
| 11 | P1 | project_rules §5 包名规范改为 `next_edu_cloud.*` | coord | project_rules §5 |
| 12 | P1 | iam.proto 补 4 个 RPC（Viewport/EffectivePermissions/Logout/GetPublicKey） | ai02 | iam.proto + iam 02 文档 |
| 13 | P1 | content.proto 补 Chapter/Question 域 | ai05 | content.proto + content 02 文档 |
| 14 | P1 | core_edu.proto 补 Attendance 域 | ai03 | core_edu.proto + core-edu 02 文档 |
| 15 | P1 | events.proto 补 NotificationEvent/AIUsageEvent/UserEvent/RoleEvent | coord | events.proto |
| 16 | P1 | buf.gen.yaml 补 gRPC 插件 | coord | buf.gen.yaml |
| 17 | P1 | ai07 修正前端 4 处端点不一致 | ai07 | teacher-portal README §1.3.1 + §3.5 |
| 18 | P1 | content 补 Outbox 实现 | ai05 | content 代码 + 02 文档 |
| 19 | P1 | msg 明确发布 `edu.notification.events` topic | ai05 | msg 02 文档 + 代码 |
| 20 | P2 | api-gateway 信封补 traceId/details | ai01 | api-gateway 02 文档 |
| 21 | P2 | push-gateway 定义 ActionState 信封 | ai01 | push-gateway 02 文档 |
| 22 | P2 | msg ZodError 走 GlobalErrorFilter 返回 400 | ai05 | msg 代码 |
| 23 | P2 | core-edu 完整错误码清单文档化 | ai03 | core-edu 02 文档 |
| 24 | P2 | 建立 `infra/port-allocation.md` 全局端口表 | coord | infra/port-allocation.md |
---
## 7. 裁决生效说明
- 本章节裁决自发布之日起生效，各 AI 在下一阶段实施时必须遵循
- **裁决的设计意图已沉淀到 [004 架构影响地图](./004_architecture_impact_map.md) 对应章节**（§1.2 端口矩阵、§4.2 gRPC 启用阶段矩阵、§7.2 topic 补登、§11.2 包名规范、§11.4 错误码前缀矩阵、§12.2 Outbox 豁免条款）
- 整改清单中标注"coord"的责任项由协调 AI 执行，标注具体 AI 的由对应开发 AI 执行
- 整改完成后各 AI 需在 `docs/troubleshooting/known-issues.md` 工作经验日志区追加记录
- 若整改涉及源码修改，必须运行 `pnpm run arch:scan` 更新 arch.db
---
## 8. 总裁裁决落实记录（2026-07-09）
> 本节记录总裁最终裁决（[president-final-rulings.md](./president-final-rulings.md)）对本审查报告裁决的落实情况。
### 8.1 已落实项
| 审查章节 | 裁决内容 | 落实状态 |
| --------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| §2.3 gRPC 启用时机 | iam gRPC server 50052 从 P3 前移到 P2（I1 裁决） | ✅ 已同步至 004 §4.2 + port-allocation.md §5 |
| §3.2 topic 补登 | 新增 `edu.iam.audit.created` + notification 4 个具体动作 topic + warning.triggered 复用 mastery topic | ✅ 已同步至 004 §7.2 |
| §3.5 NotificationRequested 发布方 | 归 msg 发布，topic `edu.notification.requested` | ✅ 已同步至 004 §7.2 |
| §6 整改清单 | content QuestionService 从 P5 前移到 P4（N3 裁决） | ✅ 已同步至 004 §16.7.4/§16.7.5 |
### 8.2 批次 0 产出（本日完成）
| 产出项 | 文件 | 状态 |
| ----------------------- | ------------------------------------------------------------------ | -------------------------------------------------------- |
| iam.proto 8 RPC 补全 | `packages/shared-proto/proto/iam.proto` | ✅ 12 RPC |
| content.proto 补全 | `packages/shared-proto/proto/content.proto` | ✅ 4 service / 22 RPC |
| msg.proto 补全 | `packages/shared-proto/proto/msg.proto` | ✅ 3 service / 13 RPC |
| analytics.proto 扩展 | `packages/shared-proto/proto/analytics.proto` | ✅ 12 RPC（含 Stream） |
| core_edu.proto 补全 | `packages/shared-proto/proto/core_edu.proto` | ✅ 5 service（+ClassService +AttendanceService） |
| ai.proto 补全 | `packages/shared-proto/proto/ai.proto` | ✅ 6 RPC（+GenerateLessonPlan +StreamGenerateQuestion） |
| events.proto AuditEvent | `packages/shared-proto/proto/events.proto` | ✅ 9 message（+AuditEvent） |
| buf.gen.yaml gRPC 插件 | `packages/shared-proto/buf.gen.yaml` | ✅ go + python gRPC 插件 |
| shared-ts Outbox 工具包 | `packages/shared-ts/src/outbox/` | ✅ 6 文件（module/service/publisher/types/schema/index） |
| shared-go 包骨架 | `packages/shared-go/` | ✅ 4 模块（tracer/logger/jwks/env） |
| packages UI 骨架 | `packages/ui-tokens` + `packages/ui-components` + `packages/hooks` | ✅ 3 包 / 20 文件 |
| arch.db 更新 | `arch.db` | ✅ TS 14 模块 / Go 2 模块 / Proto 297 契约 |
### 8.3 未完事项（移交批次 1+）
- shared-go `go mod tidy` 需在 Go 环境就绪后执行（补 otel/jwt 依赖）
- `buf generate` 需在 buf CLI 就绪后执行（生成 3 语言 gRPC stub）
- packages `pnpm install` 已执行（shared-ts subagent 已验证 typecheck/lint 零错误）

287
docs/architecture/coord-final-decisions.md Normal file
View File

@@ -0,0 +1,287 @@
# Coord 最终方案强制裁决
> 版本：1.0
> 日期：2026-07-09
> 决策者：coord（经用户确认）
> 适用范围：Edu 项目全部 16 份 AI 设计文档（ai01-ai16）
> 关联文档：[004 架构影响地图 §16](./004_architecture_impact_map.md)、[ai-allocation.md](./ai-allocation.md)、[project_rules.md](../../.trae/rules/project_rules.md)
---
## 0. 裁决原则
用户反馈：**"前面简略实现后面要重写，完全没必要，直接使用最好的方式工作"**。
各 AI 设计文档中存在大量"P2 简化 → P3 重构 → P4 再重构"的渐进式过渡方案，导致前期代码后期必废弃。coord 裁决如下：
### 0.1 强制覆盖声明
- **本文档 > 各 AI 设计文档**：凡本文档列出的裁决项，各 AI 设计文档中与之冲突的"中间过渡方案"一律作废，**直接采用最终方案**
- **不分阶段**：最终方案在服务首次落地时即采用，不得以"阶段未到"为由先实现简化版
- **回写义务**：各 AI 收到本文档后，必须在 3 个工作日内回写自己的 02-architecture-design.md，删除所有"中间过渡方案"描述，对齐最终方案
### 0.2 裁决依据
- 用户明确指示"直接使用最好的方式"
- project_rules.md §3.1 已规定企业级规范（如 Dockerfile 多阶段、Zod 验证、GlobalErrorFilter），无理由分阶段
- 黄金模板 services/classes/ 已实现全部最终方案，其他服务对齐即可
---
## 1. 通用裁决（适用全部服务）
| # | 过渡项 | 禁止的中间方案 | 强制最终方案 | 影响服务 |
| --- | --------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| G1 | **Dockerfile** | "P3 重构"、"P5 重构"、"待落地" | **首次实现即多阶段构建**（builder + runtime） | 全部 |
| G2 | **/readyz 探针** | "P2 仅返回 ok"、"P3+ 补下游探针" | **首次实现即检查全部下游依赖**（DB SELECT 1 / Redis PING / Kafka 连接 / gRPC 下游可达） | 全部 |
| G3 | **/healthz** | "P2 改造" | **首次实现即 liveness 探针** | 全部 |
| G4 | **Logger** | "待引入 slog"、"console.log → P3 修复" | **首次实现即结构化日志**（TS pino / Go slog / Python structlog），禁止 console.log | 全部 |
| G5 | **Metrics** | "自定义业务指标待实现" | **首次实现即 /metrics 端点 + 基础业务指标** | 全部 |
| G6 | **Tracer** | "资源属性待补"、"span 待补" | **首次实现即 OTel SDK + OTLP exporter + 完整资源属性 + 全链路 span** | 全部 |
| G7 | **Zod 验证** | "P2 补全"、"P3 实施中"、"部分 → P4 全 parse" | **Controller 层首次实现即全量 schema.parse(body/query/params)** | 全部 TS |
| G8 | **GlobalErrorFilter** | "待落地"、"P4+ 对齐 ActionState" | **首次实现即注册 GlobalErrorFilter + 响应信封严格对齐 ActionState 结构** | 全部 |
| G9 | **优雅关闭** | "P2 补全" | **首次实现即 SIGTERM → app.close() → shutdownTracer()，按序关闭 HTTP→DB→Redis→Kafka** | 全部 |
| G10 | **DB 连接模式** | "const db vs getDb()" | **统一 getDb() 函数**（对齐 classes 黄金模板） | 全部 TS 持 DB 服务 |
| G11 | **ID 策略** | "cuid2 vs randomUUID" | **统一 cuid2**（对齐 classes 黄金模板） | 全部 TS 持 DB 服务 |
| G12 | **ESM import** | 缺 .js 后缀 | **所有相对 import 带 .js 后缀**（NestJS ESM 模式） | 全部 TS |
| G13 | **import type** | 混用 | **仅用于类型的导入必须 import type** | 全部 TS |
| G14 | **错误码前缀** | api-gateway 无前缀 | **每个服务错误码必须用服务名大写前缀**（GW_/IAM_/CORE_EDU_/CONTENT_/MSG_/DATA_ANA_/AI_/PUSH_/BFF_TEACHER_/BFF_STUDENT_/BFF_PARENT_/CLASSES_） | 全部 |
| G15 | **错误码子前缀** | 保留 EXAMS_/HOMEWORK_/GRADES_ | **统一用聚合域前缀 CORE_EDU_***，禁止子前缀 | 前端 + core-edu |
| G16 | **Kafka topic 命名** | edu.notification.events 抽象名 | **edu.\<domain>.\<aggregate>.\<action>** 具体动作（如 edu.notification.sent） | 全部 |
| G17 | **proto 包名** | 不一致 | **next_edu_cloud.\<domain>.v1** | 全部 |
---
## 2. BFF 层专项裁决（teacher-bff / student-bff / parent-bff）
| # | 过渡项 | 禁止的中间方案 | 强制最终方案 |
| --- | ------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| B1 | **API 风格** | "P2 REST → P4 GraphQL"、"P3 REST → P4+ GraphQL" | **P2 起直接 GraphQL**（GraphQL Yoga + DataLoader） |
| B2 | **对下游通信** | "P2 HTTP fetch → P3+ gRPC"、"P3 HTTP → P3+ gRPC" | **首次实现即 gRPC 调用下游**（iam/core-edu/content/data-ana/msg/ai 全部 gRPC） |
| B3 | **权限装饰器** | "BFF 加 @RequirePermission"、"待仲裁" | **BFF 豁免 @RequirePermission**（权限由 Gateway JWT + 下游服务负责），BFF 仅校验 x-user-id 存在 |
| B4 | **越权防御** | "仅 teacher-bff 透传"、"student-bff 待仲裁" | **全部 BFF 强制自我越权防御**：student-bff 比对 userId、parent-bff 校验 childId 绑定列表、teacher-bff 校验 teacherId 与班级关系 |
| B5 | **错误码前缀** | "STUDENT_BFF_ vs BFF_STUDENT_" | **BFF_TEACHER\_ / BFF_STUDENT\_ / BFF_PARENT_**（统一 BFF_ 前缀） |
| B6 | **缓存策略** | "不缓存 vs Redis 短缓存" | **Redis 5-30s 短缓存**（对齐 004 §6.2 BFF 混合读策略） |
| B7 | **Kafka 订阅** | "P3 评估"、"P5 评估" | **P2-P4 不订阅 Kafka**（仅同步聚合），P5 push-gateway 落地后再订阅 |
| B8 | **DownstreamClient 抽象** | "是否回写 teacher-bff" | **回写 teacher-bff**，作为 BFF 模式 v2 标准抽象，3 个 BFF 统一使用 |
---
## 3. 业务服务专项裁决
### 3.1 iam（ai06）
| # | 过渡项 | 禁止的中间方案 | 强制最终方案 |
| --- | ------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| I1 | **gRPC server** | "P2 仅 REST → P3 启用 gRPC" | **P2 即启用 gRPC server 50052**，同时暴露 REST + gRPC |
| I2 | **Outbox** | "iam 自建 → core-edu 落地后回写 shared-ts" | **直接建 shared-ts Outbox 工具包**，iam 首次实现即用 |
| I3 | **PermissionGuard** | "本地 ROLE_PERMISSIONS map → DB 驱动" | **首次实现即 DB 驱动 + Redis 缓存**，废弃本地 map |
| I4 | **AuthMiddleware** | "P2 不注册 → Controller 直读 header" | **首次实现即注册 AuthMiddleware**，Controller 通过 @Req() 获取用户上下文 |
| I5 | **JWT 密钥** | "P2 本地文件 → P6 Vault" | **P2 本地文件**（IAM_PRIVATE_KEY_PATH / IAM_PUBLIC_KEY_PATH），P6 迁 Vault 单列后续 |
| I6 | **家长-学生关联** | "接口缺失 → P3 补" | **P2 即补全**：iam_student_guardians 表 + GetChildrenByParent RPC + GET /iam/children REST（P0 阻塞 parent-bff） |
| I7 | **API 版本化** | "待 coord 审查" | _*采用 /iam/v1/* 前缀_*，Gateway 同步调整 |
| I8 | **iam 端点路径** | /iam/permissions/effective vs /iam/effective-permissions | **统一 GET /iam/permissions/effective**（RESTful 资源路径风格） |
### 3.2 core-edu（ai08）
| # | 过渡项 | 禁止的中间方案 | 强制最终方案 |
| --- | ----------------------------------------- | -------------------------------------- | -------------------------------------------------------------------- |
| C1 | **classes 合并** | "P3 初期 vs P3 末期" | **P3 开始前直接合并**：classes 代码迁移到 core-edu，classes 服务下线 |
| C2 | **gRPC server** | "P3 启用" | **P3 首次实现即启用 gRPC server 50053** |
| C3 | **Kafka console.log** | "P3 修复" | **首次实现即用 logger.info**，禁止 console.log |
| C4 | **AttendanceService** | "待 coord 补 proto" | **P3 首次实现即补全 proto + 实现** |
| C5 | **GetClassesByTeacher / BatchGetClasses** | "待新增" | **P3 首次实现即补全** |
| C6 | **排课 room_id** | "P3 实现 vs 预留 vs P6+" | **P3 预留字段**（不实现逻辑，但 schema 含字段） |
| C7 | **成绩计算公式** | "scope 优先级待定" | **class > subject > school**（越细粒度优先） |
| C8 | **作业 grace_period** | "0 秒 vs 300 秒" | **默认 300 秒**（5 分钟宽限） |
| C9 | **schema 强制校验** | "P3 JSON Schema vs 文档约束" | **P3 仅文档约束**，P6+ 引入 schema registry |
| C10 | **exam.submitted 事件** | "包含完整 answers vs 仅 submission_id" | **仅含 submission_id**（避免事件过大） |
| C11 | **archived 考试** | "物理迁移 vs 软删除 vs P6+" | **仅软删除**（is_archived 字段） |
### 3.3 content（ai09）
| # | 过渡项 | 禁止的中间方案 | 强制最终方案 |
| --- | ------------------- | -------------------- | ------------------------------------------------ |
| N1 | **gRPC server** | "gRPC 待实现" | **P4 首次实现即启用 gRPC server 50054** |
| N2 | **/readyz** | "仅 DB → P4 多依赖" | **首次实现即检查 DB/Neo4j/Kafka** |
| N3 | **QuestionService** | "P5 阻塞待补 proto" | **P4 即补全 QuestionService proto**（不等到 P5） |
| N4 | **ErrorFilter** | "错误响应结构待对齐" | **首次实现即对齐 ActionState** |
| N5 | **ChapterService** | "缺 GetChapter" | **P4 首次实现即补全** |
### 3.4 msg（ai10）
| # | 过渡项 | 禁止的中间方案 | 强制最终方案 |
| --- | --------------------- | --------------------------- | ----------------------------------------------------- |
| M1 | **gRPC server** | "gRPC 待实现" | **P5 首次实现即启用 gRPC server 50056** |
| M2 | **/readyz** | "仅 DB → P5 多依赖" | **首次实现即检查 DB/ES/Redis/Kafka/PushGateway** |
| M3 | **ZodError** | "未处理 → P5 处理" | **首次实现即处理 ZodError 分支** |
| M4 | **调用 push-gateway** | "gRPC PushService.Push" | **HTTP POST /internal/push**（coord 仲裁豁免 gRPC） |
| M5 | **事件 topic** | "edu.teaching.assignment.*" | **edu.teaching.homework.***（与 core-edu 发布方一致） |
### 3.5 data-ana（ai11）
| # | 过渡项 | 禁止的中间方案 | 强制最终方案 |
| --- | --------------------------- | --------------------- | ------------------------------------------------------------------------------------------------- |
| D1 | **ErrorFilter** | "v2 对齐 ActionState" | **首次实现即对齐 ActionState** |
| D2 | **Dockerfile** | "v2 设计多阶段" | **首次实现即多阶段** |
| D3 | **ClickHouse DDL** | "待 coord 建目录" | **直接建 infra/clickhouse/ddl/** |
| D4 | **analytics.proto 扩展** | "待 coord 审议" | **P4 即补全**：4 端 Dashboard + Warning + MasteryDistribution + SubscribeMasteryUpdate Stream RPC |
| D5 | **warning.triggered topic** | "待 coord 登记" | **已登记**，004 §7.2 + events.proto MasteryEvent |
### 3.6 ai（ai12）
| # | 过渡项 | 禁止的中间方案 | 强制最终方案 |
| --- | ---------------------- | ------------------------- | ------------------------------------------------------------------------------ |
| A1 | **ErrorFilter** | "待对齐" | **首次实现即对齐 ActionState** |
| A2 | **Dockerfile** | "实现阶段需新增" | **首次实现即多阶段** |
| A3 | **gRPC 端口** | "待 coord 补登" | **已补登 50058**（见 infra/port-allocation.md） |
| A4 | **ai.proto 补全** | "待 coord" | **P5 首次实现即补全** GenerateLessonPlan / StreamGenerateQuestion |
| A5 | **AIUsageEvent proto** | "待 coord" | **已补全** events.proto |
| A6 | **Prompt 模板存储** | "P5 YAML / P6+ DB" | **P5 直接用 DB 存储**（避免后期迁移） |
| A7 | **备课工作流** | "P5 Redis / P6+ Temporal" | **P5 用 FastAPI BackgroundTasks + Redis**（Temporal 引入成本高，P6+ 单独评估） |
| A8 | **多模态** | "P5 文本 / P6+ 多模态" | **P5 仅文本**，proto v2 预留字段 |
### 3.7 push-gateway（ai02）
| # | 过渡项 | 禁止的中间方案 | 强制最终方案 |
| --- | ------------------ | ---------------------------- | ----------------------------------------------------------------- |
| P1 | **gRPC** | "备选 gRPC PushService" | **彻底删除 gRPC 设计**，纯 HTTP + WebSocket（coord 仲裁豁免） |
| P2 | **X-Internal-Key** | "→ X-Internal-Token P5 立即" | **首次实现即 X-Internal-Token**（环境变量 INTERNAL_API_TOKEN） |
| P3 | **Dockerfile** | "P5 重构" | **首次实现即多阶段** |
| P4 | **slog** | "待引入" | **首次实现即用 slog** |
| P5 | **SSE 降级** | "P7+ 考虑" | **本期仅 HTTP 长轮询预留**，SSE 不实现 |
| P6 | **断线重连** | "本期仅协议预留" | **本期仅协议预留**（session_id + last_seq 字段），P6 实现补推逻辑 |
### 3.8 api-gateway（ai01）
| # | 过渡项 | 禁止的中间方案 | 强制最终方案 |
| --- | -------------------- | ------------------------------------------- | ----------------------------------------------------- |
| W1 | **错误码前缀** | "无前缀" | **GW_***（GW_UNAUTHORIZED 等） |
| W2 | **错误信封** | "recovery/ratelimit/circuit-breaker 待整改" | **首次实现即对齐 ActionState** |
| W3 | **slog** | "待引入" | **首次实现即用 slog** |
| W4 | **/readyz** | "待重构" | **首次实现即真实健康检查**（轮询下游 /healthz） |
| W5 | **业务 metrics** | "待实现" | **首次实现即基础业务指标**（请求量/延迟/错误率/熔断） |
| W6 | **tracer 资源属性** | "待补" | **首次实现即完整**（version/env/host） |
| W7 | **DevMode 防护** | "P1 待办" | **首次实现即生产防护**（DEV_MODE 仅非生产环境生效） |
| W8 | **per-服务实例熔断** | "P6 待办" | **保持共享 downstream 熔断**，per-实例 P6 单独评估 |
---
## 4. 前端 4 portal 专项裁决
| # | 过渡项 | 禁止的中间方案 | 强制最终方案 |
| --- | ------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| F1 | **admin-portal 端口** | 3003 / 3000 / 4003 三处矛盾 | **统一 4003** |
| F2 | **admin-portal MF 配置** | teacher_app@localhost:3000 | **teacher_app@localhost:4000** |
| F3 | **Web Vitals** | FID vs INP 混用 | **统一 INP**（CWV 2024 标准） |
| F4 | **i18n key 命名** | bff.error / bffTeacher.error / bffStudent.error 混用 | **统一 error.\<service>.\<code_snake>**（如 error.iam.invalid_credentials、error.bffTeacher.validation_error） |
| F5 | **错误码子前缀** | parent-portal 保留 GRADES_/HOMEWORK_ | **统一删除子前缀**，用 CORE_EDU_* |
| F6 | **iam 权限端点** | /iam/permissions/effective vs /iam/effective-permissions | **统一 /iam/permissions/effective** |
| F7 | **权限点命名风格** | TEACHER_DASHBOARD_VIEW / STUDENT_DASHBOARD_READ / GRADES_READ_CHILD 混用 | **统一 \<RESOURCE>\_\<ACTION>**（如 DASHBOARD_VIEW、EXAM_READ、GRADE_READ），数据范围用后缀 _OWN/_CHILD（如 GRADE_READ_CHILD） |
| F8 | **packages 归属** | "ai07/ai13 维护 vs coord 维护" | **ai13 维护 ui-tokens/ui-components/hooks，coord 仅维护 shared-ts/contracts** |
| F9 | **GraphQL vs REST** | "P2-P6 REST，未来切 GraphQL" | **P2 起 BFF 用 GraphQL，前端用 urql/apollo** |
| F10 | **MF 暴露粒度** | "AppShell 整体 vs 细粒度" | **暴露 AppShell 整体**，各 Remote 自行决定内部布局 |
| F11 | **teacher-portal 归属** | "004 §15.1 写 ai07，ai-allocation §3.2 写 ai13" | **ai13 负责 teacher-portal**（ai07 负责 classes 黄金模板） |
| F12 | **localStorage token** | "P6 评估迁移 httpOnly Cookie" | **P2 用 localStorage**（httpOnly Cookie + CSRF Token P6 单独评估） |
---
## 5. 跨服务契约裁决（一次性补全，不分阶段）
### 5.1 proto 契约补全（coord 负责，P2 启动前全部就位）
| proto 文件 | 待补内容 | 阻塞阶段 | 完成期限 |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- |
| events.proto | ✅ 已补全（UserEvent/RoleEvent/NotificationEvent/MasteryEvent/AIUsageEvent/KnowledgePointEvent/QuestionEvent） | — | 已完成 |
| iam.proto | GetViewports / GetEffectivePermissions / GetEffectiveAccess / Logout / GetPublicKey / BatchGetUsers / GetEffectiveDataScope / GetChildrenByParent | P2 | P2 启动前 |
| core_edu.proto | AttendanceService.* / GetClassesByTeacher / BatchGetClasses | P3 | P3 启动前 |
| content.proto | ChapterService.GetChapter / QuestionService.* / TextbookService.ListTextbooks 补全 | P4 | P4 启动前 |
| analytics.proto | GetTeacherDashboard / GetStudentDashboard / GetParentDashboard / GetAdminDashboard / GetWarnings / GetMasteryDistribution / SubscribeMasteryUpdate (stream) | P4 | P4 启动前 |
| ai.proto | GenerateLessonPlan / StreamGenerateQuestion / 字段扩展 | P5 | P5 启动前 |
| msg.proto | BatchSendNotification / GetUnreadCount / BatchMarkAsRead / MarkAllAsRead / RecallNotification + NotificationPreferenceService + NotificationTemplateService + 3 个 message | P5 | P5 启动前 |
### 5.2 接口命名统一
| 调用方 | 被调方 | 统一命名 | 说明 |
| ----------------- | ------------ | ------------------------------------------------------------ | ---------------------------- |
| core-edu | content | **KnowledgeGraphService.GetPrerequisites / GetLearningPath** | 禁用 ContentService 命名 |
| teacher-bff | data-ana | **GetTeacherDashboard**（无 Stats 后缀） | 统一命名 |
| msg / student-bff | push-gateway | **HTTP POST /internal/push**（body 含 user_id） | 豁免 gRPC |
| ai | core-edu | **ExamService.GetExam** | 方向：ai 调 core-edu，非反向 |
### 5.3 gRPC server 启用时机
| 服务 | gRPC 端口 | 启用时机 | 说明 |
| ------------ | --------- | --------------- | ---------------------------------- |
| iam | 50052 | **P2** | 首次实现即启用（覆盖"P2 仅 REST"） |
| core-edu | 50053 | **P3** | 首次实现即启用 |
| content | 50054 | **P4** | 首次实现即启用 |
| data-ana | 50055 | **P4** | 首次实现即启用 |
| msg | 50056 | **P5** | 首次实现即启用 |
| ai | 50058 | **P5** | 首次实现即启用 |
| push-gateway | — | **不启用** | 豁免 gRPC |
| BFF（3 个） | — | **不暴露 gRPC** | 仅对下游走 gRPC |
---
## 6. 待 P6+ 单独评估事项（不阻塞当前阶段）
以下事项不属于"中间过渡方案"，属于"未来扩展"，保持原状：
| # | 事项 | 评估时机 |
| --- | ------------------------------------------------------------------- | --------- |
| X1 | ai 发布 edu.insight.ai.generated / feedback / workflow 3 个新 topic | P6+ |
| X2 | admin-portal 8 个新 Kafka topic + events.proto message | P6 实施时 |
| X3 | admin-portal 审计日志/安全事件归属（iam vs audit-service） | P6 |
| X4 | ai 备课工作流迁移 Temporal | P6+ |
| X5 | ai Prompt 模板 DB 存储迁移（已在 A6 裁决 P5 直接用 DB） | — |
| X6 | admin-portal Grafana/Jaeger iframe 嵌入 | P6 |
| X7 | teacher-portal localStorage → httpOnly Cookie 迁移 | P6 |
| X8 | iam JWT 密钥迁移 Vault | P6 |
| X9 | api-gateway per-服务实例熔断 | P6 |
| X10 | schema registry 引入（events.proto 强制校验） | P6+ |
---
## 7. 各 AI 回写义务
各 AI 收到本文档后，必须执行以下回写：
### 7.1 回写内容
1. 删除自己 02-architecture-design.md 中所有"中间过渡方案"描述
2. 对齐本文档的最终方案
3. 更新 §8 风险与假设（移除已裁决项）
### 7.2 回写期限
| AI | 服务 | 回写期限 | 阻塞阶段 |
| ---- | -------------- | ---------------------- | -------- |
| ai01 | api-gateway | P2 启动前 | — |
| ai02 | push-gateway | P5 启动前 | — |
| ai03 | teacher-bff | **P2 启动前** | P2 |
| ai04 | student-bff | P3 启动前 | — |
| ai05 | parent-bff | P4 启动前 | — |
| ai06 | iam | **P2 启动前** | P2 |
| ai07 | classes | 已是黄金模板，无需回写 | — |
| ai08 | core-edu | P3 启动前 | — |
| ai09 | content | P4 启动前 | — |
| ai10 | msg | P5 启动前 | — |
| ai11 | data-ana | P4 启动前 | — |
| ai12 | ai | P5 启动前 | — |
| ai13 | teacher-portal | **P2 启动前** | P2 |
| ai14 | student-portal | P3 启动前 | — |
| ai15 | parent-portal | P4 启动前 | — |
| ai16 | admin-portal | P6 启动前 | — |
### 7.3 coord 验收
各 AI 回写完成后，coord 将重新运行 §8 交叉审查，确认无"中间过渡方案"残留。
---
## 8. 变更记录
| 日期 | 变更 | 决策者 |
| ---------- | --------------------------------------------------------------------------------------------------------------------- | ----------------- |
| 2026-07-09 | 初始创建，覆盖 G1-G17 / B1-B8 / I1-I8 / C1-C11 / N1-N5 / M1-M5 / D1-D5 / A1-A8 / P1-P6 / W1-W8 / F1-F12 共 80+ 项裁决 | coord（用户确认） |

129
docs/architecture/issues/contracts/admin-portal_contract.md Normal file
View File

@@ -0,0 +1,129 @@
# admin-portal 对接契约
> 负责人：ai16
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无。admin-portal 是前端微前端 Remote。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | ----------- | ---------------- | --------------------- |
| GET | / | 管理后台首页 | JWT 必需 + admin 角色 |
| GET | /users | 用户管理 | JWT 必需 + admin |
| GET | /roles | 角色权限管理 | JWT 必需 + admin |
| GET | /classes | 班级管理（全局） | JWT 必需 + admin |
| GET | /teachers | 教师管理 | JWT 必需 + admin |
| GET | /students | 学生管理 | JWT 必需 + admin |
| GET | /audit-logs | 审计日志 | JWT 必需 + admin |
| GET | /dashboard | 管理员仪表盘 | JWT 必需 + admin |
| GET | /system | 系统配置 | JWT 必需 + admin |
### 1.3 GraphQL schema（如 BFF）
不适用。admin-portal 消费 teacher-bff GraphQL admin namespace，自身不提供 schema。
### 1.4 Kafka 事件发布（如有）
无。
### 1.5 错误码前缀
无（前端不定义错误码前缀，透传 BFF 错误码）。
### 1.6 微前端架构（补充）
| 角色 | 说明 |
| ---------------------- | ----------------------------------------------- |
| MF Remote | 管理后台是微前端远程模块 |
| 暴露的 remote 模块 | AdminApp（管理后台完整应用）、shared 管理端组件 |
| module federation 配置 | `apps/admin-portal/module-federation.config.ts` |
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无。前端不直接调 gRPC。
### 2.2 Kafka 事件订阅（异步）
无。前端不直接订阅 Kafka（审计日志通过 GraphQL 查询，非直接订阅）。
### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
| ------------------- | ----------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------- |
| api-gateway (ai01) | POST /api/admin/graphql | 管理 GraphQL 查询（经网关代理到 teacher-bff admin namespace） | api-gateway/teacher-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 |
| api-gateway (ai01) | POST /api/auth/login | 管理员登录 | api-gateway 就绪前使用 MSW 返回固定 JWT（admin 角色） |
| push-gateway (ai02) | GET /ws | WebSocket 实时通知 | push-gateway 就绪前使用 mock-socket 模拟 WS 推送 |
### 2.4 GraphQL 查询域（经 api-gateway 代理到 teacher-bff admin namespace）
| Query/Mutation | 用途 | mock 策略 |
| ------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
| currentUser | 当前管理员信息 | MSW 返回固定管理员（admin 角色） |
| adminUsers / createUser / updateUser / deleteUser | 用户管理 | MSW 返回固定 50 个用户 + CRUD success |
| adminRoles / updateRolePermissions | 角色权限管理 | MSW 返回固定 5 个角色 + 权限矩阵 |
| adminClasses | 班级管理（全局） | MSW 返回固定 20 个班级 |
| adminTeachers | 教师管理 | MSW 返回固定 50 个教师 |
| adminStudents | 学生管理 | MSW 返回固定 1200 个学生 |
| auditLogs | 审计日志（聚合 iam AuditEvent） | MSW 返回固定 100 条审计日志 |
| adminDashboard | 管理员仪表盘 | MSW 返回固定仪表盘（total_teachers=50, total_students=1200, school_avg_score=80.0） |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] api-gateway HTTP :8080 启用（ai01）—— 前端请求入口 + admin 角色校验
- [ ] teacher-bff GraphQL :3003 启用（ai03）—— admin namespace 可用
- [ ] iam gRPC 50052 启用（ai06）—— 用户/角色/审计日志数据来源
- [ ] edu.iam.audit.created topic 有事件发布（ai06）—— 审计日志来源
- [ ] data-ana gRPC 50055 启用（ai11）—— adminDashboard 数据来源
- [ ] push-gateway WebSocket :8081/ws 启用（ai02）—— 实时通知
### 3.2 我的就绪标志（供下游消费）
- [ ] admin-portal dev server :4003 启用
- [ ] MF Remote 可被 AppShell 加载（暴露 AdminApp 模块）
- [ ] 独立壳渲染（首页 + 导航 + 路由守卫 + admin 角色校验）
- [ ] 登录流程可用（POST /api/auth/login 获取 JWT，前端校验 admin 角色）
- [ ] GraphQL 查询可执行（currentUser / adminDashboard / auditLogs 返回数据）
- [ ] 用户/角色 CRUD 可执行（createUser / updateRolePermissions）
- [ ] WebSocket 通知可接收
---
## §4 Mock 策略
### 4.1 我提供的 mock
admin-portal 是前端，无下游消费方。但对开发体验提供：
- **Storybook**：各组件独立 story（含权限矩阵编辑器、审计日志表格等复杂组件）
- **MSW handlers**：`apps/admin-portal/src/mocks/handlers.ts`，拦截所有 GraphQL/HTTP 请求
### 4.2 我消费的 mock
在真实上游就绪前，admin-portal 使用以下 mock：
- **HTTP/GraphQL mock**：使用 MSW 拦截所有请求
- POST /api/auth/login → 返回固定 JWT + UserInfo（admin 角色，permissions=["*"]）
- POST /api/admin/graphql → 根据 operationName 返回对应 mock 响应（与 teacher-bff admin namespace mock 数据一致）
- auditLogs mock 返回固定 100 条审计日志（含 action: create/update/delete/login/logout/permission_change）
- adminDashboard mock 返回固定全校统计仪表盘
- 所有 mock 响应定义在 `apps/admin-portal/src/mocks/fixtures/*.json`
- **WebSocket mock**：使用 mock-socket 库
- 连接后每 30 秒推送 1 条 mock 系统通知
- **JWT mock**：使用固定 mock JWT（admin 角色），存入 httpOnly cookie
- **权限矩阵 mock**：内置固定 5 个角色 + 完整权限矩阵（teacher/student/parent/admin/super_admin）
- **环境切换**：通过 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制，上游就绪后设为 `disabled`

108
docs/architecture/issues/contracts/ai_contract.md Normal file
View File

@@ -0,0 +1,108 @@
# ai 对接契约
> 负责人：ai12
> 关联：[matrix.md](./matrix.md)、[ai.proto](../../../packages/shared-proto/proto/ai.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| --------- | ---------------------- | ----------------------------- | ------------------------ | ----- |
| AiService | Chat | ChatRequest | ChatResponse | 50057 |
| AiService | StreamChat | ChatRequest | stream ChatChunk | 50057 |
| AiService | GenerateQuestion | GenerateQuestionRequest | GeneratedQuestion | 50057 |
| AiService | OptimizeExpression | OptimizeExpressionRequest | OptimizedExpression | 50057 |
| AiService | GenerateLessonPlan | GenerateLessonPlanRequest | LessonPlan | 50057 |
| AiService | StreamGenerateQuestion | StreamGenerateQuestionRequest | stream GeneratedQuestion | 50057 |
### 1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC（含 2 个 Server Streaming RPC：StreamChat / StreamGenerateQuestion）。
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
| ------------------- | ---------------------------------------------------------------------------------------- | -------- |
| edu.ai.usage.events | AIUsageEvent（operation: chat/generate_question/optimize_expression/lesson_preparation） | data-ana |
> 注：AIUsageEvent 豁免 Outbox 模式（派生数据事件，见 004 §12.2 + §15.3 #6）。
### 1.5 错误码前缀
`AI_`（如 AI_PROVIDER_UNAVAILABLE、AI_TOKEN_LIMIT_EXCEEDED、AI_CONTENT_FILTERED）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
| 被调用方 | Service.RPC | 用途 | mock 策略 |
| --------------- | -------------------------------------- | ---------------------------- | ----------------------------------------------------------- |
| content (ai09) | KnowledgeGraphService.GetPrerequisites | 生成题目时获取知识点前置依赖 | content 就绪前使用本地知识点 stub（固定 3 个前置知识点） |
| content (ai09) | QuestionService.SearchQuestions | 备课时检索同类题目参考 | content 就绪前返回空列表 |
| data-ana (ai11) | AnalyticsService.GetStudentWeakness | 个性化出题时获取学生薄弱点 | data-ana 就绪前使用本地薄弱点 stub（固定 2 个 weak_points） |
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
| ---------------------------------- | ------------------- | -------------- | -------------------------------------- |
| edu.content.knowledge_point.events | KnowledgePointEvent | content (ai09) | content 就绪前不订阅，使用内置知识点表 |
| edu.content.question.events | QuestionEvent | content (ai09) | content 就绪前忽略 |
### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
| -------------------------------- | ------------------------- | ------------------ | ------------------------------------------------------------------ |
| LLM Provider（OpenAI/百川/本地） | POST /v1/chat/completions | 调用大模型生成内容 | 开发期使用本地 mock server 返回固定 ChatResponse，不消耗真实 token |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] content gRPC 50054 启用（ai09）—— 知识点维度 + 题库检索
- [ ] edu.content.knowledge_point.events topic 有事件发布（ai09）
- [ ] data-ana gRPC 50055 启用（ai11）—— 学生薄弱点（可选，ai 可先独立运行）
### 3.2 我的就绪标志（供下游消费）
- [ ] ai gRPC 50057 启用（HealthService.Check 返回 SERVING）
- [ ] AiService.Chat / StreamChat 可调用（含流式响应）
- [ ] AiService.GenerateQuestion / StreamGenerateQuestion 可调用
- [ ] AiService.GenerateLessonPlan 可调用（P5 补全）
- [ ] AiService.OptimizeExpression 可调用
- [ ] edu.ai.usage.events topic 可发布（供 data-ana 统计 AI 用量）
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 ai 真实服务就绪前，为下游（teacher-bff）提供以下 mock：
- **gRPC mock**：使用 grpc-mock 拦截 50057 端口
- AiService.Chat 返回固定 ChatResponse（content="这是 AI 助手的模拟回复"）
- AiService.StreamChat 返回固定流（3 个 ChatChunk，最后一个 done=true）
- AiService.GenerateQuestion 返回固定 GeneratedQuestion（question/answer/explanation）
- AiService.GenerateLessonPlan 返回固定 LessonPlan（3 个 LessonSection）
- AiService.StreamGenerateQuestion 返回固定流（2 个 GeneratedQuestion）
- **Kafka mock**：ai 就绪前不发布真实 AIUsageEvent，data-ana 仪表盘 AI 用量显示"暂无数据"
### 4.2 我消费的 mock
在真实上游就绪前，ai 使用以下 mock：
- **LLM Provider mock**：本地启动 mock server，POST /v1/chat/completions 返回固定 JSON（不消耗真实 token，不产生费用）
- **content 知识点**：内置固定知识点表（数学 20 个知识点 + 前置依赖关系），不依赖 content gRPC
- **data-ana 薄弱点**：内置固定学生薄弱点（2 个 weak_points），不依赖 data-ana gRPC
- **事件订阅**：不订阅 content 事件，知识点维度表静态

102
docs/architecture/issues/contracts/api-gateway_contract.md Normal file
View File

@@ -0,0 +1,102 @@
# api-gateway 对接契约
> 负责人：ai01
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无。api-gateway 是 HTTP 入口，不对外提供 gRPC。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | -------------- | ------------------------------------------- | ---------------------- |
| ANY | /api/auth/* | 代理到 iam 认证相关（登录/注册/刷新 token） | 公开（登录注册免认证） |
| ANY | /api/teacher/* | 代理到 teacher-bff GraphQL（:3003） | JWT 必需 |
| ANY | /api/student/* | 代理到 student-bff GraphQL（:3009） | JWT 必需 |
| ANY | /api/parent/* | 代理到 parent-bff GraphQL（:3010） | JWT 必需 |
| ANY | /api/admin/* | 代理到 teacher-bff GraphQL admin namespace | JWT 必需 + admin 角色 |
| GET | /healthz | 网关健康检查（liveness） | 公开 |
| GET | /readyz | 网关就绪检查（readiness，含 iam 连通性） | 公开 |
| GET | /metrics | Prometheus 指标端点 | 公开（内网） |
### 1.3 GraphQL schema（如 BFF）
不适用。api-gateway 仅做 HTTP 反向代理 + JWT 验签，不解析 GraphQL。
### 1.4 Kafka 事件发布（如有）
无。api-gateway 不发布事件。
### 1.5 错误码前缀
`GW_`（如 GW_UNAUTHORIZED、GW_RATE_LIMITED、GW_CIRCUIT_OPEN、GW_BACKEND_UNAVAILABLE）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
| 被调用方 | Service.RPC | 用途 | mock 策略 |
| ---------- | ----------------------------- | ---------------------------------------- | ----------------------------------------------------------------- |
| iam (ai06) | IamService.GetPublicKey | 启动时拉取 RS256 公钥，用于 JWT 验签 | iam 就绪前使用本地固定 mock 公钥（与 mock 私钥配对签发 mock JWT） |
| iam (ai06) | IamService.GetEffectiveAccess | 权限校验（可选，部分路由需要细粒度权限） | iam 就绪前放行所有请求（仅校验 JWT 签名） |
### 2.2 Kafka 事件订阅（异步）
无。api-gateway 不订阅 Kafka 事件。
### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
| ------------------ | ------------- | --------------------------- | -------------------------------------------------- |
| teacher-bff (ai03) | POST /graphql | 反向代理教师端 GraphQL 请求 | teacher-bff 就绪前返回 502，前端使用本地 mock 数据 |
| student-bff (ai04) | POST /graphql | 反向代理学生端 GraphQL 请求 | student-bff 就绪前返回 502 |
| parent-bff (ai05) | POST /graphql | 反向代理家长端 GraphQL 请求 | parent-bff 就绪前返回 502 |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] iam gRPC 50052 启用（ai06）—— GetPublicKey 拉取验签公钥
- [ ] teacher-bff GraphQL :3003 启用（ai03）
- [ ] student-bff GraphQL :3009 启用（ai04）
- [ ] parent-bff GraphQL :3010 启用（ai05）
### 3.2 我的就绪标志（供下游消费）
- [ ] api-gateway HTTP :8080 启用（/healthz 返回 200）
- [ ] /readyz 返回 200（含 iam 连通性检查通过）
- [ ] JWT 验签链路打通（使用 iam 公钥校验 access_token）
- [ ] /api/auth/* 代理到 iam 认证链路可用
- [ ] /api/teacher/* /api/student/* /api/parent/* 反向代理到各 BFF 可用
- [ ] 限流（IP 级令牌桶）+ 熔断（各后端独立熔断器）生效
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 api-gateway 真实就绪前，为下游（各前端 portal）提供以下 mock：
- **HTTP mock**：使用 MSW（Mock Service Worker）或本地 nginx 拦截
- /api/auth/login 返回固定 JWT（mock 签发）+ UserInfo
- /api/teacher/* /api/student/* /api/parent/* 直接返回各 BFF 的 mock GraphQL 响应
- /healthz /readyz 返回 200
- **JWT mock**：前端开发期使用固定 mock JWT（api-gateway 就绪前不走真实验签）
### 4.2 我消费的 mock
在真实上游就绪前，api-gateway 使用以下 mock：
- **iam 公钥**：使用本地固定 mock RS256 公钥（与 mock 私钥配对），验签 mock JWT
- **iam 权限校验**：GetEffectiveAccess 返回 allowed=true，放行所有请求
- **各 BFF 代理**：BFF 就绪前返回 503 + Retry-After，前端降级到本地 mock 数据

123
docs/architecture/issues/contracts/classes_contract.md Normal file
View File

@@ -0,0 +1,123 @@
# classes 对接契约
> 负责人：ai07
> 关联：[matrix.md](../matrix.md)、[classes.proto](../../../packages/shared-proto/proto/classes.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)、[02-architecture-design.md](../../../services/classes/docs/02-architecture-design.md)
> 状态：黄金模板（P1 已实现），P3 合并入 core-edu
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| ------------ | ----------- | ------------------ | ------------------- | ------------------------------- |
| ClassService | CreateClass | CreateClassRequest | Class | 50053（P3 启用，core-edu 承载） |
| ClassService | GetClass | GetClassRequest | Class | 50053 |
| ClassService | ListClasses | ListClassesRequest | ListClassesResponse | 50053 |
| ClassService | UpdateClass | UpdateClassRequest | Class | 50053 |
| ClassService | DeleteClass | DeleteClassRequest | Empty | 50053 |
> **注意**：classes 当前仅 REST（端口 3001），gRPC server 50053 在 P3 合并入 core-edu 后启用。proto 契约已就绪（classes.proto），由 core-edu 实现承载。
### 1.2 HTTP 端点（如有）
| Method | Path | 权限 | 说明 |
| ------ | -------------- | ---------------- | ----------------------------- |
| POST | `/classes` | `CLASSES_CREATE` | 创建班级 |
| GET | `/classes` | `CLASSES_READ` | 列表（可选 `?gradeId=` 过滤） |
| GET | `/classes/:id` | `CLASSES_READ` | 单条查询 |
| PUT | `/classes/:id` | `CLASSES_UPDATE` | 更新 |
| DELETE | `/classes/:id` | `CLASSES_DELETE` | 删除（先校验存在） |
| GET | `/healthz` | 无 | liveness |
| GET | `/readyz` | 无 | readiness（校验 DB） |
| GET | `/metrics` | 无 | Prometheus 指标 |
> **响应信封**：ActionState（`{success:true, data:T}` / `{success:false, error:{code,message,details?,traceId?}}`）
### 1.3 GraphQL schema（如 BFF）
不适用。classes 是业务服务，非 BFF。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 | 阶段 |
| --------------------------- | --------------------------------- | ------------------------------- | ------------------- |
| `edu.org.class.created` | ClassEvent（action: created） | data-ana（建宽表行） | P3（core-edu 承载） |
| `edu.org.class.updated` | ClassEvent（action: updated） | data-ana、msg（班主任变更通知） | P3 |
| `edu.org.class.deleted` | ClassEvent（action: deleted） | data-ana、core-edu（关联检查） | P3 |
| `edu.org.class.transferred` | ClassEvent（action: transferred） | msg（通知新/旧班主任） | P3 |
> **事件 message**：`events.proto` 的 `ClassEvent`（event_id / aggregate_id / event_type / occurred_at / class_id / name / action / metadata）
> **发布方式**：Outbox 模式（P3 补齐 `shared/outbox/`），保证事务与事件最终一致
### 1.5 错误码前缀
`CLASSES_`（004 §11.4 确认保留，P3 合并入 core-edu 后保留历史遗留前缀）
| 错误码 | HTTP | 触发条件 |
| --------------------------- | ---- | ----------------------------- |
| `CLASSES_VALIDATION_ERROR` | 400 | Zod 校验失败 / 空 update body |
| `CLASSES_NOT_FOUND` | 404 | 资源不存在 |
| `CLASSES_PERMISSION_DENIED` | 403 | PermissionGuard 校验失败 |
| `CLASSES_CONFLICT` | 409 | 并发冲突（预留） |
| `CLASSES_BUSINESS_ERROR` | 422 | 业务规则违反（预留） |
| `CLASSES_DATABASE_ERROR` | 500 | DB 操作失败 |
| `CLASSES_INTERNAL_ERROR` | 500 | 未预期异常 |
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
当前无。P3 合并入 core-edu 后，可能调用 iam 的 `BatchGetUsers`（班主任信息批量查询）。
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 消费动作 | 阶段 |
| --------------------------- | ---------------------------- | -------------------------------------------- | ---- |
| `edu.identity.user.deleted` | UserEvent（action: deleted） | 若 deleted user 是班主任，置空 headTeacherId | P3 |
### 2.3 HTTP 调用（如有）
无。classes 是基础数据源，不反向调用其他服务。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] MySQL classes_db 可用（已就绪，P1）
- [ ] api-gateway `/classes/*` 路由已注册（已就绪，P1）
- [ ] P3：iam `BatchGetUsers` gRPC 可用（班主任信息查询）
- [ ] P3：Kafka `edu.identity.user.deleted` topic 可消费
### 3.2 我的就绪标志（供下游消费）
- [x] classes REST API 5 端点可用（P1 已实现）
- [x] `/healthz` + `/readyz` 可用（P1 已实现）
- [x] `/metrics` 可用（P1 已实现）
- [ ] P3：gRPC 50053 启用（由 core-edu 承载，`ClassService` 5 RPC 可调用）
- [ ] P3：`edu.org.class.created/updated/deleted/transferred` topic 可发布
- [ ] P3：Outbox 模式落地（`shared/outbox/` 目录补齐）
---
## §4 Mock 策略
### 4.1 我提供的 mock
classes 是 P1 黄金模板，REST API 已实现，**下游无需 mock，可直接调用真实服务**。
但为 P3 gRPC 迁移期间兼容，提供以下 mock 供下游在 gRPC 未启用时使用：
- **REST mock**（已可用）：直接调用 `http://classes:3001/classes/*`，返回真实数据
- **gRPC mock**（P3 过渡期）：grpc-mock 拦截 50053，ClassService 5 RPC 返回固定 Class 数据
- **Kafka mock**（P3 过渡期）：classes 事件未发布前，下游订阅方使用本地 stub（固定 ClassEvent JSON）
### 4.2 我消费的 mock
- P3 期间 iam `BatchGetUsers` 未就绪时，使用 grpc-mock 返回固定用户信息（班主任姓名）
- P3 期间 `edu.identity.user.deleted` topic 未就绪时，使用本地 Kafka mock consumer stub

110
docs/architecture/issues/contracts/content_contract.md Normal file
View File

@@ -0,0 +1,110 @@
# content 对接契约
> 负责人：ai09
> 关联：[matrix.md](./matrix.md)、[content.proto](../../../packages/shared-proto/proto/content.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| --------------------- | ------------------ | ------------------------- | -------------------------- | ----- |
| TextbookService | CreateTextbook | CreateTextbookRequest | Textbook | 50054 |
| TextbookService | GetTextbook | GetTextbookRequest | Textbook | 50054 |
| TextbookService | ListTextbooks | ListTextbooksRequest | ListTextbooksResponse | 50054 |
| ChapterService | GetChapter | GetChapterRequest | Chapter | 50054 |
| ChapterService | ListChapters | ListChaptersRequest | ListChaptersResponse | 50054 |
| ChapterService | CreateChapter | CreateChapterRequest | Chapter | 50054 |
| ChapterService | UpdateChapter | UpdateChapterRequest | Chapter | 50054 |
| KnowledgeGraphService | GetPrerequisites | GetPrerequisitesRequest | KnowledgePointsResponse | 50054 |
| KnowledgeGraphService | GetLearningPath | GetLearningPathRequest | LearningPath | 50054 |
| KnowledgeGraphService | AddPrerequisite | AddPrerequisiteRequest | AddPrerequisiteResponse | 50054 |
| KnowledgeGraphService | RemovePrerequisite | RemovePrerequisiteRequest | RemovePrerequisiteResponse | 50054 |
| QuestionService | CreateQuestion | CreateQuestionRequest | Question | 50054 |
| QuestionService | GetQuestion | GetQuestionRequest | Question | 50054 |
| QuestionService | ListQuestions | ListQuestionsRequest | ListQuestionsResponse | 50054 |
| QuestionService | UpdateQuestion | UpdateQuestionRequest | Question | 50054 |
| QuestionService | DeleteQuestion | DeleteQuestionRequest | DeleteQuestionResponse | 50054 |
| QuestionService | PublishQuestion | PublishQuestionRequest | PublishQuestionResponse | 50054 |
| QuestionService | SearchQuestions | SearchQuestionsRequest | SearchQuestionsResponse | 50054 |
### 1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC。
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
| ---------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------- |
| edu.content.knowledge_point.events | KnowledgePointEvent（action: created/updated/prerequisite_added/prerequisite_removed） | data-ana / ai / Neo4j Sync Worker / ES Sync Worker |
| edu.content.question.events | QuestionEvent（action: created/updated/published/deleted） | data-ana |
### 1.5 错误码前缀
`CONTENT_`（如 CONTENT_TEXTBOOK_NOT_FOUND、CONTENT_QUESTION_DUPLICATE）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无直接 gRPC 调用上游。content 通过 Kafka 事件接收 core-edu 班级/学生变更用于数据一致性。
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
| ---------------- | --------------------------------- | --------------- | ----------------------------------------------------- |
| edu.class.events | ClassEvent（action: transferred） | core-edu (ai08) | core-edu 就绪前不订阅，content 内部不依赖班级实时数据 |
| edu.exam.events | ExamEvent | core-edu (ai08) | core-edu 就绪前忽略，题目关联知识点不依赖考试事件 |
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] core-edu gRPC 50053 启用（ai08）—— 用于知识点与班级关联（可选，content 可先独立运行）
- [ ] edu.class.events / edu.exam.events topic 有事件发布（ai08）
### 3.2 我的就绪标志（供下游消费）
- [ ] content gRPC 50054 启用（HealthService.Check 返回 SERVING）
- [ ] TextbookService 3 RPC 可调用
- [ ] ChapterService 4 RPC 可调用
- [ ] KnowledgeGraphService 4 RPC 可调用（GetPrerequisites/GetLearningPath/AddPrerequisite/RemovePrerequisite）
- [ ] QuestionService 7 RPC 可调用（含 SearchQuestions 全文检索）
- [ ] edu.content.knowledge_point.events / edu.content.question.events topic 可发布
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 content 真实服务就绪前，为下游（teacher-bff / student-bff / ai / data-ana）提供以下 mock：
- **gRPC mock**：使用 grpc-mock 拦截 50054 端口
- TextbookService.ListTextbooks 返回固定 5 个 Textbook（语数英理化）
- ChapterService.ListChapters 返回固定章节树（每教材 10 章）
- KnowledgeGraphService.GetLearningPath 返回固定 8 个 KnowledgePoint 推荐顺序
- KnowledgeGraphService.GetPrerequisites 返回固定 3 个前置知识点
- QuestionService.SearchQuestions 返回固定 20 个 Question（含 options）
- **Kafka mock**：content 就绪前不发布真实事件，下游使用本地 stub
### 4.2 我消费的 mock
在真实 core-edu 就绪前，content 使用以下 mock：
- 班级/学生数据：不依赖 core-edu 实时数据，知识点关联使用固定 subject_id/grade
- 事件订阅：不订阅 edu.class.events / edu.exam.events，内部数据自洽

118
docs/architecture/issues/contracts/core-edu_contract.md Normal file
View File

@@ -0,0 +1,118 @@
# core-edu 对接契约
> 负责人：ai08
> 关联：[matrix.md](./matrix.md)、[core_edu.proto](../../../packages/shared-proto/proto/core_edu.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| ----------------- | ----------------------- | ------------------------------ | --------------------------- | ----- |
| ClassService | GetClass | GetClassRequest | ClassInfo | 50053 |
| ClassService | GetClassesByTeacher | GetClassesByTeacherRequest | GetClassesByTeacherResponse | 50053 |
| ClassService | BatchGetClasses | BatchGetClassesRequest | BatchGetClassesResponse | 50053 |
| ClassService | ListStudentsByClass | ListStudentsByClassRequest | ListStudentsByClassResponse | 50053 |
| ExamService | CreateExam | CreateExamRequest | CreateExamResponse | 50053 |
| ExamService | GetExam | GetExamRequest | Exam | 50053 |
| ExamService | ListExamsByClass | ListExamsByClassRequest | ListExamsResponse | 50053 |
| ExamService | UpdateExam | UpdateExamRequest | UpdateExamResponse | 50053 |
| ExamService | DeleteExam | DeleteExamRequest | DeleteExamResponse | 50053 |
| HomeworkService | AssignHomework | AssignHomeworkRequest | AssignHomeworkResponse | 50053 |
| HomeworkService | GetHomework | GetHomeworkRequest | Homework | 50053 |
| HomeworkService | ListHomeworkByClass | ListHomeworkByClassRequest | ListHomeworkResponse | 50053 |
| HomeworkService | SubmitHomework | SubmitHomeworkRequest | SubmitHomeworkResponse | 50053 |
| GradeService | RecordGrade | RecordGradeRequest | RecordGradeResponse | 50053 |
| GradeService | GetGrade | GetGradeRequest | Grade | 50053 |
| GradeService | ListGradesByStudent | ListGradesByStudentRequest | ListGradesResponse | 50053 |
| GradeService | ListGradesByExam | ListGradesByExamRequest | ListGradesResponse | 50053 |
| GradeService | ListGradesByHomework | ListGradesByHomeworkRequest | ListGradesResponse | 50053 |
| AttendanceService | RecordAttendance | RecordAttendanceRequest | RecordAttendanceResponse | 50053 |
| AttendanceService | GetAttendance | GetAttendanceRequest | Attendance | 50053 |
| AttendanceService | ListAttendanceByStudent | ListAttendanceByStudentRequest | ListAttendanceResponse | 50053 |
| AttendanceService | ListAttendanceByClass | ListAttendanceByClassRequest | ListAttendanceResponse | 50053 |
### 1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC。
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
| ------------------- | -------------------------------------------------- | -------------- |
| edu.exam.events | ExamEvent（action: created/updated/deleted） | msg / data-ana |
| edu.homework.events | HomeworkEvent（action: assigned/submitted/graded） | msg / data-ana |
| edu.grade.events | GradeEvent（action: recorded/updated） | msg / data-ana |
| edu.class.events | ClassEvent（action: transferred） | msg / data-ana |
### 1.5 错误码前缀
`CORE_EDU_`（如 CORE_EDU_CLASS_NOT_FOUND、CORE_EDU_EXAM_CONFLICT）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无直接 gRPC 调用上游。core-edu 通过 Kafka 事件接收 iam 用户变更，不主动调 iam。
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
| ------------------- | --------------------------------------------------------- | ---------- | -------------------------------------------------------------------- |
| edu.iam.user.events | UserEvent（action: created/updated/deleted/role_changed） | iam (ai06) | iam 就绪前不订阅，使用本地内置用户数据（teacher_id/student_id 固定） |
| edu.iam.role.events | RoleEvent（action: created/updated） | iam (ai06) | iam 就绪前忽略，权限校验在 core-edu 内部 mock |
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] iam gRPC 50052 启用（ai06）—— 用于用户身份一致性校验（可选，core-edu 可先独立运行）
- [ ] edu.iam.user.events topic 有事件发布（ai06）—— 用于同步用户缓存
### 3.2 我的就绪标志（供下游消费）
- [ ] core-edu gRPC 50053 启用（HealthService.Check 返回 SERVING）
- [ ] ClassService 4 RPC 可调用（GetClass/GetClassesByTeacher/BatchGetClasses/ListStudentsByClass）
- [ ] ExamService 5 RPC 可调用
- [ ] HomeworkService 4 RPC 可调用
- [ ] GradeService 5 RPC 可调用
- [ ] AttendanceService 4 RPC 可调用
- [ ] edu.exam.events / edu.homework.events / edu.grade.events / edu.class.events topic 可发布
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 core-edu 真实服务就绪前，为下游（teacher-bff / student-bff / parent-bff / content / msg / data-ana）提供以下 mock：
- **gRPC mock**：使用 grpc-mock 拦截 50053 端口
- ClassService.GetClassesByTeacher 返回固定 3 个 ClassInfo
- ClassService.ListStudentsByClass 返回固定 30 个 StudentInfo
- ExamService.ListExamsByClass 返回固定 2 个 Exam
- HomeworkService.ListHomeworkByClass 返回固定 3 个 Homework
- GradeService.ListGradesByStudent 返回固定 5 个 Grade
- AttendanceService.ListAttendanceByStudent 返回固定 10 条 Attendance
- **Kafka mock**：core-edu 就绪前不发布真实事件，下游 data-ana/msg 使用本地 stub 事件
### 4.2 我消费的 mock
在真实 iam 就绪前，core-edu 使用以下 mock：
- 用户数据：内置固定 teacher_id / student_id（不订阅 edu.iam.user.events）
- 权限校验：core-edu 内部不校验权限（由 Gateway/BFF 层负责），仅记录 created_by 字段

121
docs/architecture/issues/contracts/data-ana_contract.md Normal file
View File

@@ -0,0 +1,121 @@
# data-ana 对接契约
> 负责人：ai11
> 关联：[matrix.md](./matrix.md)、[analytics.proto](../../../packages/shared-proto/proto/analytics.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| ---------------- | ---------------------- | ----------------------------- | ------------------------- | ----- |
| AnalyticsService | GetClassPerformance | GetClassPerformanceRequest | ClassPerformance | 50055 |
| AnalyticsService | GetStudentWeakness | GetStudentWeaknessRequest | StudentWeakness | 50055 |
| AnalyticsService | GetLearningTrend | GetLearningTrendRequest | LearningTrend | 50055 |
| AnalyticsService | GetTeacherDashboard | GetTeacherDashboardRequest | TeacherDashboard | 50055 |
| AnalyticsService | GetStudentDashboard | GetStudentDashboardRequest | StudentDashboard | 50055 |
| AnalyticsService | GetParentDashboard | GetParentDashboardRequest | ParentDashboard | 50055 |
| AnalyticsService | GetAdminDashboard | GetAdminDashboardRequest | AdminDashboard | 50055 |
| AnalyticsService | GetWarningList | GetWarningListRequest | WarningListResponse | 50055 |
| AnalyticsService | TriggerWarning | TriggerWarningRequest | TriggerWarningResponse | 50055 |
| AnalyticsService | GetMasteryDistribution | GetMasteryDistributionRequest | MasteryDistribution | 50055 |
| AnalyticsService | GetStudentMastery | GetStudentMasteryRequest | StudentMastery | 50055 |
| AnalyticsService | SubscribeMasteryUpdate | SubscribeMasteryUpdateRequest | stream MasteryUpdateEvent | 50055 |
### 1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC（含 1 个 Server Streaming RPC）。
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
| --------------------------- | --------------------------------------------------------- | -------------- |
| edu.data_ana.mastery.events | MasteryEvent（action: mastery.updated/warning.triggered） | core-edu / msg |
> 注：MasteryEvent 豁免 Outbox 模式（派生数据事件，见 004 §12.2 + §15.3 #6）。
### 1.5 错误码前缀
`DATA_ANA_`（如 DATA_ANA_DASHBOARD_UNAVAILABLE、DATA_ANA_MASTERY_NOT_COMPUTED）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无主动 gRPC 调用上游。data-ana 通过 CDC + Kafka 事件接收数据，计算后发布 MasteryEvent。
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
| ---------------------------------- | ------------------- | --------------- | ------------------------------------------------- |
| edu.exam.events | ExamEvent | core-edu (ai08) | core-edu 就绪前使用 CDC 模拟数据 + 本地 stub 事件 |
| edu.homework.events | HomeworkEvent | core-edu (ai08) | 同上 |
| edu.grade.events | GradeEvent | core-edu (ai08) | 同上 |
| edu.class.events | ClassEvent | core-edu (ai08) | 同上 |
| edu.content.knowledge_point.events | KnowledgePointEvent | content (ai09) | content 就绪前使用内置知识点维度表 |
| edu.content.question.events | QuestionEvent | content (ai09) | content 就绪前忽略 |
| edu.ai.usage.events | AIUsageEvent | ai (ai12) | ai 就绪前忽略，AI 用量统计为空 |
### 2.3 HTTP 调用（如有）
无。
### 2.4 CDC 数据源（补充）
| 数据源 | 用途 | mock 策略 |
| ----------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------- |
| core-edu MySQL（exams/homework/grades/attendance 表） | Debezium CDC → Kafka 同步读模型 | core-edu 就绪前使用 ClickHouse 内置模拟数据集（30 学生 × 5 考试 × 10 作业） |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] core-edu gRPC 50053 启用（ai08）—— 业务事件 + CDC 数据源
- [ ] edu.exam.events / edu.homework.events / edu.grade.events / edu.class.events topic 有事件发布（ai08）
- [ ] content gRPC 50054 启用（ai09）—— 知识点维度
- [ ] edu.content.knowledge_point.events topic 有事件发布（ai09）
- [ ] ai gRPC 50057 启用（ai12）—— AI 用量统计（可选，仪表盘补全）
### 3.2 我的就绪标志（供下游消费）
- [ ] data-ana gRPC 50055 启用（HealthService.Check 返回 SERVING）
- [ ] AnalyticsService 12 RPC 可调用（含 4 端 Dashboard + Server Streaming SubscribeMasteryUpdate）
- [ ] GetTeacherDashboard / GetStudentDashboard / GetParentDashboard / GetAdminDashboard 返回结构化数据
- [ ] edu.data_ana.mastery.events topic 可发布（mastery.updated / warning.triggered）
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 data-ana 真实服务就绪前，为下游（teacher-bff / student-bff / parent-bff / admin-portal / msg）提供以下 mock：
- **gRPC mock**：使用 grpc-mock 拦截 50055 端口
- GetTeacherDashboard 返回固定仪表盘（total_classes=3, class_avg_score=82.5, top_students 5 个, pending_homework_count=8）
- GetStudentDashboard 返回固定仪表盘（avg_score=85.0, class_rank=5, weak_points 3 个）
- GetParentDashboard 返回固定仪表盘（child_avg_score=85.0, child_class_rank=5）
- GetAdminDashboard 返回固定仪表盘（total_teachers=50, total_students=1200, school_avg_score=80.0）
- GetWarningList 返回固定 5 条预警（severity: warning/critical）
- GetMasteryDistribution 返回固定分布（mastered=20, progressing=7, weak=3）
- SubscribeMasteryUpdate 返回固定流（每 5 秒推 1 个 MasteryUpdateEvent）
- **Kafka mock**：data-ana 就绪前不发布真实 MasteryEvent，msg 使用本地 stub 预警
### 4.2 我消费的 mock
在真实上游就绪前，data-ana 使用以下 mock：
- 业务数据：ClickHouse 内置模拟数据集（30 学生 × 5 考试 × 10 作业 × 30 天出勤），不依赖 core-edu CDC
- 知识点维度：内置固定知识点表（数学 50 个知识点），不依赖 content 事件
- AI 用量：AIUsageEvent 为空，仪表盘 AI 用量区块显示"暂无数据"
- CDC 通道：core-edu 就绪前 Debezium 不启动，使用 ClickHouse 批量导入模拟数据

95
docs/architecture/issues/contracts/iam_contract.md Normal file
View File

@@ -0,0 +1,95 @@
# iam 对接契约
> 负责人：ai06
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| ---------- | ----------------------- | ------------------------------ | ---------------------------- | ----- |
| IamService | Register | RegisterRequest | AuthResponse | 50052 |
| IamService | Login | LoginRequest | AuthResponse | 50052 |
| IamService | RefreshToken | RefreshTokenRequest | TokenPair | 50052 |
| IamService | Logout | LogoutRequest | LogoutResponse | 50052 |
| IamService | GetUserInfo | GetUserInfoRequest | UserInfo | 50052 |
| IamService | BatchGetUsers | BatchGetUsersRequest | BatchGetUsersResponse | 50052 |
| IamService | GetEffectivePermissions | GetEffectivePermissionsRequest | EffectivePermissionsResponse | 50052 |
| IamService | GetEffectiveAccess | GetEffectiveAccessRequest | EffectiveAccessResponse | 50052 |
| IamService | GetEffectiveDataScope | GetEffectiveDataScopeRequest | DataScopeResponse | 50052 |
| IamService | GetViewports | GetViewportsRequest | ViewportsResponse | 50052 |
| IamService | GetPublicKey | GetPublicKeyRequest | PublicKeyResponse | 50052 |
| IamService | GetChildrenByParent | GetChildrenByParentRequest | ChildrenResponse | 50052 |
### 1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC。
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
| --------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------- |
| edu.iam.user.events | UserEvent（action: created/updated/deleted/role_changed） | core-edu / msg / push-gateway / teacher-bff / student-bff |
| edu.iam.role.events | RoleEvent（action: created/updated） | core-edu / teacher-bff |
| edu.iam.audit.created | AuditEvent（action: create/update/delete/login/logout/permission_change） | admin-portal |
### 1.5 错误码前缀
`IAM_`（如 IAM_UNAUTHORIZED、IAM_USER_NOT_FOUND、IAM_PERMISSION_DENIED）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无。iam 是身份根服务，不依赖其他业务服务。
### 2.2 Kafka 事件订阅（异步）
无。
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
无上游依赖。
### 3.2 我的就绪标志（供下游消费）
- [ ] iam gRPC 50052 启用（HealthService.Check 返回 SERVING）
- [ ] IamService.Register/Login/RefreshToken/Logout 可调用（返回 AuthResponse/TokenPair）
- [ ] IamService.GetPublicKey 可用（返回 RS256 PEM 公钥，供 api-gateway 验签）
- [ ] IamService.GetChildrenByParent 可用（供 parent-bff 查孩子列表）
- [ ] edu.iam.user.events / edu.iam.role.events / edu.iam.audit.created topic 可发布
- [ ] JWT RS256 签发链路打通（access_token + refresh_token）
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 iam 真实服务就绪前，为下游（api-gateway / 各 BFF）提供以下 mock：
- **gRPC mock**：使用 grpc-mock 拦截 50052 端口，Register/Login 返回固定 AuthResponse（user.id="mock-user-001", tokens.access_token="mock-access-token"）
- **GetPublicKey mock**：返回固定 RS256 公钥 PEM（与 mock 私钥配对），供 api-gateway 验签 mock JWT
- **GetChildrenByParent mock**：返回固定 ChildInfo 列表（2 个孩子）
- **Kafka mock**：iam 服务就绪前不发布真实事件，下游订阅方使用本地 stub
### 4.2 我消费的 mock
不适用（无上游依赖）。

110
docs/architecture/issues/contracts/msg_contract.md Normal file
View File

@@ -0,0 +1,110 @@
# msg 对接契约
> 负责人：ai10
> 关联：[matrix.md](./matrix.md)、[msg.proto](../../../packages/shared-proto/proto/msg.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
| ----------------------------- | ---------------------- | ----------------------------- | --------------------------- | ----- |
| NotificationService | SendNotification | SendNotificationRequest | Notification | 50056 |
| NotificationService | ListNotifications | ListNotificationsRequest | ListNotificationsResponse | 50056 |
| NotificationService | MarkAsRead | MarkAsReadRequest | MarkAsReadResponse | 50056 |
| NotificationService | SearchNotifications | SearchNotificationsRequest | SearchNotificationsResponse | 50056 |
| NotificationService | RecallNotification | RecallNotificationRequest | RecallNotificationResponse | 50056 |
| NotificationPreferenceService | GetPreference | GetPreferenceRequest | NotificationPreference | 50056 |
| NotificationPreferenceService | UpdatePreference | UpdatePreferenceRequest | NotificationPreference | 50056 |
| NotificationPreferenceService | GetPreferenceByChannel | GetPreferenceByChannelRequest | ChannelPreference | 50056 |
| NotificationPreferenceService | ListPreferences | ListPreferencesRequest | ListPreferencesResponse | 50056 |
| NotificationTemplateService | CreateTemplate | CreateTemplateRequest | NotificationTemplate | 50056 |
| NotificationTemplateService | GetTemplate | GetTemplateRequest | NotificationTemplate | 50056 |
| NotificationTemplateService | ListTemplates | ListTemplatesRequest | ListTemplatesResponse | 50056 |
| NotificationTemplateService | RenderTemplate | RenderTemplateRequest | RenderedTemplate | 50056 |
### 1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC。
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
| --------------------------- | ------------------------------------------------------ | ----------------------- |
| edu.msg.notification.events | NotificationEvent（action: sent/read/recalled/failed） | push-gateway / data-ana |
### 1.5 错误码前缀
`MSG_`（如 MSG_TEMPLATE_NOT_FOUND、MSG_CHANNEL_DISABLED、MSG_RATE_LIMITED）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无主动 gRPC 调用上游。msg 通过 Kafka 事件被动接收业务事件后触发通知。
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
| --------------------------- | --------------------------------------------------------- | --------------- | ------------------------------------------------------- |
| edu.iam.user.events | UserEvent | iam (ai06) | iam 就绪前使用本地用户偏好默认值 |
| edu.exam.events | ExamEvent（action: created/updated/deleted） | core-edu (ai08) | core-edu 就绪前不订阅，使用本地 stub 事件触发 mock 通知 |
| edu.homework.events | HomeworkEvent（action: assigned/submitted/graded） | core-edu (ai08) | 同上 |
| edu.grade.events | GradeEvent（action: recorded/updated） | core-edu (ai08) | 同上 |
| edu.class.events | ClassEvent（action: transferred） | core-edu (ai08) | 同上 |
| edu.data_ana.mastery.events | MasteryEvent（action: mastery.updated/warning.triggered） | data-ana (ai11) | data-ana 就绪前不订阅，预警通知使用本地 stub |
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] iam gRPC 50052 启用（ai06）—— 用于用户通知偏好查询（可选）
- [ ] core-edu gRPC 50053 启用（ai08）—— 业务事件来源
- [ ] edu.exam.events / edu.homework.events / edu.grade.events / edu.class.events topic 有事件发布（ai08）
- [ ] data-ana gRPC 50055 启用（ai11）—— 预警事件来源
- [ ] edu.data_ana.mastery.events topic 有事件发布（ai11）
### 3.2 我的就绪标志（供下游消费）
- [ ] msg gRPC 50056 启用（HealthService.Check 返回 SERVING）
- [ ] NotificationService 5 RPC 可调用
- [ ] NotificationPreferenceService 4 RPC 可调用
- [ ] NotificationTemplateService 4 RPC 可调用（含 RenderTemplate 模板渲染）
- [ ] edu.msg.notification.events topic 可发布（供 push-gateway 推送）
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 msg 真实服务就绪前，为下游（teacher-bff / student-bff / parent-bff / push-gateway）提供以下 mock：
- **gRPC mock**：使用 grpc-mock 拦截 50056 端口
- NotificationService.ListNotifications 返回固定 10 条未读通知
- NotificationService.MarkAsRead 返回 success=true
- NotificationPreferenceService.GetPreference 返回默认偏好（in_app+email 开启，sms+push 关闭）
- NotificationTemplateService.RenderTemplate 返回固定 title+content
- **Kafka mock**：msg 就绪前不发布真实 NotificationEvent，push-gateway 使用本地 stub 推送
### 4.2 我消费的 mock
在真实上游就绪前，msg 使用以下 mock：
- 业务事件：core-edu/data-ana 就绪前，msg 内置定时器发布本地 stub 事件（ExamEvent/HomeworkEvent），触发 mock 通知流程
- 用户偏好：iam 就绪前使用默认偏好（所有用户 in_app 开启）
- 模板渲染：内置 5 个常用模板（exam.created / homework.assigned / grade.recorded / warning.triggered / system.notice）

121
docs/architecture/issues/contracts/parent-bff_contract.md Normal file
View File

@@ -0,0 +1,121 @@
# parent-bff 对接契约
> 负责人：ai05
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[core_edu.proto](../../../packages/shared-proto/proto/core_edu.proto)、[analytics.proto](../../../packages/shared-proto/proto/analytics.proto)、[msg.proto](../../../packages/shared-proto/proto/msg.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无对外 gRPC。parent-bff 是 GraphQL 聚合层。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | -------- | ----------------------------------------- | ---------------------- |
| POST | /graphql | 家长 BFF GraphQL 端点 | JWT 必需 + parent 角色 |
| GET | /graphql | GraphQL Playground（开发环境） | 开发环境公开 |
| GET | /healthz | 健康检查（liveness） | 公开 |
| GET | /readyz | 就绪检查（readiness，含下游 gRPC 连通性） | 公开 |
### 1.3 GraphQL schema（如 BFF）
GraphQL schema 文件路径：`apps/parent-bff/src/schema/*.graphql`（端口 :3010）
核心 Query / Mutation 域：
- **auth**：currentUser（聚合 iam.GetUserInfo + GetEffectivePermissions + GetViewports）
- **children**：myChildren（聚合 iam.GetChildrenByParent，核心依赖 I3 裁决）
- **childSummary**：childSummary（聚合 data-ana.AnalyticsService.GetParentDashboard）
- **childGrades**：childGrades（聚合 core-edu.GradeService.ListGradesByStudent）
- **childAttendance**：childAttendance（聚合 core-edu.AttendanceService.ListAttendanceByStudent）
- **childHomework**：childHomework（聚合 core-edu.HomeworkService.ListHomeworkByClass）
- **childWeakness**：childWeakness（聚合 data-ana.AnalyticsService.GetStudentWeakness）
- **childTrend**：childTrend（聚合 data-ana.AnalyticsService.GetLearningTrend）
- **notifications**：myNotifications / markAsRead（聚合 msg.NotificationService）
### 1.4 Kafka 事件发布（如有）
无。parent-bff 不发布事件，仅做 gRPC 聚合。
### 1.5 错误码前缀
`BFF_PARENT_`（如 BFF_PARENT_UPSTREAM_UNAVAILABLE、BFF_PARENT_AGGREGATION_FAILED、BFF_PARENT_NO_CHILDREN、BFF_PARENT_FORBIDDEN）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
| 被调用方 | Service.RPC | 用途 | mock 策略 |
| --------------- | ----------------------------------------- | ------------------------ | ------------------------------------------------------ |
| iam (ai06) | IamService.GetUserInfo | 获取当前家长信息 | iam 就绪前返回固定 UserInfo（parent 角色） |
| iam (ai06) | IamService.GetEffectivePermissions | 权限校验 | iam 就绪前返回家长权限集 |
| iam (ai06) | IamService.GetViewports | 家长导航菜单 | iam 就绪前返回固定视口列表 |
| iam (ai06) | IamService.GetChildrenByParent | 查询关联孩子列表（核心） | iam 就绪前返回固定 2 个 ChildInfo（I3/ISSUE-047 裁决） |
| core-edu (ai08) | GradeService.ListGradesByStudent | 孩子成绩 | core-edu 就绪前返回固定 5 个 Grade |
| core-edu (ai08) | AttendanceService.ListAttendanceByStudent | 孩子考勤 | core-edu 就绪前返回固定 10 条 Attendance |
| core-edu (ai08) | HomeworkService.ListHomeworkByClass | 孩子作业 | core-edu 就绪前返回固定 3 个 Homework |
| data-ana (ai11) | AnalyticsService.GetParentDashboard | 家长仪表盘 | data-ana 就绪前返回固定仪表盘（child_avg_score=85.0） |
| data-ana (ai11) | AnalyticsService.GetStudentWeakness | 孩子薄弱点 | data-ana 就绪前返回固定 3 个 weak_points |
| data-ana (ai11) | AnalyticsService.GetLearningTrend | 孩子学习趋势 | data-ana 就绪前返回固定趋势数据 |
| msg (ai10) | NotificationService.ListNotifications | 家长通知 | msg 就绪前返回固定 10 条通知 |
| msg (ai10) | NotificationService.MarkAsRead | 标记已读 | msg 就绪前返回 success=true |
### 2.2 Kafka 事件订阅（异步）
无。parent-bff 不订阅 Kafka 事件，仅做同步 gRPC 聚合。
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] iam gRPC 50052 启用（ai06）—— **核心依赖 GetChildrenByParent（I3/ISSUE-047 裁决）**
- [ ] core-edu gRPC 50053 启用（ai08）
- [ ] data-ana gRPC 50055 启用（ai11）
- [ ] msg gRPC 50056 启用（ai10）
### 3.2 我的就绪标志（供下游消费）
- [ ] parent-bff GraphQL :3010 启用（/healthz 返回 200）
- [ ] /readyz 返回 200（含 4 个下游 gRPC 连通性检查）
- [ ] GraphQL schema 可内省（POST /graphql 返回 schema）
- [ ] 核心 Query 可执行：currentUser / myChildren / childSummary / childGrades
- [ ] 核心 Mutation 可执行：markAsRead
- [ ] 数据范围校验生效（家长只能查自己孩子的数据，基于 iam.GetChildrenByParent 返回的 user_id 校验）
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 parent-bff 真实就绪前，为下游（parent-portal）提供以下 mock：
- **GraphQL mock**：使用 Apollo Server mockProviders 或 MSW 拦截 POST /graphql
- currentUser 返回固定家长（id="parent-001", name="王家长", roles=["parent"]）
- myChildren 返回固定 2 个孩子（id="student-001" 李同学 + id="student-002" 李妹妹）
- childSummary 返回固定仪表盘（child_avg_score=85.0, child_class_rank=5）
- childGrades 返回固定 5 个成绩
- childAttendance 返回固定 10 条考勤
- myNotifications 返回固定 10 条通知
### 4.2 我消费的 mock
在真实上游就绪前，parent-bff 使用以下 mock（详见 §2.1 mock 策略列）：
- **iam mock**：固定 UserInfo + 家长权限 + 固定视口 + 固定 2 个 ChildInfo（家长-学生关联核心数据）
- **core-edu mock**：固定孩子成绩/考勤/作业
- **data-ana mock**：固定家长仪表盘/孩子薄弱点/趋势
- **msg mock**：固定通知列表 + MarkAsRead success
> 关键：iam.GetChildrenByParent 的 mock 必须返回与 core-edu mock 数据一致的 student_id，否则数据范围校验会失败。parent-bff 启动时校验 myChildren 返回的 user_id 与下游查询的 student_id 一致性。

124
docs/architecture/issues/contracts/parent-portal_contract.md Normal file
View File

@@ -0,0 +1,124 @@
# parent-portal 对接契约
> 负责人：ai15
> 关联：[matrix.md](./matrix.md)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无。parent-portal 是前端微前端 Remote。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | --------------------- | ------------ | ------------------------------------- |
| GET | / | 家长门户首页 | JWT 必需（前端路由守卫） |
| GET | /children | 我的孩子列表 | JWT 必需 |
| GET | /child/:id/summary | 孩子概况 | JWT 必需 + 数据范围校验（仅自己孩子） |
| GET | /child/:id/grades | 孩子成绩 | JWT 必需 + 数据范围校验 |
| GET | /child/:id/attendance | 孩子考勤 | JWT 必需 + 数据范围校验 |
| GET | /child/:id/homework | 孩子作业 | JWT 必需 + 数据范围校验 |
| GET | /child/:id/weakness | 孩子薄弱点 | JWT 必需 + 数据范围校验 |
| GET | /notifications | 通知中心 | JWT 必需 |
### 1.3 GraphQL schema（如 BFF）
不适用。parent-portal 消费 parent-bff GraphQL，自身不提供 schema。
### 1.4 Kafka 事件发布（如有）
无。
### 1.5 错误码前缀
无（前端不定义错误码前缀，透传 BFF 错误码）。
### 1.6 微前端架构（补充）
| 角色 | 说明 |
| ---------------------- | ------------------------------------------------ |
| MF Remote | 家长门户是微前端远程模块 |
| 暴露的 remote 模块 | ParentApp（家长端完整应用）、shared 家长端组件 |
| module federation 配置 | `apps/parent-portal/module-federation.config.ts` |
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无。前端不直接调 gRPC。
### 2.2 Kafka 事件订阅（异步）
无。前端不直接订阅 Kafka。
### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
| ------------------- | ------------------------ | -------------------------------------------- | ---------------------------------------------------------------- |
| api-gateway (ai01) | POST /api/parent/graphql | 家长 GraphQL 查询（经网关代理到 parent-bff） | api-gateway/parent-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 |
| api-gateway (ai01) | POST /api/auth/login | 家长登录 | api-gateway 就绪前使用 MSW 返回固定 JWT |
| push-gateway (ai02) | GET /ws | WebSocket 实时通知 | push-gateway 就绪前使用 mock-socket 模拟 WS 推送 |
### 2.4 GraphQL 查询域（经 api-gateway 代理到 parent-bff）
| Query/Mutation | 用途 | mock 策略 |
| ---------------------------- | -------------------- | ----------------------------- |
| currentUser | 当前家长信息 | MSW 返回固定家长 |
| myChildren | 我的孩子列表（核心） | MSW 返回固定 2 个孩子 |
| childSummary | 孩子概况 | MSW 返回固定仪表盘 |
| childGrades | 孩子成绩 | MSW 返回固定 5 个成绩 |
| childAttendance | 孩子考勤 | MSW 返回固定 10 条考勤 |
| childHomework | 孩子作业 | MSW 返回固定 3 个作业 |
| childWeakness | 孩子薄弱点 | MSW 返回固定 3 个 weak_points |
| childTrend | 孩子学习趋势 | MSW 返回固定趋势数据 |
| myNotifications / markAsRead | 通知中心 | MSW 返回固定通知 |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] api-gateway HTTP :8080 启用（ai01）—— 前端请求入口
- [ ] parent-bff GraphQL :3010 启用（ai05）—— 数据来源
- [ ] push-gateway WebSocket :8081/ws 启用（ai02）—— 实时通知
### 3.2 我的就绪标志（供下游消费）
- [ ] parent-portal dev server :4002 启用
- [ ] MF Remote 可被 AppShell 加载（暴露 ParentApp 模块）
- [ ] 独立壳渲染（首页 + 导航 + 路由守卫）
- [ ] 登录流程可用（POST /api/auth/login 获取 JWT 存入 cookie）
- [ ] GraphQL 查询可执行（currentUser / myChildren / childSummary 返回数据）
- [ ] 数据范围校验生效（前端路由守卫校验 child:id 是否在 myChildren 返回列表中）
- [ ] WebSocket 通知可接收
---
## §4 Mock 策略
### 4.1 我提供的 mock
parent-portal 是前端，无下游消费方。但对开发体验提供：
- **Storybook**：各组件独立 story
- **MSW handlers**：`apps/parent-portal/src/mocks/handlers.ts`，拦截所有 GraphQL/HTTP 请求
### 4.2 我消费的 mock
在真实上游就绪前，parent-portal 使用以下 mock：
- **HTTP/GraphQL mock**：使用 MSW 拦截所有请求
- POST /api/auth/login → 返回固定 JWT + UserInfo（parent 角色）
- POST /api/parent/graphql → 根据 operationName 返回对应 mock 响应（与 parent-bff mock 数据一致）
- myChildren mock 必须返回固定 2 个孩子（id="student-001" + "student-002"），与其他 child* 查询的 student_id 一致
- 所有 mock 响应定义在 `apps/parent-portal/src/mocks/fixtures/*.json`
- **WebSocket mock**：使用 mock-socket 库
- 连接后每 30 秒推送 1 条 mock 通知
- **JWT mock**：使用固定 mock JWT，存入 httpOnly cookie
- **环境切换**：通过 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制，上游就绪后设为 `disabled`

101
docs/architecture/issues/contracts/push-gateway_contract.md Normal file
View File

@@ -0,0 +1,101 @@
# push-gateway 对接契约
> 负责人：ai02
> 关联：[matrix.md](./matrix.md)、[msg.proto](../../../packages/shared-proto/proto/msg.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无对外 gRPC。push-gateway 是 WebSocket/SSE 推送入口。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | ------------------- | -------------------------------------- | -------------------------------- |
| GET | /ws | WebSocket 升级端点（实时推送通知） | JWT 必需（query param 传 token） |
| GET | /sse | SSE 推送端点（备选实时通道） | JWT 必需 |
| POST | /internal/broadcast | 内部广播接口（msg 服务触发） | 内网 mTLS |
| POST | /internal/send | 内部单推接口（msg 服务触发） | 内网 mTLS |
| GET | /healthz | 健康检查（liveness） | 公开 |
| GET | /readyz | 就绪检查（readiness，含 Kafka 连通性） | 公开 |
| GET | /metrics | Prometheus 指标端点 | 公开（内网） |
### 1.3 GraphQL schema（如 BFF）
不适用。
### 1.4 Kafka 事件发布（如有）
无。push-gateway 不发布事件，仅消费事件触发推送。
### 1.5 错误码前缀
`PUSH_`（如 PUSH_CONNECTION_FAILED、PUSH_CHANNEL_CLOSED、PUSH_AUTH_INVALID）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无主动 gRPC 调用上游。
### 2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
| --------------------------- | --------------------------------- | ---------- | --------------------------------------------------------------------------- |
| edu.msg.notification.events | NotificationEvent（action: sent） | msg (ai10) | msg 就绪前不订阅，使用本地定时器每 30 秒推送 1 条 mock 通知到所有连接客户端 |
### 2.3 HTTP 调用（如有）
无。
### 2.4 内部接口（msg 调用 push-gateway）
| 被调用方 | Method.Path | 用途 | 说明 |
| ------------ | ------------------------ | ------------------ | ---------------------------------------- |
| push-gateway | POST /internal/broadcast | msg 服务批量推送 | msg 收到业务事件后渲染模板，调此接口广播 |
| push-gateway | POST /internal/send | msg 服务单用户推送 | msg 渲染后定向推送给目标用户 |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] msg gRPC 50056 启用（ai10）—— 通知事件来源
- [ ] edu.msg.notification.events topic 有事件发布（ai10）
- [ ] iam gRPC 50052 启用（ai06）—— WebSocket 连接时 JWT 验签（可选，push-gateway 可独立验签）
### 3.2 我的就绪标志（供下游消费）
- [ ] push-gateway HTTP :8081 启用（/healthz 返回 200）
- [ ] /readyz 返回 200（含 Kafka 连通性检查通过）
- [ ] WebSocket /ws 端点可升级连接（JWT 鉴权后建立长连接）
- [ ] SSE /sse 端点可建立 EventStream
- [ ] /internal/broadcast + /internal/send 接收 msg 推送并下发到在线客户端
- [ ] Kafka consumer edu.msg.notification.events 订阅成功
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 push-gateway 真实就绪前，为下游（各前端 portal）提供以下 mock：
- **WebSocket mock**：前端开发期使用 mock-socket 库模拟 WS 连接
- 连接成功后每 30 秒推送 1 条 mock 通知（type="system", title="测试通知"）
- **SSE mock**：前端使用 EventSource polyfill，本地定时推送 mock 事件
- **HTTP mock**：/internal/* 接口返回 200 success
### 4.2 我消费的 mock
在真实上游就绪前，push-gateway 使用以下 mock：
- **NotificationEvent mock**：msg 就绪前，push-gateway 内置定时器每 30 秒生成 1 条 mock NotificationEvent（action=sent），推送到所有在线客户端
- **JWT 验签**：iam 就绪前使用本地固定 mock RS256 公钥验签 WebSocket 连接的 token
- **Kafka 订阅**：msg 就绪前不启动 Kafka consumer，使用本地定时器替代

130
docs/architecture/issues/contracts/student-bff_contract.md Normal file
View File

@@ -0,0 +1,130 @@
# student-bff 对接契约
> 负责人：ai04
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[core_edu.proto](../../../packages/shared-proto/proto/core_edu.proto)、[content.proto](../../../packages/shared-proto/proto/content.proto)、[analytics.proto](../../../packages/shared-proto/proto/analytics.proto)、[msg.proto](../../../packages/shared-proto/proto/msg.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无对外 gRPC。student-bff 是 GraphQL 聚合层。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | -------- | ----------------------------------------- | ----------------------- |
| POST | /graphql | 学生 BFF GraphQL 端点 | JWT 必需 + student 角色 |
| GET | /graphql | GraphQL Playground（开发环境） | 开发环境公开 |
| GET | /healthz | 健康检查（liveness） | 公开 |
| GET | /readyz | 就绪检查（readiness，含下游 gRPC 连通性） | 公开 |
### 1.3 GraphQL schema（如 BFF）
GraphQL schema 文件路径：`apps/student-bff/src/schema/*.graphql`（端口 :3009）
核心 Query / Mutation 域：
- **auth**：currentUser（聚合 iam.GetUserInfo + GetEffectivePermissions + GetViewports）
- **myClasses**：我的班级（聚合 core-edu.ClassService.GetClass + ListStudentsByClass）
- **myExams**：我的考试列表（聚合 core-edu.ExamService.ListExamsByClass）
- **myHomework**：我的作业（聚合 core-edu.HomeworkService.ListHomeworkByClass + SubmitHomework）
- **myGrades**：我的成绩（聚合 core-edu.GradeService.ListGradesByStudent）
- **myAttendance**：我的考勤（聚合 core-edu.AttendanceService.ListAttendanceByStudent）
- **content**：textbooks / chapters / learningPath（聚合 content.KnowledgeGraphService.GetLearningPath）
- **dashboard**：studentDashboard（聚合 data-ana.AnalyticsService.GetStudentDashboard）
- **weakness**：myWeakness（聚合 data-ana.AnalyticsService.GetStudentWeakness）
- **trend**：myTrend（聚合 data-ana.AnalyticsService.GetLearningTrend）
- **notifications**：myNotifications / markAsRead（聚合 msg.NotificationService）
### 1.4 Kafka 事件发布（如有）
无。student-bff 不发布事件，仅做 gRPC 聚合。
### 1.5 错误码前缀
`BFF_STUDENT_`（如 BFF_STUDENT_UPSTREAM_UNAVAILABLE、BFF_STUDENT_AGGREGATION_FAILED、BFF_STUDENT_FORBIDDEN）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
| 被调用方 | Service.RPC | 用途 | mock 策略 |
| --------------- | ----------------------------------------- | ---------------- | ------------------------------------------- |
| iam (ai06) | IamService.GetUserInfo | 获取当前学生信息 | iam 就绪前返回固定 UserInfo（student 角色） |
| iam (ai06) | IamService.GetEffectivePermissions | 权限校验 | iam 就绪前返回学生权限集 |
| iam (ai06) | IamService.GetViewports | 学生导航菜单 | iam 就绪前返回固定视口列表 |
| core-edu (ai08) | ClassService.GetClass | 我的班级详情 | core-edu 就绪前返回固定 ClassInfo |
| core-edu (ai08) | ClassService.ListStudentsByClass | 班级同学名单 | core-edu 就绪前返回固定 30 个 StudentInfo |
| core-edu (ai08) | ExamService.ListExamsByClass | 我的考试 | core-edu 就绪前返回固定 2 个 Exam |
| core-edu (ai08) | HomeworkService.ListHomeworkByClass | 我的作业 | core-edu 就绪前返回固定 3 个 Homework |
| core-edu (ai08) | HomeworkService.SubmitHomework | 提交作业 | core-edu 就绪前返回 success=true |
| core-edu (ai08) | GradeService.ListGradesByStudent | 我的成绩 | core-edu 就绪前返回固定 5 个 Grade |
| core-edu (ai08) | AttendanceService.ListAttendanceByStudent | 我的考勤 | core-edu 就绪前返回固定 10 条 Attendance |
| content (ai09) | TextbookService.ListTextbooks | 教材列表 | content 就绪前返回固定 5 个教材 |
| content (ai09) | ChapterService.ListChapters | 章节列表 | content 就绪前返回固定章节树 |
| content (ai09) | KnowledgeGraphService.GetLearningPath | 学习路径 | content 就绪前返回固定 8 个知识点推荐顺序 |
| data-ana (ai11) | AnalyticsService.GetStudentDashboard | 学生仪表盘 | data-ana 就绪前返回固定仪表盘 |
| data-ana (ai11) | AnalyticsService.GetStudentWeakness | 我的薄弱点 | data-ana 就绪前返回固定 3 个 weak_points |
| data-ana (ai11) | AnalyticsService.GetLearningTrend | 学习趋势 | data-ana 就绪前返回固定趋势数据 |
| msg (ai10) | NotificationService.ListNotifications | 学生通知 | msg 就绪前返回固定 10 条通知 |
| msg (ai10) | NotificationService.MarkAsRead | 标记已读 | msg 就绪前返回 success=true |
### 2.2 Kafka 事件订阅（异步）
无。student-bff 不订阅 Kafka 事件，仅做同步 gRPC 聚合。
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] iam gRPC 50052 启用（ai06）
- [ ] core-edu gRPC 50053 启用（ai08）
- [ ] content gRPC 50054 启用（ai09）
- [ ] data-ana gRPC 50055 启用（ai11）
- [ ] msg gRPC 50056 启用（ai10）
### 3.2 我的就绪标志（供下游消费）
- [ ] student-bff GraphQL :3009 启用（/healthz 返回 200）
- [ ] /readyz 返回 200（含 5 个下游 gRPC 连通性检查）
- [ ] GraphQL schema 可内省（POST /graphql 返回 schema）
- [ ] 核心 Query 可执行：currentUser / myClasses / studentDashboard / myGrades
- [ ] 核心 Mutation 可执行：submitHomework / markAsRead
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 student-bff 真实就绪前，为下游（student-portal）提供以下 mock：
- **GraphQL mock**：使用 Apollo Server mockProviders 或 MSW 拦截 POST /graphql
- currentUser 返回固定学生（id="student-001", name="李同学", roles=["student"]）
- myClasses 返回固定 1 个班级
- studentDashboard 返回固定仪表盘（avg_score=85.0, class_rank=5）
- myGrades 返回固定 5 个成绩
- myHomework 返回固定 3 个作业（1 个待提交）
- myNotifications 返回固定 10 条通知
### 4.2 我消费的 mock
在真实上游就绪前，student-bff 使用以下 mock（详见 §2.1 mock 策略列）：
- **iam mock**：固定 UserInfo + 学生权限 + 固定视口
- **core-edu mock**：固定班级/同学/考试/作业/成绩/考勤
- **content mock**：固定教材/章节/学习路径
- **data-ana mock**：固定仪表盘/薄弱点/趋势
- **msg mock**：固定通知列表 + MarkAsRead success
> 所有上游 mock 通过 gRPC client 拦截器实现，上游就绪后移除拦截器切换真实调用。

125
docs/architecture/issues/contracts/student-portal_contract.md Normal file
View File

@@ -0,0 +1,125 @@
# student-portal 对接契约
> 负责人：ai14
> 关联：[matrix.md](./matrix.md)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无。student-portal 是前端微前端 Remote。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | -------------- | ------------ | ------------------------ |
| GET | / | 学生门户首页 | JWT 必需（前端路由守卫） |
| GET | /my-classes | 我的班级 | JWT 必需 |
| GET | /my-exams | 我的考试 | JWT 必需 |
| GET | /my-homework | 我的作业 | JWT 必需 |
| GET | /my-grades | 我的成绩 | JWT 必需 |
| GET | /my-attendance | 我的考勤 | JWT 必需 |
| GET | /learning-path | 学习路径 | JWT 必需 |
| GET | /dashboard | 学生仪表盘 | JWT 必需 |
| GET | /notifications | 通知中心 | JWT 必需 |
### 1.3 GraphQL schema（如 BFF）
不适用。student-portal 消费 student-bff GraphQL，自身不提供 schema。
### 1.4 Kafka 事件发布（如有）
无。
### 1.5 错误码前缀
无（前端不定义错误码前缀，透传 BFF 错误码）。
### 1.6 微前端架构（补充）
| 角色 | 说明 |
| ---------------------- | ----------------------------------------------------------------- |
| MF Remote | 学生门户是微前端远程模块，由 teacher-portal AppShell 或独立壳加载 |
| 暴露的 remote 模块 | StudentApp（学生端完整应用）、shared 学生端组件 |
| module federation 配置 | `apps/student-portal/module-federation.config.ts` |
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无。前端不直接调 gRPC。
### 2.2 Kafka 事件订阅（异步）
无。前端不直接订阅 Kafka。
### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
| ------------------- | ------------------------- | --------------------------------------------- | ----------------------------------------------------------------- |
| api-gateway (ai01) | POST /api/student/graphql | 学生 GraphQL 查询（经网关代理到 student-bff） | api-gateway/student-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 |
| api-gateway (ai01) | POST /api/auth/login | 学生登录 | api-gateway 就绪前使用 MSW 返回固定 JWT |
| push-gateway (ai02) | GET /ws | WebSocket 实时通知 | push-gateway 就绪前使用 mock-socket 模拟 WS 推送 |
### 2.4 GraphQL 查询域（经 api-gateway 代理到 student-bff）
| Query/Mutation | 用途 | mock 策略 |
| ----------------------------------- | --------------- | -------------------------------------------------- |
| currentUser | 当前学生信息 | MSW 返回固定学生 |
| myClasses | 我的班级 | MSW 返回固定 1 个班级 |
| myExams | 我的考试 | MSW 返回固定 2 个考试 |
| myHomework / submitHomework | 我的作业 + 提交 | MSW 返回固定作业 + submitHomework success |
| myGrades | 我的成绩 | MSW 返回固定 5 个成绩 |
| myAttendance | 我的考勤 | MSW 返回固定 10 条考勤 |
| textbooks / chapters / learningPath | 学习内容 | MSW 返回固定内容 + 学习路径 |
| studentDashboard | 学生仪表盘 | MSW 返回固定仪表盘（avg_score=85.0, class_rank=5） |
| myWeakness | 我的薄弱点 | MSW 返回固定 3 个 weak_points |
| myTrend | 学习趋势 | MSW 返回固定趋势数据 |
| myNotifications / markAsRead | 通知中心 | MSW 返回固定通知 |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] api-gateway HTTP :8080 启用（ai01）—— 前端请求入口
- [ ] student-bff GraphQL :3009 启用（ai04）—— 数据来源
- [ ] push-gateway WebSocket :8081/ws 启用（ai02）—— 实时通知
### 3.2 我的就绪标志（供下游消费）
- [ ] student-portal dev server :4001 启用
- [ ] MF Remote 可被 AppShell 加载（暴露 StudentApp 模块）
- [ ] 独立壳渲染（首页 + 导航 + 路由守卫）
- [ ] 登录流程可用（POST /api/auth/login 获取 JWT 存入 cookie）
- [ ] GraphQL 查询可执行（currentUser / myClasses / studentDashboard 返回数据）
- [ ] WebSocket 通知可接收
---
## §4 Mock 策略
### 4.1 我提供的 mock
student-portal 是前端，无下游消费方。但对开发体验提供：
- **Storybook**：各组件独立 story
- **MSW handlers**：`apps/student-portal/src/mocks/handlers.ts`，拦截所有 GraphQL/HTTP 请求
### 4.2 我消费的 mock
在真实上游就绪前，student-portal 使用以下 mock：
- **HTTP/GraphQL mock**：使用 MSW 拦截所有请求
- POST /api/auth/login → 返回固定 JWT + UserInfo（student 角色）
- POST /api/student/graphql → 根据 operationName 返回对应 mock 响应（与 student-bff mock 数据一致）
- 所有 mock 响应定义在 `apps/student-portal/src/mocks/fixtures/*.json`
- **WebSocket mock**：使用 mock-socket 库
- 连接后每 30 秒推送 1 条 mock 通知
- **JWT mock**：使用固定 mock JWT，存入 httpOnly cookie
- **环境切换**：通过 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制，上游就绪后设为 `disabled`

136
docs/architecture/issues/contracts/teacher-bff_contract.md Normal file
View File

@@ -0,0 +1,136 @@
# teacher-bff 对接契约
> 负责人：ai03
> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[core_edu.proto](../../../packages/shared-proto/proto/core_edu.proto)、[content.proto](../../../packages/shared-proto/proto/content.proto)、[analytics.proto](../../../packages/shared-proto/proto/analytics.proto)、[msg.proto](../../../packages/shared-proto/proto/msg.proto)、[ai.proto](../../../packages/shared-proto/proto/ai.proto)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无对外 gRPC。teacher-bff 是 GraphQL 聚合层。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | -------- | ----------------------------------------- | ----------------------- |
| POST | /graphql | 教师 BFF GraphQL 端点 | JWT 必需 + teacher 角色 |
| GET | /graphql | GraphQL Playground（开发环境） | 开发环境公开 |
| GET | /healthz | 健康检查（liveness） | 公开 |
| GET | /readyz | 就绪检查（readiness，含下游 gRPC 连通性） | 公开 |
### 1.3 GraphQL schema（如 BFF）
GraphQL schema 文件路径：`apps/teacher-bff/src/schema/*.graphql`（端口 :3003）
核心 Query / Mutation 域：
- **auth**：currentUser（聚合 iam.GetUserInfo + GetEffectivePermissions + GetViewports）
- **classes**：myClasses（聚合 core-edu.ClassService.GetClassesByTeacher）
- **students**：classStudents（聚合 core-edu.ClassService.ListStudentsByClass + iam.BatchGetUsers 补用户名）
- **exams**：classExams / createExam / updateExam（聚合 core-edu.ExamService）
- **homework**：classHomework / assignHomework（聚合 core-edu.HomeworkService）
- **grades**：studentGrades / recordGrade（聚合 core-edu.GradeService）
- **attendance**：classAttendance / recordAttendance（聚合 core-edu.AttendanceService）
- **content**：textbooks / chapters / knowledgePoints / questions（聚合 content 4 个 Service）
- **dashboard**：teacherDashboard（聚合 data-ana.AnalyticsService.GetTeacherDashboard）
- **notifications**：myNotifications / markAsRead（聚合 msg.NotificationService）
- **ai**：aiChat / generateQuestion / generateLessonPlan（聚合 ai.AiService）
### 1.4 Kafka 事件发布（如有）
无。teacher-bff 不发布事件，仅做 gRPC 聚合。
### 1.5 错误码前缀
`BFF_TEACHER_`（如 BFF_TEACHER_UPSTREAM_UNAVAILABLE、BFF_TEACHER_AGGREGATION_FAILED、BFF_TEACHER_FORBIDDEN）
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
| 被调用方 | Service.RPC | 用途 | mock 策略 |
| --------------- | ------------------------------------- | ---------------- | ----------------------------------------------- |
| iam (ai06) | IamService.GetUserInfo | 获取当前教师信息 | iam 就绪前返回固定 UserInfo（teacher 角色） |
| iam (ai06) | IamService.BatchGetUsers | 批量补全学生姓名 | iam 就绪前返回固定用户名（"学生001"~"学生030"） |
| iam (ai06) | IamService.GetEffectivePermissions | 权限校验 | iam 就绪前返回全权限（放行） |
| iam (ai06) | IamService.GetViewports | 教师导航菜单 | iam 就绪前返回固定视口列表 |
| core-edu (ai08) | ClassService.GetClassesByTeacher | 教师班级列表 | core-edu 就绪前返回固定 3 个 ClassInfo |
| core-edu (ai08) | ClassService.ListStudentsByClass | 班级学生名单 | core-edu 就绪前返回固定 30 个 StudentInfo |
| core-edu (ai08) | ExamService.* | 考试管理 | core-edu 就绪前返回固定考试数据 |
| core-edu (ai08) | HomeworkService.* | 作业管理 | core-edu 就绪前返回固定作业数据 |
| core-edu (ai08) | GradeService.* | 成绩管理 | core-edu 就绪前返回固定成绩数据 |
| core-edu (ai08) | AttendanceService.* | 考勤管理 | core-edu 就绪前返回固定考勤数据 |
| content (ai09) | TextbookService.ListTextbooks | 教材列表 | content 就绪前返回固定 5 个教材 |
| content (ai09) | ChapterService.ListChapters | 章节列表 | content 就绪前返回固定章节树 |
| content (ai09) | KnowledgeGraphService.* | 知识图谱 | content 就绪前返回固定知识点 |
| content (ai09) | QuestionService.SearchQuestions | 题库检索 | content 就绪前返回固定 20 题 |
| data-ana (ai11) | AnalyticsService.GetTeacherDashboard | 教师仪表盘 | data-ana 就绪前返回固定仪表盘数据 |
| data-ana (ai11) | AnalyticsService.GetClassPerformance | 班级成绩分析 | data-ana 就绪前返回固定分析数据 |
| data-ana (ai11) | AnalyticsService.GetWarningList | 预警列表 | data-ana 就绪前返回固定 5 条预警 |
| msg (ai10) | NotificationService.ListNotifications | 教师通知列表 | msg 就绪前返回固定 10 条通知 |
| msg (ai10) | NotificationService.MarkAsRead | 标记已读 | msg 就绪前返回 success=true |
| ai (ai12) | AiService.Chat | AI 对话 | ai 就绪前返回固定回复 |
| ai (ai12) | AiService.GenerateQuestion | AI 出题 | ai 就绪前返回固定题目 |
| ai (ai12) | AiService.GenerateLessonPlan | AI 备课 | ai 就绪前返回固定教案 |
### 2.2 Kafka 事件订阅（异步）
无。teacher-bff 不订阅 Kafka 事件，仅做同步 gRPC 聚合。
### 2.3 HTTP 调用（如有）
无。
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] iam gRPC 50052 启用（ai06）
- [ ] core-edu gRPC 50053 启用（ai08）
- [ ] content gRPC 50054 启用（ai09）
- [ ] data-ana gRPC 50055 启用（ai11）
- [ ] msg gRPC 50056 启用（ai10）
- [ ] ai gRPC 50057 启用（ai12）
### 3.2 我的就绪标志（供下游消费）
- [ ] teacher-bff GraphQL :3003 启用（/healthz 返回 200）
- [ ] /readyz 返回 200（含 6 个下游 gRPC 连通性检查）
- [ ] GraphQL schema 可内省（POST /graphql 返回 schema）
- [ ] 核心 Query 可执行：currentUser / myClasses / teacherDashboard
- [ ] 核心 Mutation 可执行：createExam / assignHomework / recordGrade
- [ ] admin namespace 可用（供 admin-portal 消费）
---
## §4 Mock 策略
### 4.1 我提供的 mock
在 teacher-bff 真实就绪前，为下游（teacher-portal / admin-portal）提供以下 mock：
- **GraphQL mock**：使用 Apollo Server mockProviders 或 MSW 拦截 POST /graphql
- currentUser 返回固定教师（id="teacher-001", name="张老师", roles=["teacher"]）
- myClasses 返回固定 3 个班级
- teacherDashboard 返回固定仪表盘数据
- myNotifications 返回固定 10 条通知
- **admin namespace mock**：admin-portal 查询返回固定管理员视角数据（全校统计）
### 4.2 我消费的 mock
在真实上游就绪前，teacher-bff 使用以下 mock（详见 §2.1 mock 策略列）：
- **iam mock**：固定 UserInfo + 全权限 + 固定视口
- **core-edu mock**：固定班级/学生/考试/作业/成绩/考勤数据
- **content mock**：固定教材/章节/知识点/题目
- **data-ana mock**：固定仪表盘/分析/预警
- **msg mock**：固定通知列表 + MarkAsRead success
- **ai mock**：固定 AI 回复/题目/教案
> 所有上游 mock 通过 gRPC client 拦截器实现，上游就绪后移除拦截器切换真实调用。

126
docs/architecture/issues/contracts/teacher-portal_contract.md Normal file
View File

@@ -0,0 +1,126 @@
# teacher-portal 对接契约
> 负责人：ai13
> 关联：[matrix.md](./matrix.md)
---
## §1 我提供什么（对外接口）
### 1.1 gRPC 接口（如有）
无。teacher-portal 是前端微前端 Shell。
### 1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
| ------ | -------------- | ----------------------------- | ------------------------ |
| GET | / | 教师门户首页（MF Shell 容器） | JWT 必需（前端路由守卫） |
| GET | /classes/* | 班级管理子应用 | JWT 必需 |
| GET | /exams/* | 考试管理子应用 | JWT 必需 |
| GET | /homework/* | 作业管理子应用 | JWT 必需 |
| GET | /grades/* | 成绩管理子应用 | JWT 必需 |
| GET | /attendance/* | 考勤管理子应用 | JWT 必需 |
| GET | /content/* | 内容管理子应用 | JWT 必需 |
| GET | /dashboard | 教师仪表盘 | JWT 必需 |
| GET | /ai/* | AI 助手子应用 | JWT 必需 |
| GET | /notifications | 通知中心 | JWT 必需 |
### 1.3 GraphQL schema（如 BFF）
不适用。teacher-portal 消费 teacher-bff GraphQL，自身不提供 schema。
### 1.4 Kafka 事件发布（如有）
无。
### 1.5 错误码前缀
无（前端不定义错误码前缀，透传 BFF 错误码）。
### 1.6 微前端架构（补充）
| 角色 | 说明 |
| ---------------------- | --------------------------------------------------- |
| MF Shell（AppShell） | 教师门户是微前端宿主，加载其他子应用 |
| 暴露的 remote 模块 | AppShell（导航/布局/路由守卫）、shared 设计系统组件 |
| module federation 配置 | `apps/teacher-portal/module-federation.config.ts` |
---
## §2 我消费什么（依赖上游）
### 2.1 gRPC 调用（同步）
无。前端不直接调 gRPC。
### 2.2 Kafka 事件订阅（异步）
无。前端不直接订阅 Kafka。
### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
| ------------------- | ------------------------- | --------------------------------------------- | ----------------------------------------------------------------- |
| api-gateway (ai01) | POST /api/teacher/graphql | 教师 GraphQL 查询（经网关代理到 teacher-bff） | api-gateway/teacher-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 |
| api-gateway (ai01) | POST /api/auth/login | 教师登录 | api-gateway 就绪前使用 MSW 返回固定 JWT |
| push-gateway (ai02) | GET /ws | WebSocket 实时通知 | push-gateway 就绪前使用 mock-socket 模拟 WS 推送 |
### 2.4 GraphQL 查询域（经 api-gateway 代理到 teacher-bff）
| Query/Mutation | 用途 | mock 策略 |
| -------------------------------------------------- | ------------ | ---------------------- |
| currentUser | 当前教师信息 | MSW 返回固定教师 |
| myClasses | 我的班级 | MSW 返回固定 3 个班级 |
| classStudents | 班级学生名单 | MSW 返回固定 30 个学生 |
| classExams / createExam | 考试管理 | MSW 返回固定考试数据 |
| classHomework / assignHomework | 作业管理 | MSW 返回固定作业数据 |
| studentGrades / recordGrade | 成绩管理 | MSW 返回固定成绩数据 |
| classAttendance / recordAttendance | 考勤管理 | MSW 返回固定考勤数据 |
| textbooks / chapters / knowledgePoints / questions | 内容管理 | MSW 返回固定内容数据 |
| teacherDashboard | 教师仪表盘 | MSW 返回固定仪表盘 |
| myNotifications / markAsRead | 通知中心 | MSW 返回固定通知 |
| aiChat / generateQuestion / generateLessonPlan | AI 助手 | MSW 返回固定 AI 响应 |
---
## §3 就绪信号
### 3.1 我依赖的上游就绪标志
- [ ] api-gateway HTTP :8080 启用（ai01）—— 前端请求入口
- [ ] teacher-bff GraphQL :3003 启用（ai03）—— 数据来源
- [ ] push-gateway WebSocket :8081/ws 启用（ai02）—— 实时通知
### 3.2 我的就绪标志（供下游消费）
- [ ] teacher-portal dev server :4000 启用
- [ ] MF Shell 可加载（首页渲染 AppShell + 导航）
- [ ] 子应用路由可访问（/classes /exams /homework 等子页面渲染）
- [ ] 登录流程可用（POST /api/auth/login 获取 JWT 存入 cookie）
- [ ] GraphQL 查询可执行（currentUser / myClasses 返回数据）
- [ ] WebSocket 通知可接收（push-gateway 推送 → 前端通知中心更新）
---
## §4 Mock 策略
### 4.1 我提供的 mock
teacher-portal 是最前端，无下游消费方。但对开发体验提供：
- **Storybook**：各组件独立 story，供设计审查
- **MSW handlers**：`apps/teacher-portal/src/mocks/handlers.ts`，拦截所有 GraphQL/HTTP 请求返回 mock 数据
### 4.2 我消费的 mock
在真实上游就绪前，teacher-portal 使用以下 mock：
- **HTTP/GraphQL mock**：使用 MSW（Mock Service Worker）拦截所有请求
- POST /api/auth/login → 返回固定 JWT + UserInfo
- POST /api/teacher/graphql → 根据 operationName 返回对应 mock 响应（与 teacher-bff mock 数据一致）
- 所有 mock 响应定义在 `apps/teacher-portal/src/mocks/fixtures/*.json`
- **WebSocket mock**：使用 mock-socket 库
- 连接 ws://localhost:8081/ws 后每 30 秒推送 1 条 mock 通知
- **JWT mock**：使用固定 mock JWT（与 api-gateway mock 公钥配对），存入 httpOnly cookie
- **环境切换**：通过 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制是否启用 MSW，上游就绪后设为 `disabled`

292
docs/architecture/issues/coord.md Normal file
View File

@@ -0,0 +1,292 @@
# coord 仲裁结果汇总
> 维护者：coord（协调 AI）
> 维护规则：各 AI 在 `objections/[模块名]_issue.md` 提请异议 → coord 审阅 → 在本文件写入仲裁结果
> 关联文档：[president-final-rulings.md](../president-final-rulings.md)、[ai-work-orchestration.md](../ai-work-orchestration.md)、[workline.md](./workline.md)、[matrix.md](./matrix.md)
---
## 仲裁记录索引
| 编号 | 日期 | 提请方 | 主题 | 状态 | 仲裁章节 |
| ------- | ---------- | ---------------------- | --------------------------------- | --------- | -------- |
| ARB-001 | 2026-07-09 | coord（批次 1 启动前） | teacher-bff GraphQL schema 第一版 | ✅ 已裁决 | §1 |
| ARB-002 | 2026-07-09 | coord（批次 1 启动前） | MF Shell 暴露清单 | ✅ 已裁决 | §2 |
---
## §1 ARB-001：teacher-bff GraphQL schema 第一版
### 1.1 背景
批次 1（P2）启动前，需仲裁 teacher-bff GraphQL schema 第一版，作为 ai03（teacher-bff）和 ai13（teacher-portal）的共同契约。
数据源：ai03 的 [02-architecture-design.md §5](../../services/teacher-bff/docs/02-architecture-design.md#L503) 提供了目标态 schema（P4），但 P2 只需 Must Have 子集。
### 1.2 仲裁结论
**P2 第一版 schema 范围**（Must Have，对应 ai03 P2 工作量分级 Must Have 13 项）：
```graphql
# ============ P2 第一版 schema ============
# 存放位置：packages/shared-ts/contracts/graphql/teacher-bff.graphql
# 仲裁原则：仅包含 P2 可实现的 Query（iam + classes 已就绪），Mutation 延后到 P3
scalar DateTime
enum DataScope {
SELF
CLASS
GRADE
SCHOOL
DISTRICT
ALL
}
enum ExamStatus {
DRAFT
PUBLISHED
IN_PROGRESS
GRADING
SCORED
ARCHIVED
}
enum SubmissionStatus {
NOT_SUBMITTED
SUBMITTED
GRADED
}
type User {
id: ID!
email: String!
name: String!
roles: [String!]!
dataScope: DataScope!
}
type ViewportItem {
key: String!
label: String!
route: String!
icon: String
sortOrder: String!
requiredPermission: String
}
type Class {
id: ID!
name: String!
gradeId: String!
studentCount: Int!
}
type DashboardStats {
totalExams: Int!
pendingGrading: Int!
todayHomework: Int!
}
type DashboardData {
user: User!
classes: [Class!]!
viewports: [ViewportItem!]!
stats: DashboardStats!
}
# ============ Query（P2 仅读，无 Mutation） ============
type Query {
# 仪表盘聚合（并行：iam.me + iam.viewports + iam.permissions + classes.byTeacher）
dashboard: DashboardData!
# 视口配置（导航）
viewports: [ViewportItem!]!
# 当前用户信息
me: User!
# 班级列表（按教师 dataScope 过滤）
classes: [Class!]!
class(id: ID!): Class
}
# ============ P2 不包含（P3+ 扩展） ============
# - exams / homework / grades Query → P3（core-edu 就绪后）
# - classPerformance / studentWeakness / learningTrend → P4（data-ana 就绪后）
# - notifications → P5（msg 就绪后）
# - 所有 Mutation → P3+
# - Subscription → P6+ 评估
```
### 1.3 关键裁决
| 裁决点 | 结论 | 依据 |
| ---------------- | ---------------------------------------------------------- | ------------------------------------------------------------ |
| Schema 存放位置 | `packages/shared-ts/contracts/graphql/teacher-bff.graphql` | 总裁裁决 §2.17 SDL-first + 集中管理 |
| P2 Query 范围 | dashboard / viewports / me / classes / class（5 个） | 仅依赖 iam + classes（P2 就绪） |
| P2 Mutation 范围 | **无**（P2 纯读） | Mutation 依赖 core-edu（P3），P2 无下游可写 |
| DataLoader | dashboard 内 classes 列表用 DataLoader | N+1 防御（ai03 §5.1 第 4 条） |
| 复杂度限制 | depth ≤ 7，cost ≤ 1000 | ai03 §5.1 第 5 条 |
| admin 命名空间 | **P2 不包含**，P6 admin-portal 阶段新增 `admin` 命名空间 | 总裁裁决 §5.1 admin 复用 teacher-bff + admin schema 命名空间 |
| 错误响应 | ActionState 信封（success/errors/data） | coord-final-decisions F9 |
| 降级模式 | success=true + error=null + data 内 degraded 字段 | 总裁裁决 §3.4 方案 B |
### 1.4 ai03 执行项
1. 在 `packages/shared-ts/contracts/graphql/teacher-bff.graphql` 创建 P2 第一版 schema 文件
2. teacher-bff 实现 Yoga GraphQL endpoint（`POST /graphql`）
3. 实现 5 个 Query Resolver（dashboard / viewports / me / classes / class）
4. dashboard Resolver 并行调用 iam（3 RPC）+ classes（1 RPC），用 DataLoader 防御 N+1
5. 实现 ActionState 信封 + 降级模式（方案 B）
### 1.5 ai13 执行项
1. teacher-portal Shell 暴露 `GraphQLProvider`（urql client 单例）
2. 使用 `useGraphQLClient()` 从 packages/hooks 获取 client
3. P2 页面（dashboard / classes）通过 GraphQL query 拉取数据
4. **不调用 REST 端点**（除登录外，P2 起 all-in GraphQL）
---
## §2 ARB-002：MF Shell 暴露清单
### 2.1 背景
批次 1（P2）启动前，需仲裁 teacher-portal 作为 MF Shell 暴露哪些模块给 Remote（student/parent/admin），作为 ai13 的实现依据。
数据源：ai13 的 [03-long-term-architecture.md §1.4](../../apps/teacher-portal/docs/03-long-term-architecture.md) 提供了 GraphQL client 单例设计。
### 2.2 仲裁结论
**P2 第一版 MF Shell 暴露清单**：
```typescript
// teacher-portal/next.config.js — NextFederationPlugin exposes
exposes: {
// 1. AppShell（布局 + 导航 + 认证守卫）
'./AppShell': './src/components/AppShell.tsx',
// 2. GraphQLProvider（urql client 单例，总裁 §2.17 方案 A）
'./GraphQLProvider': './src/app/providers.tsx',
// 3. 共享 hooks
'./useAuth': './packages/hooks/src/use-auth.ts',
'./usePermission': './packages/hooks/src/use-permission.ts',
'./useGraphQLClient': './packages/hooks/src/use-graphql-client.ts',
// 4. 共享 UI 组件
'./ErrorBoundary': './packages/ui-components/src/error-boundary.tsx',
'./Loading': './packages/ui-components/src/loading.tsx',
'./Empty': './packages/ui-components/src/empty.tsx',
'./RequirePermission': './packages/ui-components/src/require-permission.tsx',
}
```
**MF shared（singleton）配置**：
```typescript
shared: {
react: { singleton: true, requiredVersion: '^18.3.0' },
'react-dom': { singleton: true, requiredVersion: '^18.3.0' },
urql: { singleton: true, requiredVersion: '^2.2.0' },
graphql: { singleton: true, requiredVersion: '^16.8.0' },
'@edu/ui-tokens': { singleton: true },
'@edu/ui-components': { singleton: true },
'@edu/hooks': { singleton: true },
}
```
### 2.3 关键裁决
| 裁决点 | 结论 | 依据 |
| ------------------- | ---------------------------------------------- | --------------------------- |
| Shell 身份 | teacher-portal 是 MF Shell（非 Remote） | 总裁裁决 §2.17 + ai13 §1.3 |
| P2 Remote 数量 | **0**（P2 暂无 Remote，仅配置 exposes/shared） | ai13 §1.3 绞杀者模式 step 3 |
| P3 首个 Remote | student-portal | ai13 §1.3 step 4 |
| GraphQL client 归属 | Shell 暴露 GraphQLProvider，Remote 复用 | 总裁 §2.17 方案 A |
| MF shared singleton | react / react-dom / urql / graphql / @edu/* | 避免多实例 + 缓存不一致 |
| AppShell 暴露 | 是（Remote 复用布局 + 导航 + 认证守卫） | ai13 §1.3 |
| feature flag | `NEXT_PUBLIC_MF_ENABLED=false`（P2 默认关） | ai13 §1.3 回退策略 |
| 登录页 | P2 不走 MF（Shell 独占 `/login`） | 登录是认证前提，MF 依赖认证 |
### 2.4 ai13 执行项
1. teacher-portal `next.config.js` 添加 NextFederationPlugin（exposes + shared，**无 remotes**）
2. 创建 `src/app/providers.tsx`（GraphQLProvider 包裹）
3. AppShell 改造：从 REST `/api/v1/teacher/viewports` 切换为 GraphQL query `viewports`
4. P2 页面（dashboard / classes）全部用 GraphQL
5. feature flag `NEXT_PUBLIC_MF_ENABLED=false`（P2 默认单体路由）
### 2.5 ai03 执行项（联动）
1. teacher-bff 暴露 `POST /graphql` endpoint
2. 提供GraphQL playground（仅开发环境）
---
## §3 仲裁流程说明
### 3.1 提请异议
各 AI 在自己模块的 `objections/[模块名]_issue.md` 中追加异议条目，格式：
```markdown
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
```
### 3.2 coord 仲裁
coord 审阅各 `objections/[模块名]_issue.md` 后，在本文件（coord.md）追加仲裁章节：
```markdown
## §N ARB-XXX：[主题]
### N.1 背景
### N.2 仲裁结论
### N.3 关键裁决（表格）
### N.4 相关 AI 执行项
```
### 3.3 状态同步
- 仲裁完成后，coord 在对应 `objections/[模块名]_issue.md` 中更新状态为"已裁决（见 coord.md §N）"
- coord 在 [workline.md](./workline.md) §8 就绪信号跟踪表中更新进度
### 3.4 目录结构
```
issues/
├── coord.md # 本文件（仲裁汇总）
├── workline.md # 总工作安排
├── matrix.md # 上下游对接总矩阵
├── objections/ # 各模块问题/异议
│ ├── [模块名]_issue.md
│ └── cross_issue.md # 跨模块问题
├── worklines/ # 各模块工作排期
│ └── [模块名]_workline.md
└── contracts/ # 各模块对接契约
└── [模块名]_contract.md
```
---
## §4 历史仲裁（已迁移）
以下仲裁已在此前完成，原始记录见 [coord-final-decisions.md](../coord-final-decisions.md) 和 [president-final-rulings.md](../president-final-rulings.md)：
- I1-I8：iam P2 契约（coord-final-decisions.md §1）
- F1-F9：BFF 设计裁决（coord-final-decisions.md §2）
- G1-G3：Gateway 裁决（coord-final-decisions.md §3）
- N1-N3：content 裁决（coord-final-decisions.md §4）
- 总裁裁决 70+ 项（president-final-rulings.md §1-§5）
本文件仅记录**新流程启动后**（2026-07-09 起）的仲裁。

229
docs/architecture/issues/matrix.md Normal file
View File

@@ -0,0 +1,229 @@
# 上下游对接总矩阵
> 维护者：coord（协调 AI）
> 关联：[coord.md](./coord.md)、[workline.md](./workline.md)、各模块 [contracts/](./contracts/)
> 模式：全并行开发（各 AI 一口气完成 P2-P6，开发期间用 mock，最后统一集成测试）
---
## §1 服务依赖矩阵（谁调用谁）
```mermaid
graph TB
subgraph Frontend["微前端层"]
TP[teacher-portal<br/>ai13 :4000]
SP[student-portal<br/>ai14 :4001]
PP[parent-portal<br/>ai15 :4002]
AP[admin-portal<br/>ai16 :4003]
end
subgraph Gateway["网关层"]
AGW[api-gateway<br/>ai01 :8080]
PGW[push-gateway<br/>ai02 :8081]
end
subgraph BFF["BFF 层"]
TBFF[teacher-bff<br/>ai03 :3003 GraphQL]
SBFF[student-bff<br/>ai04 :3009 GraphQL]
PBFF[parent-bff<br/>ai05 :3010 GraphQL]
end
subgraph Services["业务服务层"]
IAM[iam<br/>ai06 :50052]
CORE[core-edu<br/>ai08 :50053]
CONTENT[content<br/>ai09 :50054]
MSG[msg<br/>ai10 :50056]
DATA[data-ana<br/>ai11 :50055]
AISVC[ai<br/>ai12 :50057]
end
TP --> AGW
SP --> AGW
PP --> AGW
AP --> AGW
TP -.推送.-> PGW
SP -.推送.-> PGW
PP -.推送.-> PGW
AGW --> TBFF
AGW --> SBFF
AGW --> PBFF
TBFF --> IAM
TBFF --> CORE
TBFF --> CONTENT
TBFF --> DATA
TBFF --> MSG
TBFF --> AISVC
SBFF --> IAM
SBFF --> CORE
SBFF --> CONTENT
SBFF --> DATA
PBFF --> IAM
PBFF --> CORE
PGW --> MSG
AISVC --> CONTENT
AISVC --> DATA
CORE -.Kafka.-> CONTENT
CORE -.Kafka.-> DATA
CORE -.Kafka.-> MSG
CONTENT -.Kafka.-> DATA
IAM -.Kafka.-> CORE
IAM -.Kafka.-> MSG
```
---
## §2 gRPC 接口提供方矩阵
| 提供方 | gRPC 端口 | Service | RPC 数 | 消费方 | 就绪信号 | 状态 |
| --------------- | --------- | --------------------------------------------------------------------------------- | ------ | ---------------------------------------------------- | ----------------------------- | ---- |
| iam (ai06) | 50052 | IamService | 12 | teacher-bff / student-bff / parent-bff / api-gateway | HealthService.Check = SERVING | ⏳ |
| core-edu (ai08) | 50053 | ClassService + ExamService + HomeworkService + GradeService + AttendanceService | 22 | teacher-bff / student-bff / parent-bff | HealthService.Check = SERVING | ⏳ |
| content (ai09) | 50054 | TextbookService + ChapterService + KnowledgeGraphService + QuestionService | 18 | teacher-bff / student-bff / ai | HealthService.Check = SERVING | ⏳ |
| data-ana (ai11) | 50055 | AnalyticsService | 12 | teacher-bff / student-bff / parent-bff / ai | HealthService.Check = SERVING | ⏳ |
| msg (ai10) | 50056 | NotificationService + NotificationPreferenceService + NotificationTemplateService | 13 | teacher-bff / push-gateway | HealthService.Check = SERVING | ⏳ |
| ai (ai12) | 50057 | AiService | 6 | teacher-bff | HealthService.Check = SERVING | ⏳ |
---
## §3 GraphQL 接口提供方矩阵
| 提供方 | HTTP 端口 | Endpoint | 消费方 | schema 文件 | 状态 |
| ------------------ | --------- | ------------- | ----------------------------- | -------------------------------------------------------- | ---- |
| teacher-bff (ai03) | 3003 | POST /graphql | teacher-portal / admin-portal | packages/shared-ts/contracts/graphql/teacher-bff.graphql | ⏳ |
| student-bff (ai04) | 3009 | POST /graphql | student-portal | packages/shared-ts/contracts/graphql/student-bff.graphql | ⏳ |
| parent-bff (ai05) | 3010 | POST /graphql | parent-portal | packages/shared-ts/contracts/graphql/parent-bff.graphql | ⏳ |
---
## §4 Kafka 事件发布方矩阵
| 发布方 | Topic | Event | 消费方 | Outbox | 状态 |
| --------------- | --------------------------- | ----------------------------------------------------- | --------------------------------------------------------- | ------- | ---- |
| iam (ai06) | edu.iam.user.events | UserEvent（created/updated/deleted/role_changed） | core-edu / msg / push-gateway / teacher-bff / student-bff | ✅ | ⏳ |
| iam (ai06) | edu.iam.role.events | RoleEvent（created/updated） | core-edu / msg | ✅ | ⏳ |
| iam (ai06) | edu.iam.audit.created | AuditEvent（create/update/delete/login/logout） | admin-portal | ✅ | ⏳ |
| core-edu (ai08) | edu.exam.events | ExamEvent（created/updated/deleted） | msg / data-ana / push-gateway | ✅ | ⏳ |
| core-edu (ai08) | edu.homework.events | HomeworkEvent（assigned/submitted/graded） | msg / data-ana / push-gateway | ✅ | ⏳ |
| core-edu (ai08) | edu.grade.events | GradeEvent（recorded/updated） | msg / push-gateway / parent-bff | ✅ | ⏳ |
| core-edu (ai08) | edu.class.events | ClassEvent（transferred） | msg / data-ana | ✅ | ⏳ |
| content (ai09) | edu.content.kp.events | KnowledgePointEvent（created/updated/prerequisite_*） | data-ana / ai / Neo4j Sync / ES Sync | ✅ | ⏳ |
| content (ai09) | edu.content.question.events | QuestionEvent（created/updated/published/deleted） | data-ana / ai / ES Sync | ✅ | ⏳ |
| msg (ai10) | edu.notification.requested | NotificationEvent（sent） | push-gateway / data-ana | ✅ | ⏳ |
| data-ana (ai11) | edu.analytics.mastery | MasteryEvent（mastery.updated / warning.triggered） | core-edu / msg | ❌ 豁免 | ⏳ |
| ai (ai12) | edu.ai.usage | AIUsageEvent（chat/generate/lesson） | data-ana | ❌ 豁免 | ⏳ |
---
## §5 HTTP 接口矩阵（非 gRPC / 非 GraphQL）
| 提供方 | Method | Path | 用途 | 消费方 | 认证 | 状态 |
| ------------------- | ------ | ----------------- | -------------------- | ----------------------------------------------- | -------------- | ---- |
| api-gateway (ai01) | * | /api/v1/teacher/* | 反向代理 teacher-bff | teacher-portal | JWT | ⏳ |
| api-gateway (ai01) | * | /api/v1/student/* | 反向代理 student-bff | student-portal | JWT | ⏳ |
| api-gateway (ai01) | * | /api/v1/parent/* | 反向代理 parent-bff | parent-portal | JWT | ⏳ |
| api-gateway (ai01) | * | /api/v1/iam/* | 反向代理 iam | （内部） | JWT | ⏳ |
| push-gateway (ai02) | WS | /ws | WebSocket 推送通道 | teacher-portal / student-portal / parent-portal | JWT | ⏳ |
| push-gateway (ai02) | SSE | /sse | SSE 推送通道 | teacher-portal | JWT | ⏳ |
| push-gateway (ai02) | POST | /internal/push | 内部推送入口 | msg | X-Internal-Key | ⏳ |
| iam (ai06) | GET | /healthz | 存活检查 | k8s / 监控 | 无 | ⏳ |
| iam (ai06) | GET | /readyz | 就绪检查（5 依赖） | k8s / 监控 | 无 | ⏳ |
| 所有服务 | GET | /metrics | Prometheus 指标 | Prometheus | 无 | ⏳ |
---
## §6 错误码前缀矩阵
| 模块 | 前缀 | 示例 |
| ------------ | --------- | -------------------------------------------------- |
| api-gateway | GW_ | GW_UNAUTHORIZED / GW_RATE_LIMITED |
| push-gateway | PUSH_ | PUSH_DEVICE_NOT_FOUND / PUSH_CHANNEL_FAILED |
| teacher-bff | BFF_XXX_ | BFF_TEACHER_UNAUTHORIZED / BFF_TEACHER_BAD_GATEWAY |
| student-bff | BFF_XXX_ | BFF_STUDENT_UNAUTHORIZED |
| parent-bff | BFF_XXX_ | BFF_PARENT_CHILD_NOT_BOUND |
| iam | IAM_ | IAM_USER_NOT_FOUND / IAM_INVALID_CREDENTIALS |
| core-edu | CORE_EDU_ | CORE_EDU_EXAM_NOT_FOUND |
| content | CONTENT_ | CONTENT_QUESTION_NOT_FOUND |
| msg | MSG_ | MSG_NOTIFICATION_NOT_FOUND |
| data-ana | DATA_ANA_ | DATA_ANA_DASHBOARD_UNAVAILABLE |
| ai | AI_ | AI_GENERATION_FAILED / AI_QUOTA_EXCEEDED |
---
## §7 全并行开发 Mock 策略汇总
| 消费方 | 消费的接口 | Mock 方式 | 切换真实时机 |
| -------------- | ----------------------------------- | --------------------------------------- | ----------------------------------- |
| api-gateway | iam.GetPublicKey | 硬编码 RS256 公钥（DEV_MODE） | iam gRPC 50052 就绪 |
| teacher-bff | iam gRPC 12 RPC | grpc-mock 拦截 + 固定 JSON | iam 就绪信号 ✅ |
| teacher-bff | core-edu gRPC 22 RPC | grpc-mock 拦截 + 固定 JSON | core-edu 就绪信号 ✅ |
| student-bff | iam + core-edu + content + data-ana | grpc-mock 拦截 | 各服务就绪信号 ✅ |
| parent-bff | iam + core-edu | grpc-mock 拦截 | 各服务就绪信号 ✅ |
| teacher-portal | teacher-bff GraphQL | MSW 拦截 + 固定 response | teacher-bff GraphQL 就绪 ✅ |
| student-portal | student-bff GraphQL | MSW 拦截 | student-bff GraphQL 就绪 ✅ |
| parent-portal | parent-bff GraphQL | MSW 拦截 | parent-bff GraphQL 就绪 ✅ |
| admin-portal | teacher-bff GraphQL (admin) | MSW 拦截 | teacher-bff admin namespace 就绪 ✅ |
| push-gateway | msg Kafka 事件 | 本地 Kafka mock producer | msg 就绪信号 ✅ |
| ai | content + data-ana gRPC | grpc-mock 拦截 | 各服务就绪信号 ✅ |
| data-ana | core-edu/content/ai Kafka + CDC | 本地 Kafka mock + ClickHouse 模拟数据集 | 各服务就绪信号 ✅ |
---
## §8 就绪信号跟踪表
> 各 AI 完成模块后，在此表更新状态（⏳ 进行中 → ✅ 就绪）
| 模块 | AI | 就绪信号 | 状态 | 完成时间 |
| -------------- | ---- | ------------------------------------------- | ---- | -------- |
| iam | ai06 | gRPC 50052 + 12 RPC + HealthService SERVING | ⏳ | - |
| api-gateway | ai01 | :8080 可访问 + JWT 验签 | ⏳ | - |
| teacher-bff | ai03 | POST /graphql + 5 Query | ⏳ | - |
| teacher-portal | ai13 | :4000 可访问 + 登录→Dashboard | ⏳ | - |
| core-edu | ai08 | gRPC 50053 + 22 RPC + HealthService SERVING | ⏳ | - |
| content | ai09 | gRPC 50054 + 18 RPC + HealthService SERVING | ⏳ | - |
| msg | ai10 | gRPC 50056 + 13 RPC + HealthService SERVING | ⏳ | - |
| data-ana | ai11 | gRPC 50055 + 12 RPC + HealthService SERVING | ⏳ | - |
| ai | ai12 | gRPC 50057 + 6 RPC + HealthService SERVING | ⏳ | - |
| student-bff | ai04 | POST /graphql + Dashboard Query | ⏳ | - |
| parent-bff | ai05 | POST /graphql + Dashboard Query | ⏳ | - |
| push-gateway | ai02 | :8081 可访问 + /internal/push | ⏳ | - |
| student-portal | ai14 | :4001 可访问 + MF Remote | ⏳ | - |
| parent-portal | ai15 | :4002 可访问 + MF Remote | ⏳ | - |
| admin-portal | ai16 | :4003 可访问 + MF Remote + admin | ⏳ | - |
---
## §9 统一集成测试检查清单
> 所有模块就绪后，按此清单进行统一集成测试
### 9.1 认证链路
- [ ] teacher-portal 登录 → api-gateway → iam → JWT 签发
- [ ] JWT 验签 → x-user-id 注入 → teacher-bff 读取
### 9.2 GraphQL 链路
- [ ] teacher-portal → teacher-bff GraphQL dashboard Query
- [ ] teacher-bff → iam gRPC + core-edu gRPC 并行聚合
- [ ] ActionState 信封正确返回
### 9.3 事件链路
- [ ] core-edu 发布 GradeEvent → Kafka → msg 消费 → push-gateway 推送
- [ ] data-ana 消费 CDC 事件 → ClickHouse 写入
### 9.4 MF 链路
- [ ] teacher-portal Shell 加载 student-portal Remote
- [ ] GraphQL client 单例跨 Remote 共享
### 9.5 推送链路
- [ ] msg → push-gateway /internal/push → WebSocket 推送到前端

24
docs/architecture/issues/objections/admin-portal_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# admin-portal 问题记录
> 负责人：ai16
> 关联：[coord.md](../coord.md)、[contracts/admin-portal_contract.md](../contracts/admin-portal_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/ai_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# ai 问题记录
> 负责人：ai12
> 关联：[coord.md](../coord.md)、[contracts/ai_contract.md](../contracts/ai_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/api-gateway_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# api-gateway 问题记录
> 负责人：ai01
> 关联：[coord.md](../coord.md)、[contracts/api-gateway_contract.md](../contracts/api-gateway_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

58
docs/architecture/issues/objections/classes_issue.md Normal file
View File

@@ -0,0 +1,58 @@
# classes 问题记录
> 负责人：ai07
> 关联：[coord.md](../coord.md)、[contracts/classes_contract.md](../contracts/classes_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
### ISSUE-001-ai07：P3 合并后 classes 目录保留方式
- **提请方**：ai07
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：classes 是黄金模板，P3 合并入 core-edu 后，`services/classes/` 目录是否保留？若保留，是只读对照基准还是改为 shared-ts 模板？若删除，黄金模板对照基准丢失，其他 TS 服务无法对齐。
- **建议方案**：保留 `services/classes/` 作为只读对照基准（不删除），core-edu 复制其结构。黄金模板 checklist（02-architecture-design.md §10）由 ai07 持续维护。
- **状态**：待 coord 仲裁
### ISSUE-002-ai07：cuid2 迁移时机
- **提请方**：ai07
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：classes 当前用 uuid v4 生成 ID，project_rules 要求 cuid2。迁移时机有两种选择：(A) P1 黄金模板立即迁移；(B) P3 合并入 core-edu 时统一迁移。若选 A，黄金模板先行避免 ai08 继承 uuid 遗留；若选 B，减少一次迁移成本。
- **建议方案**：选 A（P1 立即迁移），黄金模板应先行，避免其他服务继承 uuid 遗留。迁移涉及 classes 表主键、proto message 字段类型。
- **状态**：待 coord 仲裁
### ISSUE-003-ai07：proto ClassService 合并后归属
- **提请方**：ai07
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：P3 合并入 core-edu 后，`classes.proto` 的 `ClassService` 是否迁移到 `core_edu.proto`？若迁移，破坏 proto 契约稳定性（下游需更新 import）；若保留，core_edu.proto 不会膨胀但需在 core-edu 实现中 import classes.proto。
- **建议方案**：保留 `classes.proto` 由 core-edu 实现（选项 B），保持契约稳定性，避免下游 import 路径变更。
- **状态**：待 coord 仲裁
### ISSUE-004-ai07：node:20-alpine → node:22-alpine 升级时机
- **提请方**：ai07
- **日期**：2026-07-10
- **类型**：其他
- **描述**：classes Dockerfile 用 `node:20-alpine`，project_rules §15.8 镜像预拉清单是 `node:22-alpine`。是 P1 立即升级还是等统一升级？
- **建议方案**：P1 立即升级，影响所有 TS 服务 Dockerfile 基准，黄金模板应先行。
- **状态**：待 coord 仲裁

24
docs/architecture/issues/objections/content_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# content 问题记录
> 负责人：ai09
> 关联：[coord.md](../coord.md)、[contracts/content_contract.md](../contracts/content_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/core-edu_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# core-edu 问题记录
> 负责人：ai08
> 关联：[coord.md](../coord.md)、[contracts/core-edu_contract.md](../contracts/core-edu_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

13
docs/architecture/issues/objections/cross_issue.md Normal file
View File

@@ -0,0 +1,13 @@
# 跨模块问题记录
> 维护者：所有 AI（跨模块问题在此追加）
> 关联：[coord.md](../coord.md)
> 规则：涉及多个模块的问题在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!-- 追加条目格式同各模块 issue.md -->
（暂无问题）

24
docs/architecture/issues/objections/data-ana_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# data-ana 问题记录
> 负责人：ai11
> 关联：[coord.md](../coord.md)、[contracts/data-ana_contract.md](../contracts/data-ana_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/iam_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# iam 问题记录
> 负责人：ai06
> 关联：[coord.md](../coord.md)、[contracts/iam_contract.md](../contracts/iam_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/msg_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# msg 问题记录
> 负责人：ai10
> 关联：[coord.md](../coord.md)、[contracts/msg_contract.md](../contracts/msg_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/parent-bff_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# parent-bff 问题记录
> 负责人：ai05
> 关联：[coord.md](../coord.md)、[contracts/parent-bff_contract.md](../contracts/parent-bff_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/parent-portal_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# parent-portal 问题记录
> 负责人：ai15
> 关联：[coord.md](../coord.md)、[contracts/parent-portal_contract.md](../contracts/parent-portal_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/push-gateway_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# push-gateway 问题记录
> 负责人：ai02
> 关联：[coord.md](../coord.md)、[contracts/push-gateway_contract.md](../contracts/push-gateway_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/student-bff_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# student-bff 问题记录
> 负责人：ai04
> 关联：[coord.md](../coord.md)、[contracts/student-bff_contract.md](../contracts/student-bff_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/student-portal_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# student-portal 问题记录
> 负责人：ai14
> 关联：[coord.md](../coord.md)、[contracts/student-portal_contract.md](../contracts/student-portal_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

24
docs/architecture/issues/objections/teacher-bff_issue.md Normal file
View File

@@ -0,0 +1,24 @@
# teacher-bff 问题记录
> 负责人：ai03
> 关联：[coord.md](../coord.md)、[contracts/teacher-bff_contract.md](../contracts/teacher-bff_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

161
docs/architecture/issues/objections/teacher-portal_issue.md Normal file
View File

@@ -0,0 +1,161 @@
# teacher-portal 问题记录
> 负责人：ai13
> 关联：[coord.md](../coord.md)、[contracts/teacher-portal_contract.md](../contracts/teacher-portal_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
> 迁移说明：本文件 ISSUE-036~041 迁移自旧 `docs/issues.md` §2.7（已按总裁裁决 §0.4 编号冲突整理规则保留原始编号 + 追加 `<提请AI>` 后缀）
---
## 问题列表
### ISSUE-036-ai13：03-long-term-architecture.md "REST→GraphQL 演进策略"与 F9 裁决冲突
- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：裁决冲突 + 文档同步遗漏
- **阶段**：P2
- **描述**：
- coord F9 裁决："P2 起 BFF 用 GraphQL，前端用 urql/apollo"，禁止"P2-P6 REST，未来切 GraphQL"
- ai13 `apps/teacher-portal/docs/03-long-term-architecture.md` §1.4（提请时误记为 §6，实际 §6 是 i18n）仍保留"REST→GraphQL 切换策略"过渡方案（P2-P4 REST + P5+ 迁移 + feature flag 灰度）
- 与 F9 裁决直接冲突，违反"不分阶段"原则
- **建议方案**：
1. 删除 §1.4 "REST → GraphQL 切换策略"整节
2. 替换为"GraphQL 客户端架构（P2 起最终方案）"
3. 同步更新 §1.1 P2 行 + §1.2 表格 + §12.3 #3 待裁决问题
- **状态**：✅ 已回写闭合（2026-07-09，批次 0.15 后）
- **coord 裁决**：总裁裁决 §3.4 + §4.4 第 5 条（删除过渡方案本身，保留设计决策记录）
- **回写执行**：详见 [03-long-term-architecture.md §14.1](../../../apps/teacher-portal/docs/03-long-term-architecture.md)
---
### ISSUE-037-ai13：ai13 与 ai03 的 GraphQL schema 契约协调机制未明确
- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：契约不明确
- **阶段**：P2
- **描述**：
- F9 裁决：P2 起 BFF 用 GraphQL（teacher-bff ai03 实现 GraphQL Yoga server），前端用 urql（teacher-portal ai13 实现 GraphQL client）
- B1 裁决：GraphQL Yoga + DataLoader
- ai13 与 ai03 的 GraphQL schema 契约如何协调未明确：
- schema 定义权归属（ai03 定义 server schema，ai13 消费？还是 coord 仲裁第一版？）
- schema 版本管理（GraphQL schema 演进如何同步前后端？）
- 查询/变更/订阅的命名规范（camelCase vs snake_case？分页规范？）
- 错误响应格式（GraphQL errors 数组 vs ActionState 信封？）
- 与 ISSUE-019（ai08 core-edu 调用侧）/ ISSUE-030（ai04 student-bff 前端消费侧）同类但不同 BFF
- **建议方案**：
1. coord 在批次 1 启动前仲裁 teacher-bff GraphQL schema 第一版
2. 建立"schema-first"工作流：ai03 定义 → coord 仲裁 → ai13 消费 → 变更需 PR + 双方 review
3. 明确 GraphQL 规范：camelCase 命名、Relay Cursor Connections 分页、errors 数组扩展 ActionState 字段（extensions.code = BFF_TEACHER_*）
4. 建立 schema 注册表（packages/shared-ts/contracts/graphql/）
- **状态**：✅ 已裁决
- **coord 裁决**：总裁裁决 §2.2（GraphQL schema 仲裁机制）—— SDL-first，存放 `packages/shared-ts/contracts/graphql/`，各 BFF AI 起草 + coord 仲裁第一版
- **执行**：ai13 待 ai03 起草 teacher-bff schema 后消费，coord 批次 1 启动前仲裁
---
### ISSUE-038-ai13：MF 暴露 AppShell 整体是否包含 GraphQL client 单例未明确
- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：契约不明确
- **阶段**：P2
- **描述**：
- F10 裁决："暴露 AppShell 整体，各 Remote 自行决定内部布局"
- 问题：AppShell 整体暴露是否包含 GraphQL client 单例（urql Client）？
- 方案 A（包含）：Shell 初始化 GraphQL client，通过 React Context 注入给所有 Remote，共享同一 client 实例 + 缓存
- 方案 B（不包含）：各 Remote 自行初始化，缓存隔离
- 方案 A 风险：MF 跨 React 实例时 Context 共享有坑（shared singleton 要求）
- 方案 B 风险：缓存隔离导致跨 Remote 数据不一致
- **建议方案**：建议方案 A（Shell 暴露 GraphQL client 单例）
- **状态**：✅ 已裁决
- **coord 裁决**：总裁裁决 §2.17（采纳方案 A：Shell 暴露 GraphQLProvider，student/parent/admin Remote 复用 Shell 单例）
- **执行**：ai13 P2 实现 Shell GraphQLProvider，ai14/ai15/ai16 消费；MF shared 配置 react/urql/graphql 设为 singleton
---
### ISSUE-039-ai13：F8 ai13 维护 packages 的建立时机与依赖未明确
- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：前置依赖未就绪 + 工作归属不明
- **阶段**：P2
- **描述**：
- F8 裁决："ai13 维护 ui-tokens/ui-components/hooks，coord 仅维护 shared-ts/contracts"
- 问题：
- 这 3 个 packages 何时建立？P2 启动前？P2 启动时？
- ai13 P2 首次实现是否依赖这 3 个 packages 已就位？
- packages 的依赖关系：ui-components 依赖 ui-tokens，hooks 依赖 ui-components？还是平级？
- 4 个 portal 是否都消费？版本管理策略？
- ai-work-orchestration.md §3.1 批次 0 未列出这 3 个 packages 的建立任务
- **建议方案**：
1. ai13 在 P2 启动前（批次 0 末）建立 3 个 packages 骨架
2. 依赖关系：ui-tokens（无依赖）→ ui-components（依赖 ui-tokens）→ hooks（依赖 ui-components）
3. 4 个 portal 统一消费，版本通过 pnpm workspace 协议（"workspace:*"）
4. ai13 完成后通知 ai14/ai15/ai16 消费
- **状态**：✅ 已裁决 + 已执行
- **coord 裁决**：总裁裁决 §2.18（ai13 在 P2 启动前 = 批次 0.15 建立 3 个 packages 骨架，4 个 portal 统一消费）
- **执行**：ai13 已于批次 0.15 完成建立：
- `packages/ui-tokens/`（colors/typography/spacing/shadows + index.ts）
- `packages/ui-components/`（cn/error-boundary/loading/empty/require-permission + index.ts）
- `packages/hooks/`（use-auth/use-permission/use-a11y-id/use-toast/use-trace-id/use-aria-live/use-api/use-viewports + types + index.ts）
- 依赖方向：ui-tokens ← ui-components ← hooks（hooks 不依赖 iam，权限数据 props 注入）
- pnpm-workspace.yaml 已注册 packages/*
---
### ISSUE-040-ai13：ai13 teacher-portal P2 功能范围与下游服务启用阶段的关系未明确
- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：跨度过大
- **阶段**：P2
- **描述**：
- ai-work-orchestration.md §4.3 明确 ai13 P2 范围：client 改造 + MF shell + 共享组件抽取
- 但 teacher-portal P2 阶段需对接 teacher-bff（ai03 P2 启动）的哪些 GraphQL 查询未明确：
- P2 仅实现登录 + Dashboard 框架？
- 还是包含班级列表 + 学生列表等基础教学功能？
- teacher-bff P2 只调 iam（gRPC），core-edu P3 / content P4 / data-ana P4 才启用
- 若 teacher-portal P2 实现班级/学生/作业等页面，但 teacher-bff P2 无法 gRPC 调 core-edu（P3 才启用），数据来源断裂
- ISSUE-004/005 已裁决"BFF 跨阶段扩展下游"是允许的例外，但前端是否也跟随？
- **建议方案**：
1. 明确 ai13 P2 功能范围：登录 + 权限上下文 + Dashboard 框架 + 个人设置 + 班级列表（iam 数据）+ 学生列表（iam 数据）
2. P3 起跟随 teacher-bff 扩展 core-edu 相关页面
3. 前端路由骨架 P2 一次性建立，但页面内容随 BFF 能力分阶段填充
- **状态**：✅ 已裁决
- **coord 裁决**：总裁裁决 §3.5（ai13 P2 功能范围：登录 + 权限上下文 + Dashboard 框架 + 个人设置 + 班级列表 + 学生列表；P3-P5 跟随 teacher-bff 扩展）
- **执行**：ai13 P2 按此范围实现，见 workline.md §3 P2 详细任务
---
### ISSUE-041-ai13：仲裁评估总结 - 关键裁决对 ai13 的可行性与影响评估
- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：跨度过大（评估总结）
- **阶段**：P2-P6
- **描述**：ai13 完整阅读 coord-final-decisions.md（80+ 项裁决）+ ai-work-orchestration.md（批次 0-5 规划）+ issues.md（35 个已识别问题），对 ai13 的关键裁决影响评估：
| 裁决编号 | 裁决内容 | 对 ai13 影响 | 可行性 | 风险 |
| -------- | -------------------------------- | --------------------------------- | -------------------------------------- | -------------------------------------- |
| F9 | P2 起 GraphQL（urql） | 高：从 REST 改造为 GraphQL client | 中：schema 契约协调成本高（ISSUE-037） | schema 未及时仲裁阻塞 P2 |
| F12 | P2 localStorage token | 低：与原设计一致 | 高 | 无 |
| F8 | ai13 维护 3 个 packages | 中：新增 packages 建立任务 | 高：ai13 已设计完毕 | 时机不明确（ISSUE-039） |
| F10 | MF 暴露 AppShell 整体 | 中：Shell 设计需包含 Provider | 高 | GraphQL client 单例不明确（ISSUE-038） |
| F7 | 权限点命名 `<RESOURCE>_<ACTION>` | 低：命名规范调整 | 高 | 无 |
- **影响**：本评估总结供 coord 参考，不直接阻塞工作；具体阻塞问题已分别提请（ISSUE-036~040，均已裁决）
- **建议方案**：
1. coord 优先处理 ISSUE-037（schema 仲裁机制）+ ISSUE-039（packages 时机），二者是 ai13 P2 启动的关键前置 —— ✅ 均已裁决
2. ai13 在等待 coord 仲裁期间，先完成 03 文档回写（删除 REST→GraphQL）+ packages 骨架建立 —— ✅ 均已完成
3. ai13 与 ai03 建立 schema 协调通道（PR review + 双方签字）
- **状态**：✅ 仅供参考，无具体裁决需求（所有子问题 ISSUE-036~040 均已裁决）
- **coord 裁决**：总裁裁决 §10 问题索引表确认 ISSUE-036~041-ai13 映射到 §2.2/2.17/2.18/3.4/3.5
---
**AI Agent**: ai13（teacher-portal）
**Branch**: feat/teacher-portal-issues-migrate-ai13
**Coordinator**: coord-ai
**迁移说明**：本文件 ISSUE-036~041 迁移自旧 `docs/issues.md` §2.7，按总裁裁决 §0.4 保留原始编号 + 追加 `<提请AI>` 后缀，状态更新为已裁决

268
docs/architecture/issues/workline.md Normal file
View File

@@ -0,0 +1,268 @@
# 总工作安排（coord 汇总）
> 维护者：coord（协调 AI）
> 维护规则：各 AI 在 `worklines/[模块名]_workline.md` 写入甘特图工作排期 → coord 汇总到本文件
> 模式：**全并行**（各 AI 一口气完成 P2-P6 全部代码，开发期间用 mock，最后统一集成测试）
> 关联文档：[ai-work-orchestration.md](../ai-work-orchestration.md)、[coord.md](./coord.md)、[matrix.md](./matrix.md)、[president-final-rulings.md](../president-final-rulings.md)
---
## §1 16 AI 总时间线（甘特图）
```mermaid
gantt
title Edu 项目 16 AI 功能时间线（总裁裁决 §6.1 最终版）
dateFormat YYYY-MM-DD
axisFormat %m-%d
section 批次0 coord前置 3-5天
coord 0.1-0.14 proto+工具包 :crit, b0, 2026-07-09, 4d
ai13 0.15 packages骨架 :b0a, 2026-07-09, 3d
section 批次1 P2 7-10天
ai01 Gateway路由+shared-go :b1a, after b0, 8d
ai06 iam P2.1 gRPC+8RPC :crit, b1b, after b0, 8d
ai03 teacher-bff GraphQL Must :b1c, after b0, 8d
ai13 teacher-portal P2 MF Shell :b1d, after b0, 8d
section 批次2 P3 7-10天
ai07 classes代码交接 :b2a, after b1b, 2d
ai08 core-edu gRPC 50053 :crit, b2b, after b1b, 8d
ai04 student-bff GraphQL :b2c, after b1c, 8d
ai14 student-portal P3 :b2d, after b1d, 8d
ai03 teacher-bff P3扩展 :b2e, after b1c, 5d
section 批次3 P4 10-12天
ai09 content gRPC 50054+Question :crit, b3a, after b2b, 11d
ai11 data-ana gRPC 50055 :b3b, after b2b, 11d
ai05 parent-bff GraphQL :b3c, after b2c, 11d
ai15 parent-portal P4 :b3d, after b2d, 11d
section 批次4 P5 12-15天
ai10 msg gRPC 50056 :crit, b4a, after b3a, 13d
ai02 push-gateway HTTP :b4b, after b3a, 13d
ai12 ai服务 gRPC 50058 :b4c, after b3a, 13d
ai03 teacher-bff P5扩展 :b4d, after b3a, 8d
section 批次5 P6 10-12天
ai16 admin-portal MVP :crit, b5a, after b4a, 11d
iam P2.2补全 :b5b, after b4a, 11d
持续优化 /readyz硬化 :b5c, after b4a, 11d
```
**关键路径**（红色 crit）：批次0 → iam P2.1 → core-edu → content → msg → admin-portal
**总时间线**：49-64 天（约 10-13 周）
---
## §2 批次概览
| 批次 | 阶段 | 时间 | 参与AI | 完成信号 |
| ---- | ---------- | -------- | ------------------------------------ | ------------------ |
| 0 | coord 前置 | 3-5 天 | coord + ai13 | ✅ 2026-07-09 完成 |
| 1 | P2 | 7-10 天 | ai01 + ai06 + ai03 ⟷ ai13 | ⏳ 进行中 |
| 2 | P3 | 7-10 天 | ai07 + ai08 + ai04 ⟷ ai14 + ai03扩展 | ⏳ |
| 3 | P4 | 10-12 天 | ai09 + ai11 + ai05 ⟷ ai15 | ⏳ |
| 4 | P5 | 12-15 天 | ai10 ⟷ ai02 + ai12 + ai03扩展 | ⏳ |
| 5 | P6 | 10-12 天 | ai16 + 持续优化 | ⏳ |
---
## §3 批次 1（P2）详细排期
### 3.1 总甘特图
```mermaid
gantt
title 批次 1（P2）详细排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section ai01 api-gateway
1.1 路由表+双入口+shared-go接入 :a1a, 2026-07-10, 3d
1.2 JWT校验+JWKS fetcher :a1b, after a1a, 3d
1.3 限流+熔断+CORS :a1c, after a1b, 2d
section ai06 iam P2.1
6.1 gRPC server 50052启用 :crit, a6a, 2026-07-10, 2d
6.2 8 RPC实现(Register-GetChildrenByParent) :crit, a6b, after a6a, 4d
6.3 /readyz深度(5依赖检查) :a6c, after a6b, 1d
6.4 iam_student_guardians表+DataScope :a6d, after a6b, 1d
section ai03 teacher-bff
3.1 GraphQL schema第一版(ARB-001) :crit, a3a, 2026-07-10, 2d
3.2 Yoga endpoint+5 Query Resolver :crit, a3b, after a3a, 3d
3.3 DataLoader+N+1防御 :a3c, after a3b, 1d
3.4 ActionState信封+降级模式B :a3d, after a3b, 1d
3.5 /readyz探针列表 :a3e, after a3d, 1d
section ai13 teacher-portal
13.1 MF Shell配置(exposes+shared) :crit, a13a, 2026-07-10, 2d
13.2 GraphQLProvider+urql client单例 :crit, a13b, after a13a, 2d
13.3 AppShell改造(REST→GraphQL) :a13c, after a13b, 2d
13.4 登录页+Dashboard页+班级列表页 :a13d, after a13c, 2d
```
### 3.2 依赖关系
```
ai06.6.1 gRPC 启用 ──┬──> ai03.3.2 GraphQL Resolver（调用 iam gRPC）
└──> ai01.1.2 JWT 校验（调用 iam GetPublicKey）
ai03.3.1 schema 第一版 ──> ai13.13.2 GraphQLProvider（消费 schema）
ai03.3.2 Resolver ────────> ai13.13.3 AppShell 改造（viewports query）
ai01.1.1 路由表 ──> ai03.3.2 endpoint 对外可访问
└──> ai13.13.4 页面可访问
```
### 3.3 完成信号
批次 1 完成的 5 个标志：
1. ai06：iam gRPC 50052 启用 + 12 RPC 全部实现 + /readyz 返回 5 项依赖状态
2. ai01：api-gateway 路由 `/api/v1/teacher/*` → teacher-bff:3003 + JWKS 验签 + 限流
3. ai03：teacher-bff `POST /graphql` 可用 + 5 Query Resolver + DataLoader + ActionState
4. ai13：teacher-portal MF Shell 配置就绪 + 登录/Dashboard/班级列表页可用
5. 端到端：教师登录 → 看到 Dashboard（含班级列表 + 视口导航）
---
## §4 各 AI 工作清单（汇总）
> 详细排期见各模块 `_workline.md` 文件
### 4.1 ai01（api-gateway）
- P2：路由表 + JWT RS256 验签（JWKS） + 限流 + 熔断 + CORS + shared-go 接入
- 详见：[api-gateway_workline.md](./api-gateway_workline.md)
### 4.2 ai02（push-gateway）
- P5：HTTP /internal/* + Kafka 双通道 + 多设备会话隔离 + 审计表
- 详见：[push-gateway_workline.md](./push-gateway_workline.md)
### 4.3 ai03（teacher-bff）
- P2：GraphQL schema 第一版 + 5 Query Resolver + DataLoader + ActionState
- P3 扩展：exams/homework/grades Query + Mutation
- P5 扩展：notifications Query + SSE
- 详见：[teacher-bff_workline.md](./teacher-bff_workline.md)
### 4.4 ai04（student-bff）
- P3：GraphQL schema + Dashboard + 考试作答 + 作业提交
- 详见：[student-bff_workline.md](./student-bff_workline.md)
### 4.5 ai05（parent-bff）
- P4：GraphQL schema + Dashboard + 多子女切换 + 成绩趋势
- 详见：[parent-bff_workline.md](./parent-bff_workline.md)
### 4.6 ai06（iam）
- P2.1：gRPC 50052 + 12 RPC + /readyz 深度 + iam_student_guardians + DataScope
- P2.2：P3-P6 期间持续补充
- 详见：[iam_workline.md](./iam_workline.md)
### 4.7 ai07（classes → core-edu 交接）
- P3：classes 代码交接 + core-edu 服务骨架
- 详见：[core-edu_workline.md](./core-edu_workline.md)
### 4.8 ai08（core-edu）
- P3：gRPC 50053 + exams/homework/grades/attendance/class 全部 RPC + Outbox
- 详见：[core-edu_workline.md](./core-edu_workline.md)
### 4.9 ai09（content）
- P4：gRPC 50054 + textbook/chapter/knowledge-graph/question 4 service + Neo4j + ES
- 详见：[content_workline.md](./content_workline.md)
### 4.10 ai10（msg）
- P5：gRPC 50056 + notification/preference/template 3 service + Outbox
- 详见：[msg_workline.md](./msg_workline.md)
### 4.11 ai11（data-ana）
- P4：gRPC 50055 + 4 Dashboard + Warning + Mastery + ClickHouse + CDC 消费
- 详见：[data-ana_workline.md](./data-ana_workline.md)
### 4.12 ai12（ai 服务）
- P5：gRPC 50058 + Chat/GenerateQuestion/OptimizeExpression/LessonPlan + ES 检索
- 详见：[ai_workline.md](./ai_workline.md)
### 4.13 ai13（teacher-portal）
- P2：MF Shell + AppShell + GraphQL client + 登录/Dashboard/班级列表
- P3：考试/作业/成绩页面 + MF Remote 就绪
- 详见：[teacher-portal_workline.md](./teacher-portal_workline.md)
### 4.14 ai14（student-portal）
- P3：MF Remote + 考试作答 + 作业提交
- 详见：[student-portal_workline.md](./student-portal_workline.md)
### 4.15 ai15（parent-portal）
- P4：MF Remote + Dashboard + 多子女切换
- 详见：[parent-portal_workline.md](./parent-portal_workline.md)
### 4.16 ai16（admin-portal）
- P6：MVP + 用户管理 + 角色权限 + 审计日志
- 详见：[admin-portal_workline.md](./admin-portal_workline.md)
---
## §5 工作流说明
### 5.1 各 AI 写入 `_workline.md`
各 AI 在自己模块的 `[模块名]_workline.md` 中写入甘特图排期，格式：
````markdown
# [模块名] 工作排期
## §1 总览
[模块职责简述]
## §2 甘特图
```mermaid
gantt
title [模块名] 工作排期
dateFormat YYYY-MM-DD
...
```
````
## §3 详细任务
### [阶段] [任务编号]：[任务名]
- 负责人：aiXX
- 依赖：[前置任务]
- 交付物：[具体文件/功能]
- 验收标准：[验收点]
```
### 5.2 coord 汇总
coord 审阅各 `_workline.md` 后，在本文件（workline.md）汇总：
- §1 总时间线（16 AI 甘特图）
- §2 批次概览
- §3 当前批次详细排期
- §4 各 AI 工作清单（链接到各 `_workline.md`）
### 5.3 更新时机
- 批次启动前：coord 写入 §3 当前批次详细排期
- 批次进行中：各 AI 更新自己的 `_workline.md`（标记完成进度）
- 批次完成后：coord 更新 §2 完成信号 + §1 总进度
```

45
docs/architecture/issues/worklines/admin-portal_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# admin-portal 工作排期
> 负责人：ai16
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/admin-portal_contract.md](../contracts/admin-portal_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
admin-portal 是管理端微前端，通过 MF Remote 接入主应用，覆盖用户管理、角色权限、审计日志等场景。全阶段目标：P2 MF Remote 骨架 → P3 用户管理+角色权限+审计日志 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai16 admin-portal 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a16a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai16 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai16
- **交付物**：⚠️ 由 ai16 自行补充
- **依赖**：见 [contracts/admin-portal_contract.md](../contracts/admin-portal_contract.md)
- **验收标准**：⚠️ 由 ai16 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai16 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai16 自行补充

45
docs/architecture/issues/worklines/ai_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# ai 工作排期
> 负责人：ai12
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/ai_contract.md](../contracts/ai_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
ai 是智能服务，提供 AiService（6 个 RPC），结合 Elasticsearch 检索与 LLM 网关实现智能问答与推荐。全阶段目标：P2 ES 接入+LLM 网关 → P3 AiService 6 RPC → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai12 ai 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a12a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai12 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai12
- **交付物**：⚠️ 由 ai12 自行补充
- **依赖**：见 [contracts/ai_contract.md](../contracts/ai_contract.md)
- **验收标准**：⚠️ 由 ai12 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai12 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai12 自行补充

57
docs/architecture/issues/worklines/api-gateway_workline.md Normal file
View File

@@ -0,0 +1,57 @@
# api-gateway 工作排期
> 负责人：ai01
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/api-gateway_contract.md](../contracts/api-gateway_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
api-gateway 是 Edu 系统统一入口，负责路由、JWT 验签、限流、熔断、CORS。全阶段目标：P2 路由+JWT → P3 限流加固 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai01 api-gateway 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2 基础
路由表+双入口+shared-go :a1a, 2026-07-10, 3d
JWT校验+JWKS fetcher :a1b, after a1a, 3d
限流+熔断+CORS :a1c, after a1b, 2d
section P3-P6 持续优化
路由扩展(student/parent/admin) :a1d, after a1c, 2d
指标+链路加固 :a1e, after a1d, 2d
```
> **注意**：以上为 coord 初始规划，ai01 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### P2：路由表 + JWT + 限流
- **负责人**：ai01
- **交付物**：
- `services/api-gateway/internal/routing/router.go` — 路由表
- `/api/v1/teacher/*` → teacher-bff:3003 代理
- `/api/v1/iam/*` → iam:3002 代理
- JWT RS256 验签（shared-go/jwks）
- 限流 + 熔断 + CORS
- **依赖**：shared-go 骨架（批次 0 已完成）+ iam GetPublicKey（ai06）
- **验收标准**：路由双入口 + JWT 验签 + 限流 + CORS 白名单
- **完整 P3-P6 任务**：⚠️ 由 ai01 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：iam GetPublicKey RPC（ai06）
- **我的就绪信号**：api-gateway :8080 可访问 + JWT 验签可用

107
docs/architecture/issues/worklines/classes_workline.md Normal file
View File

@@ -0,0 +1,107 @@
# classes 工作排期
> 负责人：ai07
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/classes_contract.md](../contracts/classes_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
> 特殊说明：classes 是黄金模板（P1 已实现），P3 合并入 core-edu（ai08 接管）
---
## §1 总览
classes 是 Edu 微服务的黄金模板，P1 阶段已实现班级 CRUD + 全横切关注点。P3 阶段合并入 core-edu 后，classes 模块代码由 ai08 接管维护，但黄金模板对照 checklist 由 ai07 持续维护。
**全阶段目标**：
- P1（已完成）：班级 CRUD + 黄金模板 + 6 项整改
- P3：合并入 core-edu + Outbox + gRPC + DataScope + Redis 缓存 + cuid2 迁移
- P6：黄金模板 checklist 持续维护 + 硬化
---
## §2 全阶段甘特图（P1-P6）
```mermaid
gantt
title ai07 classes 黄金模板全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P1 黄金模板整改
阶段1+2架构设计文档 :crit, a7a, 2026-07-10, 1d
typeorm移除+tracer修复+@Query替换 :crit, a7b, 2026-07-10, 1d
测试覆盖率60→80%+Dockerfile升级 :a7c, 2026-07-11, 1d
schema索引补齐 :a7d, 2026-07-11, 1d
section P3 合并入core-edu
shared/outbox目录补齐 :a7e, 2026-07-14, 2d
cuid2迁移+DataScope注入 :a7f, 2026-07-15, 2d
Redis缓存+软删除+分页 :a7g, 2026-07-17, 3d
gRPC 50053启用+核心edu合并 :a7h, 2026-07-20, 2d
section P6 硬化
黄金模板checklist持续维护 :a7i, 2026-07-25, 5d
可观测性增强+告警规则 :a7j, 2026-07-30, 3d
```
---
## §3 详细任务
### P1：黄金模板整改（立即）
| # | 任务 | 交付物 | 验收标准 | 状态 |
| --- | ----------------------------------- | ------------------------------------------------------------------------- | --------------------------------- | --------- |
| 1 | 阶段 1+2 架构设计文档 | `services/classes/docs/01-understanding.md` + `02-architecture-design.md` | coord 交叉审查通过 | ✅ 已完成 |
| 2 | 移除 typeorm 冗余依赖 | `package.json` 删除 typeorm 行 | `pnpm install` 零错误 | 待执行 |
| 3 | tracer.ts console.log → logger.info | `src/shared/observability/tracer.ts` L20 | grep `console.log` 返回 0 | 待执行 |
| 4 | controller list @Req → @Query | `src/classes/classes.controller.ts` L49-53 | list 方法用 `@Query('gradeId')` | 待执行 |
| 5 | 测试覆盖率阈值 60% → 80% | `vitest.config.ts` + 补测试用例 | `pnpm test:coverage` 达 80% | 待执行 |
| 6 | Dockerfile node:20 → node:22 | `Dockerfile` | 基础镜像 `node:22-alpine` | 待执行 |
| 7 | schema 补齐索引 | `classes.schema.ts` + 迁移脚本 | grade_id / head_teacher_id 有索引 | 待执行 |
### P3：合并入 core-edu（交接给 ai08）
| # | 任务 | 交付物 | 验收标准 | 状态 |
| --- | ------------------------- | ---------------------------------------------------------- | ------------------------------- | ------ |
| 1 | `shared/outbox/` 目录补齐 | outbox.repository / outbox.publisher / outbox.relay-worker | 事件可发布到 Kafka | 待执行 |
| 2 | cuid2 迁移 | id 字段 uuid v4 → cuid2 + 数据迁移脚本 | 双写过渡期完成 | 待执行 |
| 3 | DataScope 6 级 WHERE 注入 | Repository list 方法接收 dataScope 参数 | 6 级过滤生效 | 待执行 |
| 4 | Redis 班级列表缓存 | cachedList 方法 + TTL 5 分钟 + 事件失效 | 缓存命中率 > 80% | 待执行 |
| 5 | 软删除 + 审计字段 | deleted_at / created_by / updated_by | DELETE 改软删除 | 待执行 |
| 6 | 分页 + 批量查询 | 游标分页 + POST /classes/batch | proto page_size/page_token 落地 | 待执行 |
| 7 | gRPC server 50053 启用 | ClassService 5 RPC 实现 | gRPC health check SERVING | 待执行 |
| 8 | PermissionGuard 改调 iam | 动态权限查询 getEffectivePermissions | 角色变更无需改代码重启 | 待执行 |
### P6：硬化
| # | 任务 | 交付物 | 验收标准 | 状态 |
| --- | --------------------------- | ---------------------------------- | ---------------- | ------ |
| 1 | 黄金模板 checklist 持续维护 | 02-architecture-design.md §10 更新 | 覆盖全部新模式 | 待执行 |
| 2 | 可观测性增强 | 日志注入 traceId + Outbox 积压告警 | Grafana 面板可用 | 待执行 |
---
## §4 依赖与就绪信号
- **我依赖**：
- MySQL classes_db（P1 已就绪）
- api-gateway 路由注册（P1 已就绪）
- P3：iam `BatchGetUsers` + `getEffectivePermissions`
- P3：Kafka 基础设施（ai08 启用）
- **我的就绪信号**：
- P1：REST API 5 端点 + /healthz + /readyz + /metrics 可用（已就绪）
- P3：gRPC 50053 + Outbox 事件发布 + Redis 缓存可用
- **交接信号**：P3 合并时，ai07 向 ai08 交接 classes 模块，交接清单见 02-architecture-design.md §11
---
## §5 交接计划（ai07 → ai08）
| 交接项 | 内容 | 时间 |
| ------------------ | ------------------------------------------------------- | --------- |
| 源码交接 | `services/classes/src/` 全部源码 | P3 启动时 |
| 文档交接 | `services/classes/docs/` 2 份设计文档 | P3 启动时 |
| proto 交接 | `classes.proto` 由 core-edu 实现承载 | P3 启动时 |
| 黄金模板保留 | `services/classes/` 保留作只读对照基准（待 coord 仲裁） | P3 合并后 |
| checklist 持续维护 | ai07 持续维护 02-architecture-design.md §10 | 跨阶段 |

45
docs/architecture/issues/worklines/content_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# content 工作排期
> 负责人：ai09
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/content_contract.md](../contracts/content_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
content 是内容服务，提供 TextbookService、ChapterService、KnowledgeGraphService、QuestionService，结合 Neo4j 知识图谱与 Elasticsearch 全文检索。全阶段目标：P2 服务骨架+Neo4j+ES → P3 四大 Service 实现 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai09 content 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a9a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai09 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai09
- **交付物**：⚠️ 由 ai09 自行补充
- **依赖**：见 [contracts/content_contract.md](../contracts/content_contract.md)
- **验收标准**：⚠️ 由 ai09 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai09 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai09 自行补充

45
docs/architecture/issues/worklines/core-edu_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# core-edu 工作排期
> 负责人：ai08
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/core-edu_contract.md](../contracts/core-edu_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
core-edu 是教学核心服务，提供 ClassService、ExamService、HomeworkService、GradeService、AttendanceService，并基于 Outbox 模式发布领域事件。全阶段目标：P2 服务骨架+Outbox → P3 五大 Service 实现 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai08 core-edu 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a8a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai08 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai08
- **交付物**：⚠️ 由 ai08 自行补充
- **依赖**：见 [contracts/core-edu_contract.md](../contracts/core-edu_contract.md)
- **验收标准**：⚠️ 由 ai08 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai08 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai08 自行补充

45
docs/architecture/issues/worklines/data-ana_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# data-ana 工作排期
> 负责人：ai11
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/data-ana_contract.md](../contracts/data-ana_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
data-ana 是数据分析服务，提供 AnalyticsService（12 个 RPC），基于 ClickHouse 列存查询与 CDC 消费实现实时分析。全阶段目标：P2 ClickHouse 接入+CDC 消费 → P3 AnalyticsService 12 RPC → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai11 data-ana 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a11a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai11 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai11
- **交付物**：⚠️ 由 ai11 自行补充
- **依赖**：见 [contracts/data-ana_contract.md](../contracts/data-ana_contract.md)
- **验收标准**：⚠️ 由 ai11 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai11 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai11 自行补充

56
docs/architecture/issues/worklines/iam_workline.md Normal file
View File

@@ -0,0 +1,56 @@
# iam 工作排期
> 负责人：ai06
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/iam_contract.md](../contracts/iam_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
iam 是身份认证服务，全阶段目标：gRPC 50052 + 12 RPC + /readyz 深度 + iam_student_guardians + DataScope + 审计日志 + Outbox。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai06 iam 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2.1 核心
gRPC server 50052启用 :crit, a6a, 2026-07-10, 2d
12 RPC实现 :crit, a6b, after a6a, 4d
/readyz深度(5依赖) :a6c, after a6b, 1d
iam_student_guardians+DataScope :a6d, after a6b, 1d
section P2.2-P6 扩展
审计日志+Outbox :a6e, after a6d, 3d
持续补全 :a6f, after a6e, 5d
```
> **注意**：以上为 coord 初始规划，ai06 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### P2.1：gRPC + 12 RPC + /readyz + DataScope
- **负责人**：ai06
- **交付物**：
- gRPC server 50052 + 12 RPC（见 iam.proto）
- /readyz 5 项依赖检查
- iam_student_guardians 表 + DataScope=CHILDREN
- **依赖**：iam.proto（批次 0 已完成）
- **验收标准**：12 RPC 全部可用 + /readyz 返回 5 项状态
- **完整 P2.2-P6 任务**：⚠️ 由 ai06 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：无（iam 是基础服务）
- **我的就绪信号**：gRPC 50052 启用 + GetPublicKey RPC 可用 + HealthService.Check 返回 SERVING

45
docs/architecture/issues/worklines/msg_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# msg 工作排期
> 负责人：ai10
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/msg_contract.md](../contracts/msg_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
msg 是消息服务，提供 NotificationService、PreferenceService、TemplateService，并基于 Outbox 模式发布消息事件。全阶段目标：P2 服务骨架+Outbox → P3 三大 Service 实现 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai10 msg 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a10a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai10 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai10
- **交付物**：⚠️ 由 ai10 自行补充
- **依赖**：见 [contracts/msg_contract.md](../contracts/msg_contract.md)
- **验收标准**：⚠️ 由 ai10 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai10 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai10 自行补充

45
docs/architecture/issues/worklines/parent-bff_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# parent-bff 工作排期
> 负责人：ai05
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/parent-bff_contract.md](../contracts/parent-bff_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
parent-bff 为家长端提供 GraphQL 聚合 API，覆盖 Dashboard、多子女切换、成绩趋势等场景。全阶段目标：P2 GraphQL schema 骨架 → P3 Dashboard+多子女+成绩趋势 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai05 parent-bff 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a5a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai05 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai05
- **交付物**：⚠️ 由 ai05 自行补充
- **依赖**：见 [contracts/parent-bff_contract.md](../contracts/parent-bff_contract.md)
- **验收标准**：⚠️ 由 ai05 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai05 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai05 自行补充

45
docs/architecture/issues/worklines/parent-portal_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# parent-portal 工作排期
> 负责人：ai15
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/parent-portal_contract.md](../contracts/parent-portal_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
parent-portal 是家长端微前端，通过 MF Remote 接入主应用，覆盖 Dashboard、多子女切换等场景。全阶段目标：P2 MF Remote 骨架 → P3 Dashboard+多子女切换 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai15 parent-portal 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a15a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai15 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai15
- **交付物**：⚠️ 由 ai15 自行补充
- **依赖**：见 [contracts/parent-portal_contract.md](../contracts/parent-portal_contract.md)
- **验收标准**：⚠️ 由 ai15 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai15 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai15 自行补充

45
docs/architecture/issues/worklines/push-gateway_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# push-gateway 工作排期
> 负责人：ai02
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/push-gateway_contract.md](../contracts/push-gateway_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
push-gateway 负责长连接接入（HTTP /internal/* + WebSocket/SSE）与多设备会话管理，配合审计表实现消息推送可观测。全阶段目标：P2 HTTP+WS 接入 → P3 多设备会话 → P4-P6 审计与加固。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai02 push-gateway 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a2a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai02 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai02
- **交付物**：⚠️ 由 ai02 自行补充
- **依赖**：见 [contracts/push-gateway_contract.md](../contracts/push-gateway_contract.md)
- **验收标准**：⚠️ 由 ai02 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai02 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai02 自行补充

45
docs/architecture/issues/worklines/student-bff_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# student-bff 工作排期
> 负责人：ai04
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/student-bff_contract.md](../contracts/student-bff_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
student-bff 为学生端提供 GraphQL 聚合 API，覆盖 Dashboard、考试作答、作业提交等场景。全阶段目标：P2 GraphQL schema 骨架 → P3 Dashboard+考试+作业聚合 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai04 student-bff 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a4a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai04 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai04
- **交付物**：⚠️ 由 ai04 自行补充
- **依赖**：见 [contracts/student-bff_contract.md](../contracts/student-bff_contract.md)
- **验收标准**：⚠️ 由 ai04 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai04 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai04 自行补充

45
docs/architecture/issues/worklines/student-portal_workline.md Normal file
View File

@@ -0,0 +1,45 @@
# student-portal 工作排期
> 负责人：ai14
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/student-portal_contract.md](../contracts/student-portal_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
student-portal 是学生端微前端，通过 MF Remote 接入主应用，覆盖考试作答、作业提交等场景。全阶段目标：P2 MF Remote 骨架 → P3 考试作答+作业提交 → P4-P6 持续优化。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai14 student-portal 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2-P6
[阶段任务] :a14a, 2026-07-10, Xd
```
> **注意**：以上为 coord 初始规划，ai14 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### 全阶段任务
- **负责人**：ai14
- **交付物**：⚠️ 由 ai14 自行补充
- **依赖**：见 [contracts/student-portal_contract.md](../contracts/student-portal_contract.md)
- **验收标准**：⚠️ 由 ai14 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：⚠️ 由 ai14 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai14 自行补充

58
docs/architecture/issues/worklines/teacher-bff_workline.md Normal file
View File

@@ -0,0 +1,58 @@
# teacher-bff 工作排期
> 负责人：ai03
> 关联：[workline.md](../workline.md)、[coord.md §1 ARB-001](../coord.md)、[contracts/teacher-bff_contract.md](../contracts/teacher-bff_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
---
## §1 总览
teacher-bff 是教学场景域聚合层，全阶段目标：P2 GraphQL schema 第一版 → P3 扩展 exams/homework/grades → P4 学情分析 → P5 通知+SSE → P6 admin 命名空间。
---
## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
```mermaid
gantt
title ai03 teacher-bff 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2 GraphQL 基础
schema第一版(ARB-001) :crit, a3a, 2026-07-10, 2d
Yoga endpoint+5 Query Resolver :crit, a3b, after a3a, 3d
DataLoader+N+1防御 :a3c, after a3b, 1d
ActionState信封+降级模式B :a3d, after a3b, 1d
section P3-P6 扩展
exams/homework/grades Query :a3e, after a3d, 3d
学情分析+通知+SSE :a3f, after a3e, 4d
admin命名空间 :a3g, after a3f, 2d
```
> **注意**：以上为 coord 初始规划，ai03 接管后必须自行细化为完整 P2-P6 排期。
---
## §3 详细任务
### P2：GraphQL schema + 5 Query + DataLoader + ActionState
- **负责人**：ai03
- **交付物**：
- `packages/shared-ts/contracts/graphql/teacher-bff.graphql` — P2 schema
- Yoga endpoint `POST /graphql`
- 5 Query：dashboard / viewports / me / classes / class
- DataLoader + ActionState 信封 + 降级模式 B
- **依赖**：iam gRPC（ai06）+ coord 仲裁 ARB-001
- **验收标准**：5 Query 可用 + ActionState 信封 + depth ≤ 7
- **完整 P3-P6 任务**：⚠️ 由 ai03 自行补充
---
## §4 依赖与就绪信号
- **我依赖**：iam gRPC 50052（ai06）+ core-edu gRPC 50053（ai08，P3+）
- **我的就绪信号**：POST /graphql 可用 + dashboard Query 返回正确数据

170
docs/architecture/issues/worklines/teacher-portal_workline.md Normal file
View File

@@ -0,0 +1,170 @@
# teacher-portal 工作排期
> 负责人：ai13
> 关联：[workline.md](../workline.md)、[coord.md §2 ARB-002](../coord.md)、[contracts/teacher-portal_contract.md](../contracts/teacher-portal_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，开发期间用 mock，最后统一集成测试）
> 依据：president-final-rulings.md §3.5（ai13 P2 功能范围）+ §7.13（ai13 工作内容最终清单）+ 03-long-term-architecture.md §1.1 阶段能力累积矩阵
---
## §1 总览
teacher-portal 是教学场景域微前端（MF Shell），全阶段目标：P2 MF Shell + GraphQL client + 基础页面 → P3 考试/作业/成绩 → P4 知识图谱/学情 → P5 推送/AI → P6 可观测性硬化。
**全并行模式**：ai13 一口气完成 P2-P6 全部代码，开发期间用 MSW mock 上游（teacher-bff GraphQL / api-gateway HTTP / push-gateway WebSocket），上游就绪后在 [matrix.md](../matrix.md) §8 更新就绪信号，最后统一集成测试。
---
## §2 全阶段甘特图（P2-P6）
```mermaid
gantt
title ai13 teacher-portal 全阶段排期（全并行）
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2 基础
packages骨架(ui-tokens/ui-components/hooks) :crit, a13p0, 2026-07-09, 1d
MF Shell配置(NextFederationPlugin) :crit, a13a, after a13p0, 2d
GraphQLProvider+urql client单例 :crit, a13b, after a13a, 2d
AppShell+路由骨架+设计令牌三层 :a13c, after a13b, 2d
登录页+权限上下文+Token存储 :a13d, after a13c, 2d
Dashboard框架+班级列表+学生列表+个人设置 :a13e, after a13d, 3d
section P3 教学核心
考试管理页面(列表/创建/详情) :a13f, after a13e, 3d
作业管理页面(布置/批改) :a13g, after a13f, 3d
成绩管理页面(录入/分析) :a13h, after a13g, 2d
乐观更新+多Tab会话同步 :a13i, after a13h, 2d
section P4 知识与学情
知识图谱可视化页面 :a13j, after a13i, 3d
学情分析仪表盘(宽表5s) :a13k, after a13j, 3d
parent-portal Remote接入 :a13l, after a13k, 1d
section P5 推送与AI
WebSocket通知中心 :a13m, after a13l, 2d
AI辅助出题(SSE流式) :a13n, after a13m, 3d
AI生成教案/学情报告 :a13o, after a13n, 2d
section P6 硬化
Sentry+RUM+OTel browser :a13p, after a13o, 2d
A11y审计(WCAG 2.2 AA) :a13q, after a13p, 2d
性能优化+bundle门禁 :a13r, after a13q, 2d
localStorage→httpOnly Cookie迁移 :a13s, after a13r, 1d
```
---
## §3 详细任务
### P2：MF Shell + GraphQL client + 基础页面
- **负责人**：ai13
- **裁决依据**：总裁裁决 §3.5（ai13 P2 功能范围）+ F9（GraphQL P2 起）+ F12（localStorage token）+ §2.17（MF GraphQL client 单例方案 A）+ §2.18（packages 批次 0.15）
- **交付物**：
- ✅ packages 骨架（ui-tokens/ui-components/hooks，批次 0.15 已完成）
- NextFederationPlugin 配置（exposes AppShell + shared react/urql/graphql singleton，无 remotes）
- GraphQLProvider + urql client 单例（Shell 暴露，Remote 复用，§2.17 方案 A）
- AppShell（Layout + 侧边栏 + 路由守卫 + ErrorBoundary + 设计令牌三层 primitive/semantic/tailwind-theme）
- 登录页（POST /api/auth/login → JWT 存 localStorage，F12）
- 权限上下文（usePermission + useViewports，权限点 `<RESOURCE>_<ACTION>` F7）
- Dashboard 框架（teacherDashboard GraphQL query）
- 班级列表页（myClasses GraphQL query，iam 数据）
- 学生列表页（classStudents GraphQL query，iam 数据）
- 个人设置页（currentUser + updateUser GraphQL query/mutation）
- **依赖**：teacher-bff GraphQL schema 第一版（ai03 + coord 仲裁 ISSUE-037）+ api-gateway 路由（ai01）
- **Mock 策略**：MSW 拦截 POST /api/teacher/graphql + POST /api/auth/login（见 contract.md §4.2）
- **验收标准**：MF 配置不破坏单体 + GraphQL 拉取数据 + 登录→Dashboard→班级列表→学生列表链路通
### P3：考试/作业/成绩 + 乐观更新 + 多 Tab 同步
- **负责人**：ai13
- **交付物**：
- 考试管理页面（classExams list / createExam mutation / examDetail）
- 作业管理页面（classHomework list / assignHomework mutation / homeworkDetail / 批改界面）
- 成绩管理页面（studentGrades list / recordGrade mutation / 成绩分析图表）
- 乐观更新（useMutation onMutate 回滚 + invalidateQueries，见 03 §10.1）
- 多 Tab 会话同步（BroadcastChannel('edu-session')，见 03 §2.5）
- **依赖**：teacher-bff 扩展 core-edu gRPC 调用（ai03 P3，core-edu ai08 P3 启用 gRPC）
- **Mock 策略**：MSW 返回固定考试/作业/成绩数据
- **验收标准**：教师创建考试→学生（student-portal Remote）作答→教师批改全链路（mock）+ 乐观更新回滚正确 + 多 Tab 登出同步
### P4：知识图谱 + 学情分析 + parent-portal Remote
- **负责人**：ai13
- **交付物**：
- 知识图谱可视化页面（recharts/d3 节点图，CSR + @next/dynamic 懒加载）
- 学情分析仪表盘（宽表 5s 返回，ISR revalidate 60s + CSR 交互）
- parent-portal Remote 接入（MF remotes 配置，feature flag NEXT_PUBLIC_MF_ENABLED）
- **依赖**：teacher-bff 扩展 content/data-ana gRPC 调用（ai03 P4，content ai09 P4 / data-ana ai11 P4 启用 gRPC）+ parent-portal（ai15 P4）
- **Mock 策略**：MSW 返回固定知识图谱 + 学情宽表数据
- **验收标准**：教师查看知识图谱 + 学情宽表 5s 返回（mock）+ parent-portal Remote 在 Shell 内渲染
### P5：WebSocket 推送 + AI 辅助 + 通知中心
- **负责人**：ai13
- **交付物**：
- WebSocket 通知中心（ws://push-gateway:8081/ws，实时通知 + BroadcastChannel 跨 Tab）
- AI 辅助出题（SSE 流式，generateQuestion subscription）
- AI 生成教案/学情报告（generateLessonPlan / generateReport mutation）
- **依赖**：push-gateway WebSocket（ai02 P5）+ ai 服务 gRPC（ai12 P5 启用 gRPC）+ msg 服务（ai10 P5）
- **Mock 策略**：mock-socket 模拟 WS 推送 + MSW 返回固定 AI 响应（SSE 用 ReadableStream mock）
- **验收标准**：全校广播实时到达（mock）+ AI 流式出题（mock）+ 通知中心实时更新
### P6：可观测性硬化 + A11y + 性能 + Token 迁移
- **负责人**：ai13
- **交付物**：
- Sentry 错误追踪 + Session Replay（NEXT_PUBLIC_SENTRY_DSN + beforeSend PII 过滤）
- Web Vitals RUM（LCP/INP/CLS/TTFB → /api/v1/admin/web-vitals）
- OTel browser SDK（自动埋点 fetch/XHR/document load → OTLP collector）
- A11y 审计（WCAG 2.2 AA：eslint-plugin-jsx-a11y + @axe-core/playwright + 对比度审计）
- 性能优化（bundle analyzer + size-limit CI 门禁：Shell <150KB / Remote <80KB / CSS <50KB）
- localStorage → httpOnly Cookie 迁移（iam refresh cookie 端点就绪后 + CSRF 防护）
- **依赖**：全链路可观测就绪（iam refresh cookie + Sentry DSN + OTel collector）
- **验收标准**：99.9% 可用 + WCAG 2.2 AA + LCP <2.5s / INP <200ms / CLS <0.1（P75）
---
## §4 依赖与就绪信号
### §4.1 我依赖的上游就绪标志
| 上游 | 就绪标志 | 阻塞阶段 | 状态 |
| --------------------------------------------------------- | ------------------------------------------------- | -------- | ---------------------- |
| packages 骨架（ai13 自建） | ui-tokens/ui-components/hooks 可 import | P2 启动 | ✅ 已就绪（批次 0.15） |
| teacher-bff GraphQL schema（ai03 + coord 仲裁 ISSUE-037） | packages/shared-ts/contracts/graphql/ 第一版 | P2 启动 | ⏳ 待 coord 仲裁 |
| api-gateway HTTP :8080（ai01） | /api/teacher/graphql + /api/auth/login 路由可用 | P2 启动 | ⏳ 待 ai01 |
| teacher-bff core-edu 扩展（ai03 P3） | classExams/classHomework/studentGrades query 可用 | P3 启动 | ⏳ 待 ai03 P3 |
| teacher-bff content/data-ana 扩展（ai03 P4） | knowledgeGraph/studentAnalytics query 可用 | P4 启动 | ⏳ 待 ai03 P4 |
| push-gateway WebSocket :8081/ws（ai02 P5） | WS 连接可建立 + 推送可接收 | P5 启动 | ⏳ 待 ai02 P5 |
| ai 服务 gRPC（ai12 P5） | generateQuestion/generateLessonPlan 可调 | P5 启动 | ⏳ 待 ai12 P5 |
| iam refresh cookie 端点（ai06 P6） | POST /iam/auth/refresh 返回 httpOnly cookie | P6 启动 | ⏳ 待 ai06 P6 |
### §4.2 我的就绪信号（供下游消费）
| 信号 | 就绪标志 | 消费方 |
| ------------------------------- | -------------------------------------- | ---------------------------------- |
| teacher-portal dev server :4000 | next dev -p 4000 可访问 | 无（最前端） |
| MF Shell 可加载 | 首页渲染 AppShell + 导航 | student/parent/admin Remote（P3+） |
| 登录流程可用 | POST /api/auth/login → JWT → Dashboard | 无（最前端） |
| GraphQL 查询可执行 | currentUser/myClasses 返回数据 | 无（最前端） |
| parent-portal Remote 接入点 | MF remotes 配置就绪 | parent-portal（ai15 P4） |
---
## §5 全并行开发说明
按 [matrix.md](../matrix.md) §全并行模式：
1. ai13 一口气完成 P2-P6 全部代码，开发期间用 MSW mock 上游
2. 上游就绪后在 matrix.md §8 更新就绪信号
3. 所有模块就绪后统一集成测试（matrix.md §9 检查清单）
4. Mock 切换：NEXT_PUBLIC_API_MOCKING=enabled → disabled
---
**AI Agent**: ai13（teacher-portal）
**Branch**: feat/teacher-portal-workline-ai13
**Coordinator**: coord-ai

1240
docs/architecture/president-final-rulings.md Normal file
View File

File diff suppressed because it is too large Load Diff

6
docs/issues.md
View File

@@ -2205,7 +2205,11 @@
---
## 3.6 ai16 复审批次（2026-07-09）
> **ai16 复审批次记录已迁移**：见 [issues/objections/admin-portal_issue.md](./architecture/issues/objections/admin-portal_issue.md)（2026-07-09 设计文档重构，issues.md 已归档）
---
## 2.9 ai02 补充的待仲裁问题（ISSUE-053 ~ ISSUE-058）
**复审范围**：coord-final-decisions.md（前端 4 portal F1-F12 + 通用 G14/G16 + X2/X3/X6 待 P6+ 事项 + §7 各 AI 回写义务）+ ai-work-orchestration.md（批次 5 P6 ai16 工作范围）+ issues.md v1.5（含 ai16 新增 5 个问题 ISSUE-044~048）+ ai16 自身 `apps/admin-portal/docs/02-architecture-design.md`（§4.1 数据获取路径 / §6.1 权限表 27 路由 / §6.2 错误码清单 / §12.4 错误码前缀表 / §18 coord 仲裁清单 9 子项）

147
docs/superpowers/specs/2026-07-09-ai-collab-docs-restructure-design.md Normal file
View File

@@ -0,0 +1,147 @@
# AI 协作文档体系重构设计
> 日期：2026-07-09
> 状态：已批准，已实现
> 关联：[president-final-rulings.md](../../architecture/president-final-rulings.md)、[ai-work-orchestration.md](../../architecture/ai-work-orchestration.md)
---
## 1. 背景与问题
### 1.1 原始问题
Edu 项目有 16 个 AI 协作开发微服务架构。此前的协作文档存在两个核心问题：
1. **issues.md 单文件多 AI 写入冲突**：70+ 问题由多个 AI 追加到同一文件，导致编号严重冲突（ISSUE-024/025/028~~031/032~~036/044~048 多处重复），文件结构混乱（3 个 `## 2.` 标题，章节标题与 issue 标题合并）。
2. **coord 集中规划批次不符合全并行需求**：原模式按 6 批次串行推进（批次 0→1→2→...→5），各 AI 等待批次信号才能开始。用户决定改为**全并行模式**：各 AI 一口气完成自己模块从 P2 到 P6 的所有代码，开发期间用 mock，最后统一集成测试。
### 1.2 用户需求
- 模块问题和模块 workline 分子文件夹存放
- coord 的 coord.md 和 workline.md 位置不变（留根目录）
- workline 由各模块 AI 自己详细规划（不是 coord 规划）
- 需要一份上下游对接契约文档，支持全并行开发期间用 mock
---
## 2. 设计方案
### 2.1 目录结构
```
docs/architecture/issues/
├── coord.md # coord 仲裁汇总（不变）
├── workline.md # coord 总工作安排（不变）
├── matrix.md # 新增：上下游对接总矩阵
├── objections/ # 各模块问题/异议（AI 提请，coord 仲裁）
│ ├── [模块名]_issue.md # 15 个模块各一个
│ └── cross_issue.md # 跨模块问题
├── worklines/ # 各模块工作排期（AI 自己写，覆盖 P2-P6 全阶段）
│ └── [模块名]_workline.md # 15 个模块各一个
└── contracts/ # 各模块对接契约（我提供什么 + 我消费什么 + mock 策略）
└── [模块名]_contract.md # 15 个模块各一个
```
**命名冲突解决**：外层文件夹保持 `issues/`（coord.md/workline.md 位置不变），内层"模块问题"子文件夹改名为 `objections/`（语义更准确：AI 提请的异议），避免 `issues/issues/` 路径。
### 2.2 三类文档职责
| 文档类型 | 子文件夹 | 维护方 | 内容 |
| ---------------- | ------------- | ---------------------- | ---------------------------------------------- |
| issue（异议） | `objections/` | 各 AI 提请，coord 仲裁 | 遇到问题时追加条目，coord 仲裁后更新状态 |
| workline（排期） | `worklines/` | 各 AI 自己写 | 全阶段甘特图 + 详细任务 + 依赖与就绪信号 |
| contract（契约） | `contracts/` | 各 AI 维护，coord 汇总 | 我提供什么 + 我消费什么 + mock 策略 + 就绪信号 |
**coord 根目录文件**：
- `coord.md`：coord 仲裁结果汇总（各 AI 提请异议后，coord 在此写入仲裁结论）
- `workline.md`：coord 总工作安排（16 AI 甘特图 + 批次概览 + 各 AI 工作清单链接）
- `matrix.md`：coord 汇总的上下游对接总矩阵（服务依赖图 + gRPC/GraphQL/Kafka/HTTP 矩阵 + mock 策略 + 就绪信号跟踪）
### 2.3 全并行开发模式
**核心原则**：各 AI 一口气完成自己模块从 P2 到 P6 的所有代码，开发期间用 mock，最后统一集成测试。
**工作流**：
1. 各 AI 读取自己的 `contract.md` 了解上下游接口
2. 各 AI 在 `workline.md` 详细规划全阶段任务
3. 开发期间消费上游的 mock（见 contract.md §4 mock 策略）
4. 上游就绪后在 `matrix.md` §8 更新就绪信号
5. 所有模块就绪后统一集成测试（见 matrix.md §9 检查清单）
**Mock 策略**（见 matrix.md §7）：
- gRPC 调用：grpc-mock 拦截 + 固定 JSON
- GraphQL 调用：MSW 拦截 + 固定 response
- Kafka 事件：本地 Kafka mock producer
- HTTP 调用：MSW / fetch mock
### 2.4 contract.md 模板结构
```markdown
# [模块名] 对接契约
## §1 我提供什么（对外接口）
- 1.1 gRPC 接口（如有）
- 1.2 HTTP 端点（如有）
- 1.3 GraphQL schema（如 BFF）
- 1.4 Kafka 事件发布（如有）
- 1.5 错误码前缀
## §2 我消费什么（依赖上游）
- 2.1 gRPC 调用（同步）+ mock 策略
- 2.2 Kafka 事件订阅（异步）+ mock 策略
- 2.3 HTTP 调用（如有）+ mock 策略
## §3 就绪信号
- 3.1 我依赖的上游就绪标志
- 3.2 我的就绪标志（供下游消费）
## §4 Mock 策略
- 4.1 我提供的 mock
- 4.2 我消费的 mock
```
---
## 3. 实现清单
### 3.1 文件创建（共 48 个文件）
| 类型 | 数量 | 位置 |
| ----------- | -------------------------- | ----------- |
| contract.md | 15 | contracts/ |
| workline.md | 15（4 个已有 + 11 个新建） | worklines/ |
| issue.md | 16（15 模块 + 1 跨模块） | objections/ |
| matrix.md | 1 | 根目录 |
| **合计** | 47 + matrix.md = 48 | |
### 3.2 文件迁移
- 旧 `issues/[模块名]_workline.md`（4 个）→ 迁移到 `worklines/` 子文件夹，更新路径引用
- 旧文件删除
### 3.3 文档更新
- `coord.md` §3：更新仲裁流程指向 `objections/` 子文件夹
- `workline.md`：更新维护规则指向 `worklines/` 子文件夹 + 全并行模式说明
- `issues.md`（旧）：添加迁移说明指向新流程
- `ai-work-orchestration.md` §9.2：指向新流程
---
## 4. 验收标准
- [ ] `docs/architecture/issues/` 下有 3 个子文件夹（objections/ worklines/ contracts/）
- [ ] 每个子文件夹有 15-16 个 `.md` 文件
- [ ] `coord.md` 和 `workline.md` 在根目录
- [ ] `matrix.md` 在根目录
- [ ] 所有路径引用正确（`../coord.md` 而非 `./coord.md`）
- [ ] 旧 `issues/[模块名]_workline.md` 文件已删除
- [ ] `issues.md` 顶部有迁移说明