xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5c89def70416ffd70df5d0424403c88e51f7500b
Edu/docs/architecture/issues/worklines/student-bff_workline.md

18 KiB
Raw Blame History

student-bff 工作排期

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

§1 总览

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 全阶段甘特图（批次 1 等待期 + 批次 2-5）

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

    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

关键路径（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
  • 依赖：无（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 依赖与就绪信号

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）
Reference in New Issue View Git Blame Copy Permalink