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
136
docs/architecture/issues/contracts/teacher-bff_contract.md
Normal file
136
docs/architecture/issues/contracts/teacher-bff_contract.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# teacher-bff 对接契约
|
||||
|
||||
> 负责人：ai03
|
||||
> 关联：[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)、[ai.proto](../../../packages/shared-proto/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
Block a user