xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b3511910d1f2e1fcf50210edfa9ec030df985a2e
Edu/docs/architecture/issues/contracts/teacher-bff_contract.md
SpecialX faaaf29f67 docs: ai 协作文档体系重构与多 ai 仲裁结果落地 
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md)

2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration)

3.各服务 01/02 文档补全

4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens)

5.Proto 契约补全

6.004 架构影响地图更新

7.端口分配表

8.设计规格文档
2026-07-10 12:58:22 +08:00

8.0 KiB
Raw Blame History

teacher-bff 对接契约

负责人：ai03 关联：matrix.md、iam.proto、core_edu.proto、content.proto、analytics.proto、msg.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 拦截器实现，上游就绪后移除拦截器切换真实调用。

Reference in New Issue View Git Blame Copy Permalink