# teacher-portal 对接契约

> 负责人：ai13
> 关联：[matrix.md](./matrix.md)

---

## §1 我提供什么（对外接口）

### 1.1 gRPC 接口（如有）

无。teacher-portal 是前端微前端 Shell。

### 1.2 HTTP 端点（如有）

| Method | Path           | 用途                          | 认证                     |
| ------ | -------------- | ----------------------------- | ------------------------ |
| GET    | /              | 教师门户首页（MF Shell 容器） | JWT 必需（前端路由守卫） |
| GET    | /classes/*     | 班级管理子应用                | JWT 必需                 |
| GET    | /exams/*       | 考试管理子应用                | JWT 必需                 |
| GET    | /homework/*    | 作业管理子应用                | JWT 必需                 |
| GET    | /grades/*      | 成绩管理子应用                | JWT 必需                 |
| GET    | /attendance/*  | 考勤管理子应用                | JWT 必需                 |
| GET    | /content/*     | 内容管理子应用                | JWT 必需                 |
| GET    | /dashboard     | 教师仪表盘                    | JWT 必需                 |
| GET    | /ai/*          | AI 助手子应用                 | JWT 必需                 |
| GET    | /notifications | 通知中心                      | JWT 必需                 |

### 1.3 GraphQL schema（如 BFF）

不适用。teacher-portal 消费 teacher-bff GraphQL，自身不提供 schema。

### 1.4 Kafka 事件发布（如有）

无。

### 1.5 错误码前缀

无（前端不定义错误码前缀，透传 BFF 错误码）。

### 1.6 微前端架构（补充）

| 角色                   | 说明                                                |
| ---------------------- | --------------------------------------------------- |
| MF Shell（AppShell）   | 教师门户是微前端宿主，加载其他子应用                |
| 暴露的 remote 模块     | AppShell（导航/布局/路由守卫）、shared 设计系统组件 |
| module federation 配置 | `apps/teacher-portal/module-federation.config.ts`   |

---

## §2 我消费什么（依赖上游）

### 2.1 gRPC 调用（同步）

无。前端不直接调 gRPC。

### 2.2 Kafka 事件订阅（异步）

无。前端不直接订阅 Kafka。

### 2.3 HTTP 调用（如有）

| 被调用方            | Method.Path                  | 用途                                          | mock 策略                                                         |
| ------------------- | ---------------------------- | --------------------------------------------- | ----------------------------------------------------------------- |
| api-gateway (ai01)  | POST /api/v1/teacher/graphql | 教师 GraphQL 查询（经网关代理到 teacher-bff，对齐 matrix.md §5） | api-gateway/teacher-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 |
| api-gateway (ai01)  | POST /api/auth/login         | 教师登录（非 GraphQL，认证前提，F12: JWT 存 localStorage） | api-gateway 就绪前使用 MSW 返回固定 JWT                           |
| push-gateway (ai02) | GET /ws                      | WebSocket 实时通知                            | push-gateway 就绪前使用 mock-socket 模拟 WS 推送                  |

### 2.4 GraphQL 查询域（经 api-gateway 代理到 teacher-bff）

| Query/Mutation                                     | 用途         | mock 策略              |
| -------------------------------------------------- | ------------ | ---------------------- |
| currentUser                                        | 当前教师信息 | MSW 返回固定教师       |
| myClasses                                          | 我的班级     | MSW 返回固定 3 个班级  |
| classStudents                                      | 班级学生名单 | MSW 返回固定 30 个学生 |
| classExams / createExam                            | 考试管理     | MSW 返回固定考试数据   |
| classHomework / assignHomework                     | 作业管理     | MSW 返回固定作业数据   |
| studentGrades / recordGrade                        | 成绩管理     | MSW 返回固定成绩数据   |
| classAttendance / recordAttendance                 | 考勤管理     | MSW 返回固定考勤数据   |
| textbooks / chapters / knowledgePoints / questions | 内容管理     | MSW 返回固定内容数据   |
| teacherDashboard                                   | 教师仪表盘   | MSW 返回固定仪表盘     |
| myNotifications / markAsRead                       | 通知中心     | MSW 返回固定通知       |
| aiChat / generateQuestion / generateLessonPlan     | AI 助手      | MSW 返回固定 AI 响应   |

---

## §3 就绪信号

### 3.1 我依赖的上游就绪标志

- [ ] api-gateway HTTP :8080 启用（ai01）—— 前端请求入口
- [ ] teacher-bff GraphQL :3003 启用（ai03）—— 数据来源
- [ ] push-gateway WebSocket :8081/ws 启用（ai02）—— 实时通知

### 3.2 我的就绪标志（供下游消费）

- [ ] teacher-portal dev server :4000 启用
- [ ] MF Shell 可加载（首页渲染 AppShell + 导航）
- [ ] 子应用路由可访问（/classes /exams /homework 等子页面渲染）
- [ ] 登录流程可用（POST /api/auth/login 获取 JWT 存入 localStorage，F12；P6 迁移 httpOnly cookie）
- [ ] GraphQL 查询可执行（dashboard / viewports / me / classes / class Query，ARB-001）
- [ ] WebSocket 通知可接收（push-gateway 推送 → 前端通知中心更新）

---

## §4 Mock 策略

### 4.1 我提供的 mock

teacher-portal 是最前端，无下游消费方。但对开发体验提供：

- **Storybook**：各组件独立 story，供设计审查
- **MSW handlers**：`apps/teacher-portal/src/mocks/handlers.ts`，拦截所有 GraphQL/HTTP 请求返回 mock 数据

### 4.2 我消费的 mock

在真实上游就绪前，teacher-portal 使用以下 mock：

- **HTTP/GraphQL mock**：使用 MSW（Mock Service Worker）拦截所有请求
  - POST /api/auth/login → 返回固定 JWT + UserInfo
  - POST /api/v1/teacher/graphql → 根据 operationName 返回对应 mock 响应（与 teacher-bff mock 数据一致，对齐 §2.3）
  - 所有 mock 响应定义在 `apps/teacher-portal/src/mocks/fixtures/*.json`
- **WebSocket mock**：使用 mock-socket 库
  - 连接 ws://localhost:8081/ws 后每 30 秒推送 1 条 mock 通知
- **JWT mock**：使用固定 mock JWT（与 api-gateway mock 公钥配对），存入 localStorage（F12；P6 迁移 httpOnly cookie）
- **环境切换**：通过 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制是否启用 MSW，上游就绪后设为 `disabled`