xiner/Edu

Files

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

7.3 KiB

Raw Blame History

student-bff 对接契约

负责人：ai04 关联：matrix.md、iam.proto、core_edu.proto、content.proto、analytics.proto、msg.proto

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

1.1 gRPC 接口（如有）

无对外 gRPC。student-bff 是 GraphQL 聚合层。

1.2 HTTP 端点（如有）

Method	Path	用途	认证
POST	/graphql	学生 BFF GraphQL 端点	JWT 必需 + student 角色
GET	/graphql	GraphQL Playground（开发环境）	开发环境公开
GET	/healthz	健康检查（liveness）	公开
GET	/readyz	就绪检查（readiness，含下游 gRPC 连通性）	公开

1.3 GraphQL schema（如 BFF）

GraphQL schema 文件路径：apps/student-bff/src/schema/*.graphql（端口 :3009）

核心 Query / Mutation 域：

auth：currentUser（聚合 iam.GetUserInfo + GetEffectivePermissions + GetViewports）
myClasses：我的班级（聚合 core-edu.ClassService.GetClass + ListStudentsByClass）
myExams：我的考试列表（聚合 core-edu.ExamService.ListExamsByClass）
myHomework：我的作业（聚合 core-edu.HomeworkService.ListHomeworkByClass + SubmitHomework）
myGrades：我的成绩（聚合 core-edu.GradeService.ListGradesByStudent）
myAttendance：我的考勤（聚合 core-edu.AttendanceService.ListAttendanceByStudent）
content：textbooks / chapters / learningPath（聚合 content.KnowledgeGraphService.GetLearningPath）
dashboard：studentDashboard（聚合 data-ana.AnalyticsService.GetStudentDashboard）
weakness：myWeakness（聚合 data-ana.AnalyticsService.GetStudentWeakness）
trend：myTrend（聚合 data-ana.AnalyticsService.GetLearningTrend）
notifications：myNotifications / markAsRead（聚合 msg.NotificationService）

1.4 Kafka 事件发布（如有）

无。student-bff 不发布事件，仅做 gRPC 聚合。

1.5 错误码前缀

BFF_STUDENT_（如 BFF_STUDENT_UPSTREAM_UNAVAILABLE、BFF_STUDENT_AGGREGATION_FAILED、BFF_STUDENT_FORBIDDEN）

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

2.1 gRPC 调用（同步）

被调用方	Service.RPC	用途	mock 策略
iam (ai06)	IamService.GetUserInfo	获取当前学生信息	iam 就绪前返回固定 UserInfo（student 角色）
iam (ai06)	IamService.GetEffectivePermissions	权限校验	iam 就绪前返回学生权限集
iam (ai06)	IamService.GetViewports	学生导航菜单	iam 就绪前返回固定视口列表
core-edu (ai08)	ClassService.GetClass	我的班级详情	core-edu 就绪前返回固定 ClassInfo
core-edu (ai08)	ClassService.ListStudentsByClass	班级同学名单	core-edu 就绪前返回固定 30 个 StudentInfo
core-edu (ai08)	ExamService.ListExamsByClass	我的考试	core-edu 就绪前返回固定 2 个 Exam
core-edu (ai08)	HomeworkService.ListHomeworkByClass	我的作业	core-edu 就绪前返回固定 3 个 Homework
core-edu (ai08)	HomeworkService.SubmitHomework	提交作业	core-edu 就绪前返回 success=true
core-edu (ai08)	GradeService.ListGradesByStudent	我的成绩	core-edu 就绪前返回固定 5 个 Grade
core-edu (ai08)	AttendanceService.ListAttendanceByStudent	我的考勤	core-edu 就绪前返回固定 10 条 Attendance
content (ai09)	TextbookService.ListTextbooks	教材列表	content 就绪前返回固定 5 个教材
content (ai09)	ChapterService.ListChapters	章节列表	content 就绪前返回固定章节树
content (ai09)	KnowledgeGraphService.GetLearningPath	学习路径	content 就绪前返回固定 8 个知识点推荐顺序
data-ana (ai11)	AnalyticsService.GetStudentDashboard	学生仪表盘	data-ana 就绪前返回固定仪表盘
data-ana (ai11)	AnalyticsService.GetStudentWeakness	我的薄弱点	data-ana 就绪前返回固定 3 个 weak_points
data-ana (ai11)	AnalyticsService.GetLearningTrend	学习趋势	data-ana 就绪前返回固定趋势数据
msg (ai10)	NotificationService.ListNotifications	学生通知	msg 就绪前返回固定 10 条通知
msg (ai10)	NotificationService.MarkAsRead	标记已读	msg 就绪前返回 success=true

2.2 Kafka 事件订阅（异步）

无。student-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）

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

student-bff GraphQL :3009 启用（/healthz 返回 200）
/readyz 返回 200（含 5 个下游 gRPC 连通性检查）
GraphQL schema 可内省（POST /graphql 返回 schema）
核心 Query 可执行：currentUser / myClasses / studentDashboard / myGrades
核心 Mutation 可执行：submitHomework / markAsRead

§4 Mock 策略

4.1 我提供的 mock

在 student-bff 真实就绪前，为下游（student-portal）提供以下 mock：

GraphQL mock：使用 Apollo Server mockProviders 或 MSW 拦截 POST /graphql
- currentUser 返回固定学生（id="student-001", name="李同学", roles=["student"]）
- myClasses 返回固定 1 个班级
- studentDashboard 返回固定仪表盘（avg_score=85.0, class_rank=5）
- myGrades 返回固定 5 个成绩
- myHomework 返回固定 3 个作业（1 个待提交）
- myNotifications 返回固定 10 条通知

4.2 我消费的 mock

在真实上游就绪前，student-bff 使用以下 mock（详见 §2.1 mock 策略列）：

iam mock：固定 UserInfo + 学生权限 + 固定视口
core-edu mock：固定班级/同学/考试/作业/成绩/考勤
content mock：固定教材/章节/学习路径
data-ana mock：固定仪表盘/薄弱点/趋势
msg mock：固定通知列表 + MarkAsRead success

所有上游 mock 通过 gRPC client 拦截器实现，上游就绪后移除拦截器切换真实调用。

7.3 KiB Raw Blame History Unescape Escape