Merge worktree branch merge-15-modules-to-main-5ug5xJ

2026-07-10 15:28:20 +08:00
parent 60d7173545
commit df62ffc176
51 changed files with 11559 additions and 1908 deletions
--- a/docs/architecture/issues/worklines/student-bff_workline.md
+++ b/docs/architecture/issues/worklines/student-bff_workline.md
@@ -1,45 +1,362 @@
 # student-bff 工作排期

 > 负责人：ai04
-> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/student-bff_contract.md](../contracts/student-bff_contract.md)
-> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
+> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/student-bff_contract.md](../contracts/student-bff_contract.md)、[objections/student-bff_issue.md](../objections/student-bff_issue.md)
+> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，开发期间用 mock，最后统一集成测试）
+> 裁决依据：[coord-final-decisions.md](../../coord-final-decisions.md) §2 B1-B8、[president-final-rulings.md](../../president-final-rulings.md) §2.2/§3.4/§6.1

 ---

 ## §1 总览

-student-bff 为学生端提供 GraphQL 聚合 API，覆盖 Dashboard、考试作答、作业提交等场景。全阶段目标：P2 GraphQL schema 骨架 → P3 Dashboard+考试+作业聚合 → P4-P6 持续优化。
+student-bff 为学生端提供 **GraphQL 聚合 API**（B1 裁决：P2 起直接 GraphQL + DataLoader），下游通过 **gRPC** 调用业务服务（B2 裁决：首次实现即 gRPC），复用 teacher-bff 产出的 **DownstreamClient 抽象**（B8 裁决）。
+
+- **阶段归属**：P3 核心教学阶段（批次 2）
+- **端口**：3009（HTTP GraphQL endpoint）
+- **路由前缀**：`/student`（api-gateway 代理 `/api/v1/student/*` → student-bff:3009）
+- **schema 存放**：`packages/shared-ts/contracts/graphql/student-bff.schema.graphql`（president §2.2）
+- **核心场景**：学生 Dashboard 聚合 + 考试作答 + 作业提交 + 成绩查看
+
+### 1.1 关键裁决对齐
+
+| 裁决 | 结论 | 对齐方式 |
+| ---- | ---- | -------- |
+| B1 API 风格 | P2 起直接 GraphQL（Yoga + DataLoader） | P3 首次实现即 GraphQL，禁止 REST |
+| B2 下游通信 | 首次实现即 gRPC | @grpc/grpc-js + @bufbuild/protobuf，禁止 HTTP fetch |
+| B3 权限装饰器 | BFF 豁免 @RequirePermission | 仅校验 x-user-id 存在，权限交下游 |
+| B4 越权防御 | 全部 BFF 强制 | AuthorizationGuard 强制 userId 比对 |
+| B5 错误码前缀 | BFF_STUDENT_ | 统一 BFF_ 前缀 |
+| B6 缓存策略 | Redis 5-30s 短缓存 | CacheInterceptor + Redis |
+| B7 Kafka 订阅 | P2-P4 不订阅，P5 后订阅 | P3/P4 纯同步聚合，P5 引入 EventSubscriber |
+| B8 DownstreamClient | 回写 teacher-bff，3 BFF 统一 | 复用 ai03 P2 产出的抽象 |

 ---

-## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
+## §2 全阶段甘特图（批次 1 等待期 + 批次 2-5）

 ```mermaid
 gantt
-    title ai04 student-bff 全阶段排期
+    title ai04 student-bff 全阶段排期（对齐总裁 §6.1 批次时间线）
    dateFormat YYYY-MM-DD
    axisFormat %m-%d

-    section P2-P6
-    [阶段任务] :a4a, 2026-07-10, Xd
+    section 批次1等待期
+    W0.1 GraphQL schema 第一版起草 :crit, w1, 2026-07-10, 3d
+    W0.2 01/02 文档回写(B1/B2/B5/B8) :crit, w2, after w1, 3d
+    W0.3 schema 提交 coord 仲裁 :milestone, w3, after w2, 0d
+
+    section 批次2 P3 核心
+    P3.1 NestJS+GraphQL Yoga 骨架 :crit, p1, after w3, 2d
+    P3.2 DownstreamClient+gRPC client(iam+core-edu) :crit, p2, after p1, 3d
+    P3.3 核心 Query Resolver(dashboard/homework/grades/exams) :crit, p3, after p2, 3d
+    P3.4 Mutation(submitHomework)+AuthorizationGuard(B4) :crit, p4, after p3, 2d
+    P3.5 DataLoader+N+1防御 :p5, after p4, 1d
+    P3.6 Redis缓存(B6)+ActionState信封 :p6, after p4, 1d
+    P3.7 /healthz+/readyz探针(iam+core-edu) :p7, after p6, 1d
+    P3.8 横切关注点(logger/metrics/tracer/error filter) :p8, after p6, 2d
+    P3.9 单元测试(覆盖率≥80%) :p9, after p8, 2d
+
+    section 批次3 P4 扩展
+    P4.1 content gRPC client(textbooks/chapters/questions) :p10, after p9, 3d
+    P4.2 data-ana gRPC client(weakness/trend) :p11, after p10, 2d
+    P4.3 Query 扩展(myTextbooks/myWeakness/myTrend) :p12, after p11, 2d
+    P4.4 /readyz 扩展探针(content+data-ana) :p13, after p12, 1d
+    P4.5 Dashboard Resolver 字段扩展 :p14, after p12, 1d
+
+    section 批次4 P5 扩展
+    P5.1 msg gRPC client(notifications) :p15, after p14, 2d
+    P5.2 ai gRPC client(chat/streamChat SSE) :p16, after p15, 3d
+    P5.3 Query/Mutation 扩展(myNotifications/markAsRead/aiChat) :p17, after p16, 2d
+    P5.4 Kafka EventSubscriber(B7 P5订阅) :p18, after p17, 2d
+    P5.5 push-gateway 推送通道 :p19, after p18, 2d
+    P5.6 /readyz 扩展探针(msg+ai) :p20, after p19, 1d
+
+    section 批次5 P6 硬化
+    P6.1 熔断器(opossum)完善 :p21, after p20, 2d
+    P6.2 HPA+全链路可观测 :p22, after p21, 2d
+    P6.3 灾备演练+99.9%可用性 :p23, after p22, 3d
 ```

-> **注意**：以上为 coord 初始规划，ai04 接管后必须自行细化为完整 P2-P6 排期。
+> **关键路径**（crit）：schema 起草 → 文档回写 → P3 骨架 → gRPC client → Query Resolver → Mutation+Guard
+> **总时间线**：批次 1 等待期 6 天 + 批次 2 P3 约 17 天 + 批次 3 P4 约 9 天 + 批次 4 P5 约 12 天 + 批次 5 P6 约 7 天

 ---

 ## §3 详细任务

-### 全阶段任务
+### 3.1 批次 1 等待期（2026-07-10 起，约 6 天）
+
+#### W0.1 GraphQL schema 第一版起草

 - **负责人**：ai04
