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