345 lines
38 KiB
Markdown
345 lines
38 KiB
Markdown
# teacher-bff 下一步工作与上下游依赖
|
||
|
||
> 模块：teacher-bff（教学场景域聚合层 BFF，GraphQL 聚合层，端口 3003）
|
||
> 负责人：ai03
|
||
> 更新日期：2026-07-14（v2：schema v2 扩展 + 96 operations + Docker E2E 验证通过）
|
||
> 关联文档：[02-architecture-design.md](./02-architecture-design.md)、[admin-portal_contract.md](../../../docs/architecture/issues/contracts/admin-portal_contract.md)
|
||
|
||
---
|
||
|
||
## 1. 模块当前状态
|
||
|
||
teacher-bff 已完成 P2-P7 全部批次，schema 重写为 v2 扁平命名，扩展至 62 Query + 34 Mutation = 96 operations，满足 teacher-portal 89 个 operation 需求 + admin-portal 全部 admin 域需求。Docker 镜像构建成功，21/21 GraphQL 端到端查询测试全部通过（接入真实 iam，无 mock 数据）。
|
||
|
||
### 1.1 本地 Docker 验证结果（2026-07-14 v2）
|
||
|
||
测试环境：本地 Docker（edu-iam-test + edu-teacher-bff-test 容器，接入 `edu-full_default` 网络，直连 edu-mysql / edu-redis / edu-kafka）
|
||
|
||
```
|
||
镜像：edu-test-iam:latest、edu-test-teacher-bff:latest
|
||
容器：edu-iam-test（NODE_ENV=production, DEV_MODE=true, HTTP 3002 + gRPC 50052）
|
||
edu-teacher-bff-test（NODE_ENV=production, TEACHER_BFF_DEV_MODE=true, HTTP 3003）
|
||
测试用户：ffd5f3f8-67a3-4774-9ccc-c4c6d2288eaf（admin-test@edu.local, role=admin, data_scope=all）
|
||
测试 Headers：x-user-id=teacher-001, x-user-role=teacher
|
||
```
|
||
|
||
| 验证项 | 状态 | 说明 |
|
||
| ---------------------------- | ---- | ------------------------------------------------------------------ |
|
||
| iam Docker 镜像构建 | ✅ | node:20-alpine + bcryptjs（纯 JS，无 native 编译） |
|
||
| teacher-bff Docker 镜像构建 | ✅ | node:22-alpine + --ignore-scripts（跳过 husky） |
|
||
| iam HTTP /healthz | ✅ | 200 |
|
||
| iam gRPC 50052 | ✅ | GetUserInfo / BatchGetUsers / GetEffectivePermissions 等方法可调用 |
|
||
| teacher-bff /healthz | ✅ | 200 |
|
||
| teacher-bff /readyz | ✅ | 7 依赖健康（iam gRPC + Redis + 5 个 mock 客户端探针） |
|
||
| GraphQL schema introspection | ✅ | 62 Query + 34 Mutation 字段全部存在 |
|
||
| typecheck + lint + build | ✅ | 三项零错误 |
|
||
| **E2E 21/21 GraphQL 查询** | ✅ | **全部 PASS**（详见 §1.2） |
|
||
|
||
### 1.2 E2E 测试结果（21/21 PASS）
|
||
|
||
| # | 查询 | 状态 | 说明 |
|
||
| --- | ---------------- | ---- | -------------------------------------------- |
|
||
| 1 | me | ✅ | 返回真实 iam 数据 |
|
||
| 2 | dashboard | ✅ | 聚合 user + classes + viewports + stats |
|
||
| 3 | classes | ✅ | core-edu mock 返回 3 个班级 |
|
||
| 4 | classExams | ✅ | core-edu mock 返回考试列表 |
|
||
| 5 | classHomework | ✅ | core-edu mock 返回作业列表（含 status 字段） |
|
||
| 6 | classStudents | ✅ | 返回学生列表 |
|
||
| 7 | examDetail | ✅ | 返回考试详情 |
|
||
| 8 | homeworkDetail | ✅ | 返回作业详情（含 submissions） |
|
||
| 9 | knowledgeGraph | ✅ | content mock 返回知识图谱 |
|
||
| 10 | classAnalytics | ✅ | data-ana mock 返回班级分析 |
|
||
| 11 | studentAnalytics | ✅ | data-ana mock 返回学生分析 |
|
||
| 12 | myNotifications | ✅ | msg mock 返回通知（isRead → read 字段映射） |
|
||
| 13 | notifications | ✅ | msg mock 返回通知列表 |
|
||
| 14 | adminRoles | ✅ | 返回真实 iam 角色（3 个） |
|
||
| 15 | adminDashboard | ✅ | 返回真实统计数据 |
|
||
| 16 | attendanceList | ✅ | P7 降级返回空 page |
|
||
| 17 | examBuild | ✅ | P7 降级返回空 |
|
||
| 18 | gradeStats | ✅ | P7 降级返回空 |
|
||
| 19 | lessonPlans | ✅ | P7 降级返回空数组 |
|
||
| 20 | textbooks | ✅ | P7 降级返回空 page |
|
||
| 21 | errorBook | ✅ | P7 降级返回空 summary |
|
||
|
||
### 1.3 已完成的关键修复（v2 新增）
|
||
|
||
| # | 工作项 | 详情 |
|
||
| --- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| 13 | Schema v2 重写 | 62 Query + 34 Mutation = 96 operations（teacher 域 23 Query + 9 Mutation，admin 域 39 Query + 25 Mutation） |
|
||
| 14 | Teacher 域 P3-P5 扩展 | classStudents/examDetail/homeworkDetail/classExams/classHomework/examGrades/updateUser/markAsRead/generateLessonPlan/generateReport + P4 knowledgeGraph/classAnalytics/studentAnalytics + P5 myNotifications |
|
||
| 15 | P7 全部降级实现 | 39 Query + 25 Mutation 降级返回空/默认值 + warning log（attendanceList/attendanceSheet/attendanceStats/classDetail/classSchedule/leaveRequests/scheduleChanges/electiveCourses/examRichContent/proctoringStatus/submissionScanGrading/examBuild/examAnalytics/questions/textbooks/textbookCreate/gradeEntry/gradeStats/gradeAnalytics/reportCards/homeworkSubmissionSummary/homeworkAssignmentSubmissions/aiBatchGrading/lessonPlans/lessonPlanDetail/lessonPlanLibrary/lessonPlanCalendar/lessonPlanHeatmap/coursePlans/diagnosticReports/classDiagnostic/studentDiagnostic/errorBook/practiceAnalytics + 25 Mutation） |
|
||
| 16 | Dockerfile 重写（v2） | 采用 parent-bff 模式：--ignore-scripts 跳过 husky，--ignore-workspace 独立安装生产依赖 |
|
||
| 17 | docker-compose.test.yml 配置 5 个 gRPC target | CORE_EDU_GRPC_TARGET=core-edu:50053, CONTENT_GRPC_TARGET=content:50054, DATA_ANA_GRPC_TARGET=data-ana:50055, MSG_GRPC_TARGET=msg:50056, AI_GRPC_TARGET=ai:50058 |
|
||
| 18 | docker-compose.deploy.yml 同步配置 | 生产部署配置同步更新所有 gRPC target + TEACHER_BFF_DEV_MODE + REDIS_URL + OTEL |
|
||
| 19 | IamAuditLog beforeState/afterState 类型修复 | iam.types.ts 添加 beforeState/afterState: string \| null 字段 |
|
||
| 20 | Homework.status 字段修复 | schema Homework 类型添加 status: String 字段（对齐 core-edu mock 数据） |
|
||
| 21 | Notification isRead → read 字段映射 | resolver 中将 msg.Notification.isRead 映射为 schema Notification.read |
|
||
| 22 | updateUser 统一签名 | teacher.updateUser 覆盖 admin.updateUser：`updateUser(id: ID, input: UpdateUserInput!): User!` |
|
||
| 23 | textbookCreate 返回类型修复 | Textbook → TextbookItem（Textbook 类型未定义） |
|
||
| 24 | 死代码清理 | 删除 circuit-breaker.ts（import opossum 但 opossum 不在 package.json 中） |
|
||
| 25 | resolver 合并顺序调整 | admin 先 → teacher 后，使 teacher.updateUser 覆盖 admin.updateUser |
|
||
|
||
---
|
||
|
||
## 2. 上游依赖（teacher-bff 依赖谁）
|
||
|
||
### 2.1 iam 服务（ai06 负责）— P0
|
||
|
||
| # | 依赖项 | 用途 | 状态 |
|
||
| --- | ------------------------------------------------ | -------------------------------------------- | -------------- |
|
||
| 1 | gRPC `GetUserInfo(userId)` :50052 | `currentUser` / `me` 查询 | ✅ 已就绪 |
|
||
| 2 | gRPC `BatchGetUsers(userIds)` :50052 | `adminUsers` 查询 | ✅ 已就绪 |
|
||
| 3 | gRPC `GetEffectivePermissions(userId)` :50052 | 用户有效权限 | ✅ 已就绪 |
|
||
| 4 | gRPC `GetEffectiveDataScope(userId)` :50052 | 用户数据范围 | ✅ 已就绪 |
|
||
| 5 | gRPC `GetViewports(userId)` :50052 | `adminViewports` 查询 | ✅ 已就绪 |
|
||
| 6 | gRPC `GetPublicKey()` :50052 | RS256 公钥 | ✅ 已就绪 |
|
||
| 7 | REST `GET /v1/iam/roles` :3002 | `adminRoles` 查询 | ✅ 已就绪 |
|
||
| 8 | REST `GET /v1/iam/permissions` :3002 | `adminPermissions` 查询 | ✅ 已就绪 |
|
||
| 9 | REST `GET /v1/iam/audit` :3002 | `auditLogs` 查询 | ✅ 已就绪 |
|
||
| 10 | REST `GET /v1/iam/viewports` :3002 | `adminViewports` 查询（备选） | ✅ 已就绪 |
|
||
| 11 | REST `GET /v1/iam/permissions/effective` :3002 | 用户有效权限（备选） | ✅ 已就绪 |
|
||
| 12 | `POST /v1/iam/register` / `POST /v1/iam/login` | 用户注册/登录 | ✅ 已就绪 |
|
||
| 13 | `GET /.well-known/jwks.json` :3002 | RS256 JWKS | ⏳ 待 iam 实现 |
|
||
| 14 | `PATCH /v1/iam/users/:id` | admin `updateUser` / `toggleUserStatus` | ⏳ 待 iam 实现 |
|
||
| 15 | `POST /v1/iam/roles` / `PATCH /v1/iam/roles/:id` | admin `createRole` / `updateRolePermissions` | ⏳ 待 iam 实现 |
|
||
|
||
**关键环境变量**：`IAM_GRPC_TARGET=iam:50052`, `IAM_SERVICE_URL=http://iam:3002`
|
||
|
||
### 2.2 core-edu 服务（ai07 负责）— P1
|
||
|
||
| # | 依赖项 | 用途 | 状态 |
|
||
| --- | ------------------------------------------- | --------------------------------- | ------------------- |
|
||
| 1 | gRPC `ListClasses(teacherId)` :50053 | `classes` / `adminClasses` 查询 | ⏳ 待 core-edu 实现 |
|
||
| 2 | gRPC `ListExamsByClass(classId)` :50053 | `classExams` / `exams` 查询 | ⏳ 待 core-edu 实现 |
|
||
| 3 | gRPC `ListHomeworkByClass(classId)` :50053 | `classHomework` / `homework` 查询 | ⏳ 待 core-edu 实现 |
|
||
| 4 | gRPC `ListGradesByExam(examId)` :50053 | `examGrades` / `grades` 查询 | ⏳ 待 core-edu 实现 |
|
||
| 5 | gRPC `ListStudentsByClass(classId)` :50053 | `classStudents` 查询 | ⏳ 待 core-edu 实现 |
|
||
| 6 | gRPC `GetExamDetail(examId)` :50053 | `examDetail` 查询 | ⏳ 待 core-edu 实现 |
|
||
| 7 | gRPC `GetHomeworkDetail(homeworkId)` :50053 | `homeworkDetail` 查询 | ⏳ 待 core-edu 实现 |
|
||
| 8 | gRPC `CreateExam(input)` :50053 | `createExam` mutation | ⏳ 待 core-edu 实现 |
|
||
| 9 | gRPC `AssignHomework(input)` :50053 | `assignHomework` mutation | ⏳ 待 core-edu 实现 |
|
||
| 10 | gRPC `RecordGrade(input)` :50053 | `recordGrade` mutation | ⏳ 待 core-edu 实现 |
|
||
| 11 | gRPC `GetClassPerformance(classId)` :50053 | `classPerformance` 查询 | ⏳ 待 core-edu 实现 |
|
||
|
||
**当前状态**：`CORE_EDU_GRPC_TARGET=core-edu:50053` 已配置，但 core-edu 服务未启动，走降级模式 B（mock 数据）。
|
||
|
||
### 2.3 content 服务（ai08 负责）— P1
|
||
|
||
| # | 依赖项 | 用途 | 状态 |
|
||
| --- | ---------------------------------------- | --------------------------------------- | ------------------ |
|
||
| 1 | gRPC `GetKnowledgePath(classId)` :50054 | `knowledgePath` / `knowledgeGraph` 查询 | ⏳ 待 content 实现 |
|
||
| 2 | gRPC `ListTextbooks()` :50054 | `textbooks` 查询 | ⏳ 待 content 实现 |
|
||
| 3 | gRPC `ListLessonPlans(teacherId)` :50054 | `lessonPlans` 查询 | ⏳ 待 content 实现 |
|
||
|
||
**当前状态**：`CONTENT_GRPC_TARGET=content:50054` 已配置，但 content 服务未启动，走降级模式 B。
|
||
|
||
### 2.4 data-ana 服务（ai11 负责）— P1
|
||
|
||
| # | 依赖项 | 用途 | 状态 |
|
||
| --- | -------------------------------------------- | ----------------------- | ------------------- |
|
||
| 1 | gRPC `GetClassAnalytics(classId)` :50055 | `classAnalytics` 查询 | ⏳ 待 data-ana 实现 |
|
||
| 2 | gRPC `GetStudentAnalytics(studentId)` :50055 | `studentAnalytics` 查询 | ⏳ 待 data-ana 实现 |
|
||
| 3 | gRPC `GetStudentWeakness(classId)` :50055 | `studentWeakness` 查询 | ⏳ 待 data-ana 实现 |
|
||
| 4 | gRPC `GetLearningTrend(classId)` :50055 | `learningTrend` 查询 | ⏳ 待 data-ana 实现 |
|
||
|
||
**当前状态**：`DATA_ANA_GRPC_TARGET=data-ana:50055` 已配置，但 data-ana 服务未启动，走降级模式 B。
|
||
|
||
### 2.5 msg 服务（ai10 负责）— P1
|
||
|
||
| # | 依赖项 | 用途 | 状态 |
|
||
| --- | --------------------------------------- | ------------------------------------------------ | -------------- |
|
||
| 1 | gRPC `ListNotifications(userId)` :50056 | `notifications` / `myNotifications` 查询 | ⏳ 待 msg 实现 |
|
||
| 2 | gRPC `MarkNotificationRead(id)` :50056 | `markNotificationAsRead` / `markAsRead` mutation | ⏳ 待 msg 实现 |
|
||
| 3 | gRPC `ListAnnouncements(filter)` :50056 | `adminAnnouncements` 查询 | ⏳ 待 msg 实现 |
|
||
|
||
**当前状态**：`MSG_GRPC_TARGET=msg:50056` 已配置，但 msg 服务未启动，走降级模式 B。
|
||
|
||
### 2.6 ai 服务（ai12 负责）— P1
|
||
|
||
| # | 依赖项 | 用途 | 状态 |
|
||
| --- | --------------------------------------- | ----------------------------- | ------------- |
|
||
| 1 | gRPC `GenerateQuestion(input)` :50058 | `generateQuestion` mutation | ⏳ 待 ai 实现 |
|
||
| 2 | SSE `POST /v1/ai/chat/stream` :3008 | AI 对话流式响应 | ⏳ 待 ai 实现 |
|
||
| 3 | gRPC `GenerateLessonPlan(input)` :50058 | `generateLessonPlan` mutation | ⏳ 待 ai 实现 |
|
||
| 4 | gRPC `GenerateReport(input)` :50058 | `generateReport` mutation | ⏳ 待 ai 实现 |
|
||
|
||
**当前状态**：`AI_GRPC_TARGET=ai:50058` 已配置，但 ai 服务未启动，走降级模式 B。
|
||
|
||
### 2.7 Redis（基础设施）— P0
|
||
|
||
| 项 | 内容 |
|
||
| -------- | ------------------------------------- |
|
||
| 依赖内容 | /readyz 探针 + DataLoader 缓存（P4+） |
|
||
| 端点 | `redis://edu-redis:6379` |
|
||
| 当前状态 | ✅ 本地 Docker edu-redis 已就绪 |
|
||
|
||
---
|
||
|
||
## 3. 下游依赖（谁依赖 teacher-bff）
|
||
|
||
### 3.1 admin-portal（ai16 负责）— P0
|
||
|
||
| 能力 | 配置 | 状态 |
|
||
| ----------------------------- | ------------------------------------------- | --------- |
|
||
| `POST /graphql` :3003 | admin-portal GraphQL 代理目标 | ✅ 已就绪 |
|
||
| Schema v2 扁平命名 | 62 Query + 34 Mutation 字段全部实现 | ✅ 已完成 |
|
||
| x-user-data-scope header 透传 | admin 角色 data_scope=all 跳过 iam 权限校验 | ✅ 已实现 |
|
||
| 降级模式 B | 未就绪下游返回空结果 + warning | ✅ 已实现 |
|
||
|
||
**portal 需求来源**：`apps/admin-portal/docs/nextstep-v2.md`
|
||
|
||
### 3.2 teacher-portal（ai13 负责）— P0
|
||
|
||
| 能力 | 配置 | 状态 |
|
||
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
|
||
| `POST /graphql` :3003 | teacher-portal GraphQL 代理目标 | ✅ 已就绪 |
|
||
| teacher 域 23 Query | dashboard/viewports/me/classes/class/exams/homework/grades/knowledgePath/classPerformance/studentWeakness/learningTrend/notifications/classStudents/examDetail/homeworkDetail/classExams/classHomework/examGrades/knowledgeGraph/classAnalytics/studentAnalytics/myNotifications/generateLessonPlan/generateReport | ✅ 全部实现 |
|
||
| teacher 域 9 Mutation | createExam/assignHomework/recordGrade/generateQuestion/markNotificationAsRead/updateUser/markAsRead/generateLessonPlan/generateReport | ✅ 全部实现 |
|
||
| P7 39 Query + 25 Mutation 降级 | attendanceList/examBuild/gradeStats/lessonPlans/textbooks/errorBook 等 | ✅ 全部降级实现 |
|
||
| SSE `/v1/teacher/ai/chat/stream` | AI 对话流式透传 | ✅ 已实现 |
|
||
| 5 个 gRPC target 配置 | core-edu/content/data-ana/msg/ai | ✅ 已配置 |
|
||
| Zod 输入验证 | createExam/assignHomework/recordGrade/generateQuestion | ✅ 已实现 |
|
||
|
||
**portal 需求来源**：`apps/teacher-portal/nextstep-v2.md`（12 项待补工作全部 ✅）
|
||
|
||
### 3.3 api-gateway（ai01 负责）— P0
|
||
|
||
| 能力 | 配置 | 状态 |
|
||
| ----------------------------- | -------------------------- | --------------------- |
|
||
| `/api/v1/teacher/*` 反向代理 | → teacher-bff:3003/* | ✅ api-gateway 已配置 |
|
||
| `/api/admin/graphql` 反向代理 | → teacher-bff:3003/graphql | ✅ api-gateway 已配置 |
|
||
| `GET /healthz` 端点 | /readyz 下游健康检查 | ✅ 已实现 |
|
||
| `GET /readyz` 端点 | iam gRPC + Redis 健康检查 | ✅ 已实现 |
|
||
| `GET /metrics` 端点 | Prometheus 指标 | ✅ 已实现 |
|
||
|
||
### 3.4 student-portal / parent-portal
|
||
|
||
无直接 teacher-bff 需求（student-bff / parent-bff 各自负责）。
|
||
|
||
---
|
||
|
||
## 4. GraphQL Schema 清单（v2）
|
||
|
||
### 4.1 Query 字段（62 个）
|
||
|
||
**Teacher 域（23 个）**：dashboard / viewports / me / classes / class / exams / homework / grades / knowledgePath / classPerformance / studentWeakness / learningTrend / notifications / classStudents / examDetail / homeworkDetail / classExams / classHomework / examGrades / knowledgeGraph / classAnalytics / studentAnalytics / myNotifications
|
||
|
||
**Admin 域（39 个）**：currentUser / adminUsers / adminUser / adminRoles / adminPermissions / adminViewports / adminOrganization / adminClasses / adminTeachers / adminStudents / auditLogs / adminDashboard / systemSettings / auditOverviewStats / auditTrend / dataChangeLogs / loginLogs / adminSchools / adminGrades / adminGradeInsights / adminDepartments / adminAcademicYears / adminAnnouncements / adminInvitationCodes / adminFiles / adminFileStats / aiProviders / aiUsage + P7 11 个降级 Query
|
||
|
||
### 4.2 Mutation 字段（34 个）
|
||
|
||
**Teacher 域（9 个）**：createExam / assignHomework / recordGrade / generateQuestion / markNotificationAsRead / updateUser / markAsRead / generateLessonPlan / generateReport
|
||
|
||
**Admin 域（25 个）**：createUser / updateUser / toggleUserStatus / createRole / updateRolePermissions / updateViewport / updateSystemSettings / createAnnouncement / publishAnnouncement / archiveAnnouncement / toggleAnnouncementPin / generateInvitationCodes / deleteInvitationCodes / deleteFiles / updateAiProvider + P7 10 个降级 Mutation
|
||
|
||
### 4.3 Schema 文件位置
|
||
|
||
- `packages/shared-ts/contracts/graphql/teacher-bff.schema.graphql`（SDL 定义，v2 扁平命名）
|
||
|
||
---
|
||
|
||
## 5. 环境变量清单（Docker 部署）
|
||
|
||
| 变量 | 必填 | 示例值 | 说明 |
|
||
| ----------------------------- | ---- | ---------------------------- | ---------------------------------- |
|
||
| `PORT` | 是 | `3003` | HTTP 监听端口 |
|
||
| `GRAPHQL_PATH` | 否 | `/graphql` | GraphQL 端点路径 |
|
||
| `TEACHER_BFF_DEV_MODE` | 是 | `true`/`false` | 越权防御开关（P2 放行 / 生产拒绝） |
|
||
| `REDIS_URL` | 是 | `redis://edu-redis:6379` | Redis 连接地址 |
|
||
| `IAM_GRPC_TARGET` | 是 | `iam:50052` | iam gRPC 目标 |
|
||
| `IAM_SERVICE_URL` | 是 | `http://iam:3002` | iam REST 基址 |
|
||
| `CORE_EDU_GRPC_TARGET` | 否 | `core-edu:50053` | core-edu gRPC 目标（留空走降级） |
|
||
| `CONTENT_GRPC_TARGET` | 否 | `content:50054` | content gRPC 目标（留空走降级） |
|
||
| `DATA_ANA_GRPC_TARGET` | 否 | `data-ana:50055` | data-ana gRPC 目标（留空走降级） |
|
||
| `MSG_GRPC_TARGET` | 否 | `msg:50056` | msg gRPC 目标（留空走降级） |
|
||
| `AI_GRPC_TARGET` | 否 | `ai:50058` | ai gRPC 目标（留空走降级） |
|
||
| `OTEL_EXPORTER_OTLP_ENDPOINT` | 否 | `http://otel-collector:4318` | OTLP 上报端点 |
|
||
| `LOG_LEVEL` | 否 | `info` | 日志级别 |
|
||
|
||
---
|
||
|
||
## 6. 剩余工作
|
||
|
||
### 6.1 真实下游联调（按优先级）
|
||
|
||
| # | 工作项 | 阻塞条件 | 状态 |
|
||
| --- | ------------------------------------------------------------- | ------------------ | ---- |
|
||
| 1 | core-edu gRPC 联调 | core-edu 服务就绪 | ⏳ |
|
||
| 2 | content gRPC 联调 | content 服务就绪 | ⏳ |
|
||
| 3 | data-ana gRPC 联调 | data-ana 服务就绪 | ⏳ |
|
||
| 4 | msg gRPC 联调 | msg 服务就绪 | ⏳ |
|
||
| 5 | ai gRPC + SSE 联调 | ai 服务就绪 | ⏳ |
|
||
| 6 | iam REST CRUD 端点联调（createUser/updateUser/createRole 等） | iam 补齐 REST CRUD | ⏳ |
|
||
|
||
> 注：gRPC target 已全部配置，服务就绪后自动从 mock 切换为真实 gRPC 调用，无需修改 teacher-bff 代码。
|
||
|
||
### 6.2 P6 硬化任务
|
||
|
||
| # | 工作项 | 状态 |
|
||
| --- | ----------------------------- | ----------------------- |
|
||
| 1 | DataLoader 批量查询（防 N+1） | ⏳ 待下游就绪后实现 |
|
||
| 2 | Redis 多层缓存 | ⏳ 待下游就绪后实现 |
|
||
| 3 | OTel trace 上报 | ✅ 已实现（tracer.ts） |
|
||
| 4 | Prometheus 指标 | ✅ 已实现（metrics.ts） |
|
||
|
||
---
|
||
|
||
## 7. 已完成项汇总
|
||
|
||
| 工作项 | 状态 | 验证方式 |
|
||
| --------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------- |
|
||
| P2 核心 5 Query | ✅ | typecheck + lint + Docker 联调 |
|
||
| P3 teacher 域 Query/Mutation | ✅ | typecheck + lint + Docker 联调 |
|
||
| P4 学习分析 Query | ✅ | typecheck + lint + E2E 测试 |
|
||
| P5 通知 + AI Query/Mutation | ✅ | typecheck + lint + E2E 测试 |
|
||
| P6 admin 扁平命名重构（ARB-001） | ✅ | typecheck + lint + Docker 联调 |
|
||
| P6 admin 41 Query + 20 Mutation | ✅ | schema introspection + Docker 联调 |
|
||
| P6 x-user-data-scope header 透传 | ✅ | Docker 联调（adminRoles 返回真实数据） |
|
||
| P6 IamGrpcController 注册修复 | ✅ | Docker 联调（currentUser 返回真实数据） |
|
||
| P6 Zod 输入验证 | ✅ | typecheck |
|
||
| P6 SSE 流式透传 | ✅ | typecheck |
|
||
| **Schema v2 扩展（96 operations）** | ✅ | **schema introspection + E2E 21/21 PASS** |
|
||
| **Teacher 域 P3-P5 扩展（12 项）** | ✅ | **E2E 测试全部 PASS** |
|
||
| **P7 全部降级实现（39 Query + 25 Mutation）** | ✅ | **E2E 测试全部 PASS** |
|
||
| **5 个 gRPC target 配置** | ✅ | **docker-compose.test.yml + deploy.yml** |
|
||
| **Dockerfile 重写（--ignore-scripts 模式）** | ✅ | **Docker 构建成功** |
|
||
| **Homework.status 字段修复** | ✅ | **E2E classHomework PASS** |
|
||
| **Notification isRead → read 映射** | ✅ | **E2E myNotifications PASS** |
|
||
| Docker 镜像构建 | ✅ | edu-test-teacher-bff:latest（node:22-alpine） |
|
||
| Docker 容器运行 | ✅ | /healthz 200 + /readyz 200 |
|
||
| 真实 iam 联调（无 mock） | ✅ | currentUser/me/adminRoles/adminPermissions/auditLogs/adminDashboard/systemSettings 全部返回真实数据 |
|
||
| `me` 查询 dataScope 修复（v2） | ✅ | Docker 验证返回 ALL |
|
||
| DataScope 大小写转换（v2） | ✅ | iam-grpc.client.ts toUpperCase() |
|
||
| IamModule 客户端选择修复（v2） | ✅ | IAM_GRPC_TARGET 配置后强制 gRPC |
|
||
|
||
---
|
||
|
||
## 8. 关键文件路径
|
||
|
||
| 文件 | 用途 |
|
||
| ------------------------------------------------------------------- | ---------------------------------------- |
|
||
| `services/teacher-bff/src/admin/admin.resolver.ts` | admin GraphQL resolver（扁平命名） |
|
||
| `services/teacher-bff/src/admin/admin.service.ts` | admin 业务逻辑层 |
|
||
| `services/teacher-bff/src/teacher/teacher.resolver.ts` | teacher 域 GraphQL resolver（v2 扩展） |
|
||
| `services/teacher-bff/src/teacher/teacher.service.ts` | teacher 域业务逻辑层（v2 扩展） |
|
||
| `services/teacher-bff/src/teacher/ai-chat-sse.controller.ts` | SSE 流式 AI 对话 |
|
||
| `services/teacher-bff/src/graphql/graphql.controller.ts` | GraphQL 入口 + mergeResolvers 深合并 |
|
||
| `services/teacher-bff/src/graphql/context.ts` | GraphQL 上下文（提取 x-user-* headers） |
|
||
| `services/teacher-bff/src/clients/iam/iam-grpc.client.ts` | iam gRPC + REST 客户端 |
|
||
| `services/teacher-bff/src/clients/core-edu/core-edu-grpc.client.ts` | core-edu gRPC 客户端 |
|
||
| `services/teacher-bff/src/clients/content/content-grpc.client.ts` | content gRPC 客户端 |
|
||
| `services/teacher-bff/src/clients/data-ana/data-ana-grpc.client.ts` | data-ana gRPC 客户端 |
|
||
| `services/teacher-bff/src/clients/msg/msg-grpc.client.ts` | msg gRPC 客户端 |
|
||
| `services/teacher-bff/src/clients/ai/ai-grpc.client.ts` | ai gRPC 客户端 |
|
||
| `services/teacher-bff/src/clients/types.ts` | CallContext（含 dataScope 字段） |
|
||
| `services/teacher-bff/src/clients/grpc/grpc.factory.ts` | gRPC 客户端工厂 |
|
||
| `services/teacher-bff/Dockerfile` | Docker 构建（--ignore-scripts 模式） |
|
||
| `packages/shared-ts/contracts/graphql/teacher-bff.schema.graphql` | GraphQL schema 契约（v2，96 operations） |
|
||
| `packages/shared-proto/proto/iam.proto` | iam gRPC proto 契约 |
|
||
| `infra/docker-compose.test.yml` | 测试环境 compose（5 个 gRPC target） |
|
||
| `infra/docker-compose.deploy.yml` | 生产部署 compose（5 个 gRPC target） |
|
||
|
||
---
|
||
|
||
**本文件由 ai03 维护，上游/下游工作项请各负责 AI 完成后通知 ai03 更新状态。**
|