- **交付物**：⚠️ 由 ai04 自行补充
- **依赖**：见 [contracts/student-bff_contract.md](../contracts/student-bff_contract.md)
- **验收标准**：⚠️ 由 ai04 自行补充
+- **依赖**：无（president §2.2 裁决 ai04 在批次 1 等待期起草）
+- **交付物**：
+  - `packages/shared-ts/contracts/graphql/student-bff.schema.graphql` 第一版
+  - 包含 Query/Mutation 清单 + 类型定义 + 权限点标注（`# @permission:`）+ DataScope 标注（`# @dataScope: SELF`）
+  - 分页采用 Relay Cursor Connections 规范（president §2.2 #5）
+  - 错误格式：GraphQL errors 数组 + `extensions.code` + `extensions.traceId`（president §2.2 #3）
+- **验收标准**：
+  - P3 核心 Query：studentDashboard / myHomework / myGrades / myExams / myClasses / currentUser
+  - P3 核心 Mutation：submitHomework
+  - 提交 coord 仲裁（president §2.2：coord 在批次 2 启动前仲裁第一版）
+- **状态**：⏳ 待办（见 objections ISSUE-STU-004）
+
+#### W0.2 01/02 文档回写
+
+- **负责人**：ai04
+- **依赖**：无
+- **交付物**：
+  - `services/student-bff/docs/01-understanding.md` 回写（ISSUE-STU-001）：
+    - §3.2 REST 端点 → GraphQL Query/Mutation 清单
+    - §3.1/§4 HTTP fetch → gRPC 下游调用
+    - §3.3/§6 错误码 `STUDENT_BFF_` → `BFF_STUDENT_`
+    - §7.2 删除已裁决的"待仲裁"项
+  - `services/student-bff/docs/02-architecture-design.md` 回写（ISSUE-028-ai04）：
+    - §4 21 个 REST 端点 → GraphQL Schema 设计
+    - §9.2 删除 REST→GraphQL 演进，改为 GraphQL 即起点
+    - §9.3 删除 HTTP→gRPC 演进，改为 gRPC 首次实现即用
+    - §8.3 删除 8 项已裁决的"待仲裁"标注（ISSUE-STU-003）
+    - 修正 §11.4/§11.5 错误引用（ISSUE-STU-002）
+    - 补充 GraphQL Schema / DataLoader / gRPC client / AuthorizationGuard 设计
+- **验收标准**：与 coord-final-decisions §2 B1-B8 + president §2.2 完全一致
+- **状态**：⏳ 待办
+
+### 3.2 批次 2 P3 核心教学（约 17 天）
+
+#### P3.1 NestJS + GraphQL Yoga 骨架
+
+- **负责人**：ai04
+- **依赖**：批次 1 完成（iam gRPC 50052 + ai03 DownstreamClient 抽象就绪，president §6.1）
+- **交付物**：
+  - `services/student-bff/` 服务骨架（克隆 teacher-bff 结构，B8 复用 shared/）
+  - `src/app.module.ts` + `src/main.ts`（端口 3009）
+  - GraphQL Yoga endpoint（`POST /graphql`）+ Playground（开发环境）
+  - `package.json`（@edu/student-bff）+ `tsconfig.json`（NodeNext ESM）+ `nest-cli.json`
+  - `Dockerfile`（多阶段构建，EXPOSE 3009）
+- **验收标准**：`POST /graphql` 返回 200 + schema 内省可用
+- **状态**：⏳ 待办
+
+#### P3.2 DownstreamClient + gRPC client（iam + core-edu）
+
+- **负责人**：ai04
+- **依赖**：P3.1 + ai03 teacher-bff P2 产出的 DownstreamClient 抽象（B8）
+- **交付物**：
+  - `src/shared/downstream/downstream-client.ts`（复用 teacher-bff 抽象，B8）
+  - gRPC client 配置：iam:50052 + core-edu:50053
+  - `src/config/env.ts`：IamGrpcUrl + CoreEduGrpcUrl + 超时/重试参数
+  - gRPC interceptor：traceId 透传 + 错误归一化
+- **验收标准**：可调用 iam.GetUserInfo + core-edu.HomeworkService.ListHomeworkByClass
+- **状态**：⏳ 待办
+
+#### P3.3 核心 Query Resolver
+
+- **负责人**：ai04
+- **依赖**：P3.2 + coord 仲裁的 schema 第一版
+- **交付物**：
+  - `src/student/resolvers/dashboard.resolver.ts`：studentDashboard（聚合 iam + core-edu）
+  - `src/student/resolvers/homework.resolver.ts`：myHomework（core-edu）
+  - `src/student/resolvers/grades.resolver.ts`：myGrades（core-edu，B4 强制 userId 比对）
+  - `src/student/resolvers/exams.resolver.ts`：myExams（core-edu）
+  - `src/student/resolvers/classes.resolver.ts`：myClasses（core-edu）
+  - `src/student/resolvers/auth.resolver.ts`：currentUser（聚合 iam.GetUserInfo + GetEffectivePermissions + GetViewports）
+  - 并行编排：Promise.allSettled + 部分降级（president §2.6 方案 B：data 内 degraded 字段）
+- **验收标准**：5 个核心 Query 可执行，返回 ActionState 信封
+- **状态**：⏳ 待办
+
+#### P3.4 Mutation（submitHomework）+ AuthorizationGuard（B4）
+
+- **负责人**：ai04
+- **依赖**：P3.3
+- **交付物**：
+  - `src/student/resolvers/homework.mutation.resolver.ts`：submitHomework Mutation
+  - `src/student/guards/authorization.guard.ts`：B4 自我越权防御
+    - 接口：`canAccessOwnData(userId, requestedStudentId): Promise<boolean>`
+    - P3 实现：强制 `studentId === userId`（学生只能操作自己数据）
+    - 参照 teacher-bff ISSUE-033-ai03 的 AuthorizationGuard 模式（president §2.9）
+  - Zod 输入校验：SubmitHomeworkInput schema
+- **验收标准**：submitHomework 可提交；越权请求（studentId ≠ userId）返回 BFF_STUDENT_FORBIDDEN
+- **状态**：⏳ 待办
+
+#### P3.5 DataLoader + N+1 防御
+
+- **负责人**：ai04
+- **依赖**：P3.3
+- **交付物**：
+  - `src/student/dataloaders/homework.loader.ts`：批量加载作业
+  - `src/student/dataloaders/grades.loader.ts`：批量加载成绩
+  - Dashboard 内多学生场景用 DataLoader 批量去重（004 §11.3）
+- **验收标准**：N+1 查询场景下下游 gRPC 调用数 ≤ 2
+- **状态**：⏳ 待办
+
+#### P3.6 Redis 缓存（B6）+ ActionState 信封
+
+- **负责人**：ai04
+- **依赖**：P3.3
+- **交付物**：
+  - `src/shared/cache/cache.module.ts`：Redis CacheInterceptor
+  - 缓存 Key 规范：`student:dashboard:{userId}` 等（TTL 5-30s，B6）
+  - ActionState 信封：`{success, data, meta?}` / `{success: false, error: {code, message, details?, traceId?}}`
+  - 降级模式：`data.degraded = true` + `data.degradedReason`（president §2.6 方案 B）
+- **验收标准**：缓存命中时 P50 < 100ms；降级响应符合方案 B
+- **状态**：⏳ 待办
+
+#### P3.7 /healthz + /readyz 探针
+
+- **负责人**：ai04
+- **依赖**：P3.2
+- **交付物**：
+  - `src/shared/health/health.controller.ts`：/healthz（liveness）+ /readyz（readiness）
+  - P3 /readyz 探针：iam gRPC 50052 + core-edu gRPC 50053（2 项，president §2.4）
+  - 必需依赖失败返回 503；可选依赖软失败返回 200 + degraded
+- **验收标准**：/readyz 返回 2 项探针状态
+- **状态**：⏳ 待办
+
+#### P3.8 横切关注点
+
+- **负责人**：ai04
+- **依赖**：P3.1
+- **交付物**：
+  - `src/shared/observability/logger.ts`（pino，service: 'student-bff'）
+  - `src/shared/observability/metrics.ts`（prom-client，11 个 student_bff_* 指标）
+  - `src/shared/observability/tracer.ts`（OTel，serviceName: 'student-bff'）
+  - `src/shared/errors/global-error.filter.ts`（@Catch()，BFF_STUDENT_* 错误码）
+  - `src/shared/errors/application-error.ts`（错误类层次）
+  - 优雅关闭：SIGTERM → app.close() → shutdownTracer()
+- **验收标准**：/metrics 可访问；GlobalErrorFilter 捕获所有异常
+- **状态**：⏳ 待办
+
+#### P3.9 单元测试
+
+- **负责人**：ai04
+- **依赖**：P3.3-P3.8
+- **交付物**：
+  - `test/unit/resolvers/*.test.ts`：Resolver 聚合逻辑（mock gRPC 下游）
+  - `test/unit/guards/*.test.ts`：AuthorizationGuard 越权防御
+  - `test/unit/dataloaders/*.test.ts`：DataLoader 批量逻辑
+  - `vitest.config.ts`（对齐 classes 测试框架）
+- **验收标准**：覆盖率 ≥ 80%
+- **状态**：⏳ 待办
+
+### 3.3 批次 3 P4 内容分析扩展（约 9 天）
+
+#### P4.1-P4.2 content + data-ana gRPC client
+
+- **负责人**：ai04
+- **依赖**：批次 3 启动（content gRPC 50054 + data-ana gRPC 50055 就绪）
+- **交付物**：
+  - content gRPC client：TextbookService + ChapterService + QuestionService + KnowledgeGraphService
+  - data-ana gRPC client：AnalyticsService.GetStudentWeakness + GetLearningTrend
+- **验收标准**：可调用 content + data-ana gRPC RPC
+- **状态**：⏳ 待办（属"跨阶段扩展例外"，president §2.3 允许新增下游 gRPC 调用）
+
+#### P4.3-P4.5 Query 扩展 + 探针扩展 + Dashboard 字段扩展
+
+- **交付物**：
+  - Query 扩展：myTextbooks / myChapters / myQuestions / myLearningPath / myWeakness / myTrend
+  - /readyz 扩展探针：+ content 50054 + data-ana 50055（共 4 项）
+  - Dashboard Resolver 字段扩展：null 字段 → 真实 data-ana 数据（president §2.3 #4 允许）
+- **状态**：⏳ 待办
+
+### 3.4 批次 4 P5 沟通 AI 扩展（约 12 天）
+
+#### P5.1-P5.3 msg + ai gRPC client + Query/Mutation 扩展
+
+- **交付物**：
+  - msg gRPC client：NotificationService.ListNotifications + MarkAsRead
+  - ai gRPC client：AiService.Chat + StreamChat（SSE 流式透传）
+  - Query/Mutation 扩展：myNotifications / markAsRead Mutation / aiChat / aiStreamChat
+- **状态**：⏳ 待办
+
+#### P5.4-P5.6 Kafka EventSubscriber + push-gateway + 探针扩展
+
+- **交付物**：
+  - `src/student/events/event-subscriber.ts`：Kafka 消费者组（B7 P5 才订阅）
+  - 订阅 topic：edu.homework.events / edu.exam.events / edu.grade.events / edu.identity.user.role_changed
+  - 幂等性：Redis SETNX event_id 去重
+  - push-gateway 推送通道：POST /push/user/:userId
+  - /readyz 扩展探针：+ msg 50056 + ai 50058（共 6 项）
+- **状态**：⏳ 待办
+
+### 3.5 批次 5 P6 硬化（约 7 天）
+
+#### P6.1-P6.3 熔断器 + HPA + 灾备
+
+- **交付物**：
+  - 熔断器（opossum）完善：每个下游 gRPC client 独立熔断器
+  - HPA 自动扩缩容配置
+  - 全链路 trace + Grafana 仪表盘
+  - 灾备演练 + 99.9% 可用性压测
+- **状态**：⏳ 待办

 ---

 ## §4 依赖与就绪信号

