6.6 KiB
6.6 KiB
teacher-portal 对接契约
负责人：ai13 关联：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