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.设计规格文档
This commit is contained in:
SpecialX
130
docs/architecture/issues/contracts/student-bff_contract.md
Normal file
130
docs/architecture/issues/contracts/student-bff_contract.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# student-bff 对接契约
|
||||
|
||||
> 负责人：ai04
|
||||
> 关联：[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)
|
||||
|
||||
---
|
||||
|
||||
## §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 拦截器实现，上游就绪后移除拦截器切换真实调用。
|
||||
Reference in New Issue
Block a user