- **我依赖**：⚠️ 由 ai04 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai04 自行补充
+### 4.1 我依赖的上游就绪标志
+
+| 依赖项 | 提供 AI | 就绪信号 | 阻塞阶段 | 状态 |
+| ------ | ------- | -------- | -------- | ---- |
+| core_edu.proto 补全（AttendanceService / GetClassesByTeacher） | coord（president §2.5） | proto message + RPC 签名定义 | 批次 2 P3 | ⏳ |
+| buf.gen.yaml gRPC 插件 | coord（批次 0.9） | grpc/node 插件配置 | 批次 2 P3 | ⏳ |
+| ai03 DownstreamClient 抽象 | ai03（B8 裁决） | teacher-bff P2 产出可复用抽象 | 批次 2 P3 | ⏳ |
+| iam gRPC 50052 + 12 RPC | ai06（I1 裁决） | HealthService.Check = SERVING | 批次 2 P3 | ⏳ |
+| core-edu gRPC 50053 + 22 RPC | ai08（C2 裁决） | HealthService.Check = SERVING | 批次 2 P3 | ⏳ |
+| content gRPC 50054 + 18 RPC | ai09 | HealthService.Check = SERVING | 批次 3 P4 | ⏳ |
+| data-ana gRPC 50055 + 12 RPC | ai11 | HealthService.Check = SERVING | 批次 3 P4 | ⏳ |
+| msg gRPC 50056 + 13 RPC | ai10 | HealthService.Check = SERVING | 批次 4 P5 | ⏳ |
+| ai gRPC 50058 + 6 RPC | ai12 | HealthService.Check = SERVING | 批次 4 P5 | ⏳ |
+| coord 仲裁 student-bff schema 第一版 | coord（president §2.2） | schema 第一版裁定 | 批次 2 P3 | ⏳ |
+| api-gateway `/student` 路由 | ai01 | /api/v1/student/* 可代理 | 批次 2 P3 | ⏳ |
+
+### 4.2 我的就绪标志（供下游消费）
+
+| 就绪标志 | 验证方式 | 消费方 |
+| -------- | -------- | ------ |
+| student-bff GraphQL :3009 启用 | GET /healthz 返回 200 | k8s / 监控 |
+| /readyz 返回 200（含下游 gRPC 连通性） | GET /readyz 返回 200 + checks | k8s / 监控 |
+| GraphQL schema 可内省 | POST /graphql 返回 schema | ai14（student-portal） |
+| 核心 Query 可执行 | studentDashboard / myHomework / myGrades / myClasses / currentUser | ai14 |
+| 核心 Mutation 可执行 | submitHomework | ai14 |
+| /metrics 可访问 | GET /metrics 返回 prometheus 格式 | Prometheus |
+
+---
+
+## §5 Mock 策略（全并行开发期间）
+
+### 5.1 我提供的 mock（供 ai14 student-portal）
+
+在 student-bff 真实就绪前，为 ai14 提供 GraphQL mock：
+
+- **方式**：MSW 拦截 POST /graphql + 固定 response
+- **mock 数据**：
+  - currentUser 返回固定学生（id="student-001", name="李同学", roles=["student"]）
+  - studentDashboard 返回固定仪表盘（pendingHomework=3, upcomingExams=2, unreadNotifications=5）
+  - myHomework 返回固定 3 个作业（1 个待提交）
+  - myGrades 返回固定 5 个成绩
+  - myExams 返回固定 2 个考试
+  - myClasses 返回固定 1 个班级
+
+### 5.2 我消费的 mock（上游未就绪前）
+
+| 上游 | mock 方式 | 切换真实时机 |
+| ---- | --------- | ------------ |
+| iam gRPC | grpc-mock 拦截 + 固定 UserInfo/Permissions/Viewports | iam 就绪信号 ✅ |
+| core-edu gRPC | grpc-mock 拦截 + 固定 Homework/Exam/Grade/Class | core-edu 就绪信号 ✅ |
+| content gRPC | grpc-mock 拦截 + 固定 Textbook/Chapter/Question | content 就绪信号 ✅ |
+| data-ana gRPC | grpc-mock 拦截 + 固定 Weakness/Trend | data-ana 就绪信号 ✅ |
+| msg gRPC | grpc-mock 拦截 + 固定 Notification | msg 就绪信号 ✅ |
+| ai gRPC | grpc-mock 拦截 + 固定 Chat response | ai 就绪信号 ✅ |
+
+> 所有上游 mock 通过 gRPC client 拦截器实现，上游就绪后移除拦截器切换真实调用（对齐 matrix.md §7 全并行 Mock 策略）。
+
+---
+
+## §6 风险与缓解
+
+| 风险 | 概率 | 影响 | 缓解措施 |
+| ---- | ---- | ---- | -------- |
+| schema 仲裁延迟阻塞 P3 启动 | 中 | 高 | ai04 批次 1 等待期优先产出 schema 草案（W0.1） |
+| ai03 DownstreamClient 抽象未就绪 | 中 | 高 | ISSUE-007 已识别，coord 验收批次 1 时检查 |
+| core_edu.proto 补全延迟 | 低 | 高 | president §2.5 已明确 coord 负责 proto 定义 |
+| GraphQL + gRPC 首次实现复杂度高 | 中 | 中 | 复用 teacher-bff P2 模式（B8 DownstreamClient + Yoga endpoint） |
+| 下游 gRPC mock 与真实行为不一致 | 中 | 低 | 集成测试阶段统一验证（matrix.md §9） |