16 KiB
16 KiB
teacher-bff 工作排期
负责人：ai03 关联：workline.md、coord.md §1 ARB-001、contracts/teacher-bff_contract.md、president-final-rulings.md §3.1/§7.3、coord-final-decisions.md §2 B1-B8 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试） 裁决依据：B1 P2 即 GraphQL / B2 首次实现即 gRPC / B3 豁免 @RequirePermission / B4 越权防御 / B5 BFF_TEACHER_ 前缀 / B6 Redis 短缓存 / B7 P2-P4 不订阅 Kafka / B8 DownstreamClient 抽象
§1 总览
teacher-bff 是教学场景域聚合层（BFF），全阶段目标：
| 阶段 | 核心交付 | 裁决依据 |
|---|---|---|
| P2 | GraphQL schema 第一版（5 Query + admin 预留）+ DownstreamClient 抽象 + iam gRPC + AuthorizationGuard + ActionState 信封 | B1/B2/B3/B4/B5/B8 + ARB-001 + §3.1 |
| P3 | core-edu gRPC 扩展（exams/homework/grades Query + Mutation）+ AuthorizationGuard 接入 core-edu + Redis 聚合缓存 | §2.3 跨阶段扩展例外 |
| P4 | content + data-ana gRPC 扩展（学情分析 Query）+ DataLoader 全量接入 | §2.3 + §2.8 |
| P5 | ai + msg gRPC 扩展（SSE 流式 + notifications Query）+ Kafka consumer（push-gateway 落地后） | B7 |
| P6 | admin 命名空间实现 + 硬化（熔断/重试/超时/HPA/mTLS） | §5.1 + P6 硬化 |
§2 全阶段甘特图（P2-P6）
gantt
title ai03 teacher-bff 全阶段排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section P2 GraphQL 基础（8d）
schema第一版+admin预留(ARB-001) :crit, a3a, 2026-07-10, 2d
Yoga endpoint+5 Query Resolver :crit, a3b, after a3a, 3d
DownstreamClient+iam gRPC :crit, a3c, after a3a, 2d
AuthorizationGuard越权防御(B4) :crit, a3d, after a3b, 1d
ActionState信封+降级模式B :a3e, after a3b, 1d
/readyz探针注册表+iam探针 :a3f, after a3d, 1d
错误码迁移BFF_TEACHER_+回写02 :a3g, after a3e, 1d
section P3 core-edu 扩展（5d）
CoreEduClient gRPC(exams/homework/grades) :crit, a3h, after a3g, 2d
Mutation(createExam/assignHomework/recordGrade) :a3i, after a3h, 1d
AuthorizationGuard接入core-edu+Redis缓存 :a3j, after a3h, 1d
/readyz+core-edu探针 :a3k, after a3j, 1d
section P4 content+data-ana 扩展（4d）
ContentClient+DataAnaClient gRPC :a3l, after a3k, 2d
学情分析Query+DataLoader全量 :a3m, after a3l, 1d
/readyz+content+data-ana探针 :a3n, after a3m, 1d
section P5 ai+msg 扩展（8d）
AiClient+MsgClient gRPC :a3o, after a3n, 2d
SSE流式透传+notifications Query :a3p, after a3o, 2d
Kafka consumer(push-gateway落地后) :a3q, after a3p, 2d
/readyz+ai+msg探针 :a3r, after a3q, 1d
Should Have补全(OTel/metrics/DataLoader/Redis) :a3s, after a3r, 1d
section P6 admin+硬化（3d）
admin命名空间实现 :a3t, after a3s, 1d
熔断/重试/超时 :a3u, after a3t, 1d
Nice to Have补全(Zod全量/优雅关闭) :a3v, after a3u, 1d
总工期：28d（P2 8d + P3 5d + P4 4d + P5 8d + P6 3d），与 workline.md §1 总时间线对齐（批次1 8d + 批次2 5d + 批次4 8d + P4/P6 合并 7d）。
§3 详细任务
P2：GraphQL 基础 + DownstreamClient + 越权防御（批次 1，8d）
裁决依据：president §3.1 Must Have 13 项（teacher-bff 无 DB，G10/G11 不适用，实际 11 项 + DownstreamClient + admin 预留）
3.1 GraphQL schema 第一版 + admin 预留（2d，P0 阻塞 ai13）
- 负责人：ai03
- 依赖：coord 仲裁 ARB-001（已裁决）
- 交付物：
packages/shared-ts/contracts/graphql/teacher-bff.schema.graphql— P2 schema（5 Query: dashboard/viewports/me/classes/class + admin 命名空间占位）- admin 命名空间预留：schema 中声明
adminQuery/Mutation 类型骨架（无实际 Resolver），P6 实现
- 验收标准：5 Query SDL 定义完整 + admin 占位类型声明 + depth ≤ 7 + cost ≤ 1000
- 裁决引用：ARB-001 §1.2/§1.3 + president §5.1/§2.17
3.2 Yoga endpoint + 5 Query Resolver（3d，P0 阻塞 ai13）
- 负责人：ai03
- 依赖：3.1 schema + iam gRPC 50052（ai06 P2.1）
- 交付物：
POST /graphqlYoga GraphQL endpoint- 5 Query Resolver：dashboard / viewports / me / classes / class
- Dashboard Resolver P2 实现方式（ISSUE-032）：P2 仅调 iam gRPC，未启用字段返回 null +
extensions.warning = "field_unavailable_in_p2"
- 验收标准：5 Query 可执行 + ActionState 信封 + 降级模式 B（success=true + error=null + data 内 degraded 字段）
- 裁决引用：B1 + ARB-001 §1.4 + president §2.6/§2.8
3.3 DownstreamClient 抽象 + iam gRPC（2d，P0 阻塞 ai04/ai05）
- 负责人：ai03
- 依赖：iam gRPC 50052（ai06 P2.1）
- 交付物：
src/clients/DownstreamClient 抽象层（B8：BFF 模式 v2 标准抽象，3 个 BFF 统一使用，回写 teacher-bff）- IamClient gRPC 实现：
@grpc/grpc-js+@bufbuild/protobuf，调 iam:50052 - gRPC interceptor：注入 trace context（traceparent）+ x-user-id metadata + metrics
- 验收标准：IamClient gRPC 调 iam GetUserInfo/GetViewports/GetEffectiveAccess 成功
- 裁决引用：B2（首次实现即 gRPC）+ B8（DownstreamClient 抽象）
3.4 AuthorizationGuard 越权防御（1d，P0）
- 负责人：ai03
- 依赖：3.2 Resolver
- 交付物：
src/middleware/authorization.guard.ts— AuthorizationGuard 接口（canAccessClass(userId, classId): Promise<boolean>）- P2 内部实现：DEV_MODE 放行 + 生产拒绝（保守策略）
- 错误码：
BFF_TEACHER_FORBIDDEN_RESOURCE（teacherId 与资源无归属）+BFF_TEACHER_IDENTITY_MISMATCH（JWT teacherId 与 body 不一致）
- 验收标准：Guard 接口定义 + DEV_MODE 放行 + 生产拒绝 + 2 个越权错误码
- 裁决引用：B4 + president §2.7（错误码语义）+ §2.9（越权防御 P2 实现）
3.5 ActionState 信封 + 降级模式 B（1d）
- 负责人：ai03
- 依赖：3.2 Resolver
- 交付物：GlobalErrorFilter + ActionState 信封（success/errors/data）+ 降级模式 B
- 验收标准：GraphQL errors 数组扩展 ActionState 字段，
extensions.code = BFF_TEACHER_* - 裁决引用：G8 + president §2.6
3.6 /readyz 探针注册表 + iam 探针（1d）
- 负责人：ai03
- 依赖：3.3 IamClient
- 交付物：
src/shared/health/readiness.probe.ts— DownstreamHealthCheck 注册表模式- P2 探针：Redis + iam gRPC 50052（teacher-bff 无 DB，2 项）
- 验收标准：/readyz 返回 2 项检查结果 + 必需依赖失败返回 503
- 裁决引用：G2 + president §2.4（探针按阶段扩展）
3.7 错误码迁移 + 回写 02 文档（1d）
- 负责人：ai03
- 依赖：3.2-3.6
- 交付物：
application-error.ts全量迁移TEACHER_BFF_*→BFF_TEACHER_*- 回写 02 文档：4 处
GetTeacherDashboardStats→GetTeacherDashboard（ISSUE-035）+ B1/B2/B4/B8 裁决对齐
- 验收标准：源码零
TEACHER_BFF_*+ 02 文档与裁决一致 - 裁决引用：B5 + G14 + president §3.4 回写义务
P2 横切项（贯穿 3.1-3.7）
| 项 | 状态 | 说明 |
|---|---|---|
| pino 结构化日志（G4） | ✅ 已具备 | logger.ts |
| /healthz liveness（G3） | ✅ 已具备 | health.controller.ts |
| GlobalErrorFilter（G8） | ✅ 已具备 | global-error.filter.ts |
| ESM import .js 后缀（G12） | ✅ 已具备 | 源码已用 .js |
| import type（G13） | ✅ 已具备 | 源码已用 import type |
| OTel tracer（G6） | ⚠️ Should Have | P2 可降级为 logger-only，P5 补全 |
| /metrics 业务指标（G5） | ⚠️ Should Have | P2 仅暴露 process metrics |
| DataLoader（B1） | ⚠️ Should Have | P2 可先用普通 resolver，P4 全量接入 |
| Redis 5-30s 短缓存（B6） | ⚠️ Should Have | P3 接入聚合缓存 |
| Zod 全量验证（G7） | ⚠️ Nice to Have | P2 先校验核心 Query，P6 全量 |
| 优雅关闭 SIGTERM（G9） | ⚠️ Nice to Have | P2 已有基础，P6 补全关闭顺序 |
P2 退出标准：POST /graphql 可用 + 5 Query Resolver + DownstreamClient + AuthorizationGuard + ActionState 信封 + /readyz 2 项探针 + 错误码 BFF_TEACHER_* + admin 命名空间预留。
P3：core-edu gRPC 扩展（批次 2，5d）
裁决依据：§2.3 跨阶段扩展例外（新增下游 gRPC 调用 + AuthorizationGuard 内部实现替换 + /readyz 探针扩展）
3.8 CoreEduClient gRPC（2d，P0）
- 负责人：ai03
- 依赖：core-edu gRPC 50053（ai08 P3）
- 交付物：
- CoreEduClient gRPC 实现：ExamService / HomeworkService / GradeService
- GraphQL Query 扩展：exams(classId) / homework(classId) / grades(examId)
- Dashboard Resolver 扩展：null 字段替换为 core-edu 真实数据
- 验收标准：3 个 Query 返回 core-edu 数据 + Dashboard null 字段消除
- 裁决引用：§2.3 跨阶段扩展例外 + §2.8 Dashboard Resolver 扩展
3.9 Mutation 透传（1d）
- 交付物：createExam / assignHomework / recordGrade Mutation（透传 core-edu gRPC）
- 验收标准：3 个 Mutation 可执行 + 返回 ActionState 信封
3.10 AuthorizationGuard 接入 core-edu + Redis 缓存（1d）
- 交付物：
- AuthorizationGuard 内部实现替换：DEV_MODE 放行 → 真实 gRPC 校验
- Redis 缓存：
GetClassesByTeacher结果缓存（key:authz:teacher:{teacherId}:classes，TTL 5min）
- 验收标准：生产环境越权防御生效 + Redis 缓存命中
- 裁决引用：president §2.9（P3 接入 core-edu 后替换 Guard 实现）
3.11 /readyz + core-edu 探针（1d）
- 交付物：/readyz 探针注册表扩展 core-edu gRPC 50053 探针（3 项：Redis + iam + core-edu）
- 验收标准：/readyz 返回 3 项检查结果
P3 退出标准：core-edu gRPC 3 Query + 3 Mutation + AuthorizationGuard 生产生效 + Redis 缓存 + /readyz 3 项探针。
P4：content + data-ana gRPC 扩展（4d）
裁决依据：§2.3 跨阶段扩展例外
3.12 ContentClient + DataAnaClient gRPC（2d）
- 依赖：content gRPC 50054（ai09 P4）+ data-ana gRPC 50055（ai11 P4）
- 交付物：
- ContentClient gRPC：KnowledgeGraphService（GetPrerequisites / GetLearningPath）
- DataAnaClient gRPC：AnalyticsService（GetClassPerformance / GetStudentWeakness / GetLearningTrend / GetTeacherDashboard）
- GraphQL Query 扩展：knowledgePath / classPerformance / studentWeakness / learningTrend / teacherDashboard
- 验收标准：5 个 Query 返回真实数据
3.13 DataLoader 全量接入（1d）
- 交付物：DataLoader 覆盖全部 N+1 风险点（UserLoader / ClassLoader / ExamLoader / HomeworkLoader / GradeLoader）
- 验收标准：DataLoader per-request 实例 + 批量化窗口 16ms
- 裁决引用：B1 Should Have → P4 全量接入
3.14 /readyz + content + data-ana 探针（1d）
- 交付物：/readyz 探针扩展 content + data-ana（5 项：Redis + iam + core-edu + content + data-ana）
P4 退出标准：content + data-ana gRPC + 5 Query + DataLoader 全量 + /readyz 5 项探针。
P5：ai + msg gRPC 扩展 + SSE + Kafka（批次 4，8d）
裁决依据：B7（P5 push-gateway 落地后再订阅 Kafka）
3.15 AiClient + MsgClient gRPC（2d）
- 依赖：ai gRPC 50057（ai12 P5）+ msg gRPC 50056（ai10 P5）
- 交付物：
- AiClient gRPC：AiService（Chat / StreamChat streaming / GenerateQuestion / OptimizeExpression）
- MsgClient gRPC：NotificationService（ListNotifications / SearchNotifications / MarkAsRead）
- GraphQL Query 扩展：notifications + Mutation：generateQuestion / markNotificationAsRead
3.16 SSE 流式透传（2d）
- 交付物：
GET /ai/chat/streamSSE 端点（ai.StreamChat gRPC stream → BFF → 前端 EventSource） - 验收标准：SSE 三层透传端到端通 + 背压处理 + 超时取消
- 裁决引用：02 文档 §10
3.17 Kafka consumer（2d，push-gateway 落地后）
- 交付物：
- Kafka consumer 订阅
edu.identity.user.role_changed/edu.identity.role.updated，精确失效 Redis 权限缓存 - 幂等性：基于 event_id 去重（Redis SETNX）
- Kafka consumer 订阅
- 验收标准：权限变更秒级缓存失效 + 幂等消费
- 裁决引用：B7（P5 push-gateway 落地后再订阅）
3.18 /readyz + ai + msg 探针 + Should Have 补全（2d）
- 交付物：
- /readyz 探针扩展 ai + msg（7 项：Redis + iam + core-edu + content + data-ana + ai + msg）
- Should Have 补全：OTel tracer 全链路 + /metrics 业务指标 + Redis 聚合缓存 5-30s
- 验收标准：/readyz 7 项 + OTel 全链路 trace + 缓存命中率 ≥ 60%
P5 退出标准：ai + msg gRPC + SSE 流式 + notifications Query + Kafka consumer + /readyz 7 项探针 + Should Have 补全。
P6：admin 命名空间 + 硬化（3d）
裁决依据：president §5.1（admin-portal 复用 teacher-bff）+ P6 硬化
3.19 admin 命名空间实现（1d）
- 依赖：admin-portal（ai16 P6）
- 交付物：
- admin schema 命名空间 Resolver 实现（P2 预留的占位类型填充实际 Resolver）
- admin Query/Mutation：用户管理 / 角色权限管理 / 学校设置 / 组织管理 / 审计日志查询
- 验收标准：admin namespace 可内省 + admin-portal 可消费
- 裁决引用：president §5.1（admin-portal 复用 teacher-bff GraphQL endpoint）
3.20 熔断 / 重试 / 超时（1d）
- 交付物：
- Circuit Breaker（opossum，per-downstream-service）
- Retry（gRPC interceptor，仅幂等 RPC，指数退避）
- Timeout（per-RPC 3s，聚合总超时 5s）
- 验收标准：熔断/重试/超时生效 + 降级策略覆盖
3.21 Nice to Have 补全（1d）
- 交付物：Zod 全量验证 + 优雅关闭顺序（HTTP→Redis→gRPC→Kafka→Tracer）+ 测试覆盖率 ≥ 80%
- 验收标准：Zod 全 Controller 覆盖 + SIGTERM 顺序关闭 + Vitest 覆盖率 ≥ 80%
P6 退出标准：admin namespace 实现 + 熔断/重试/超时 + Zod 全量 + 测试 ≥ 80% + SLO 99.9%。
§4 依赖与就绪信号
4.1 我依赖的上游就绪信号
| 上游 | 就绪信号 | 阶段 | 状态 |
|---|---|---|---|
| iam（ai06） | gRPC 50052 + 8 RPC（GetUserInfo/GetViewports/GetEffectivePermissions/GetEffectiveAccess/Logout/GetPublicKey/BatchGetUsers/GetChildrenByParent） | P2 | ⏳ |
| core-edu（ai08） | gRPC 50053 + ExamService/HomeworkService/GradeService | P3 | ⏳ |
| content（ai09） | gRPC 50054 + KnowledgeGraphService | P4 | ⏳ |
| data-ana（ai11） | gRPC 50055 + AnalyticsService（含 GetTeacherDashboard，ISSUE-027 补全） | P4 | ⏳ |
| ai（ai12） | gRPC 50057 + AiService（含 StreamChat） | P5 | ⏳ |
| msg（ai10） | gRPC 50056 + NotificationService | P5 | ⏳ |
| push-gateway（ai02） | /internal/push 落地（B7 Kafka 订阅前提） | P5 | ⏳ |
| admin-portal（ai16） | admin schema 需求确认 | P6 | ⏳ |
4.2 我的就绪信号（供下游消费）
| 阶段 | 就绪信号 | 消费方 |
|---|---|---|
| P2 | POST /graphql 可用 + 5 Query + admin 预留 | teacher-portal（ai13） |
| P2 | DownstreamClient 抽象（B8 回写） | student-bff（ai04）/ parent-bff（ai05） |
| P3 | exams/homework/grades Query + Mutation | teacher-portal（ai13） |
| P4 | 学情分析 Query + DataLoader | teacher-portal（ai13） |
| P5 | SSE 流式 + notifications Query | teacher-portal（ai13） |
| P6 | admin namespace 可用 | admin-portal（ai16） |
§5 跨阶段扩展例外验收清单
裁决依据：president §2.3（ISSUE-020）。每次跨阶段扩展时对照检查。
- 扩展时更新 02-architecture-design.md 下游调用矩阵
- 扩展时更新 packages/shared-ts/contracts/graphql/teacher-bff.schema.graphql
- 扩展时运行
pnpm run arch:scan更新 arch.db - 未修改已有 RPC 调用签名或返回类型
- 未删除已实现的 RPC 调用
- 未修改 GraphQL schema 已有字段类型（仅新增字段）
- 未修改 /readyz 已有探针检查项（仅新增）