# 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 拦截器实现，上游就绪后移除拦截器切换真实调用。