xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(teacher-bff): admin 命名空间 + 5 个 gRPC client + health probes + merge-resolvers + nextstep 文档

Browse Source
This commit is contained in:
SpecialX
2026-07-14 16:00:46 +08:00
parent 7b790f1276
commit 895a060491
50 changed files with 9739 additions and 334 deletions
Download Patch File Download Diff File Expand all files Collapse all files

344
services/teacher-bff/docs/nextstep-v2.md Normal file
View File

@@ -0,0 +1,344 @@
# 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 更新状态。**

316
services/teacher-bff/docs/nextstep.md Normal file
View File

@@ -0,0 +1,316 @@
# teacher-bff 下一步工作与上下游依赖
> 模块：teacher-bff（教学场景域聚合层 BFF，GraphQL 聚合层，端口 3003）
> 负责人：ai03
> 更新日期：2026-07-13（v2：iam 真实数据全量联调 + dataScope 修复）
> 关联文档：[02-architecture-design.md](./02-architecture-design.md)、[admin-portal_contract.md](../../../docs/architecture/issues/contracts/admin-portal_contract.md)
---
## 1. 模块当前状态
teacher-bff 已完成 P2-P6 全部批次，admin resolver 重构为扁平命名（ARB-001 裁决），Docker 镜像构建成功并在本地 Docker 验证通过（接入真实 iam，无 mock 数据）。
### 1.1 本地 Docker 验证结果（2026-07-13 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）
```
| 验证项 | 状态 | 说明 |
| -------------------------------------------------------- | ---- | --------------------------------------------------------------------- |
| iam Docker 镜像构建 | ✅ | node:20-alpine + bcryptjs（纯 JS，无 native 编译） |
| teacher-bff Docker 镜像构建 | ✅ | node:20-alpine + shared-ts 预编译 |
| 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 | ✅ | 41 Query + 20 Mutation 字段全部存在 |
| `currentUser` 查询（UUID） | ✅ | 返回真实 iam 数据（admin-test@edu.local, dataScope: ALL, 5 权限） |
| `me` 查询（UUID） | ✅ | 返回真实 iam 数据（dataScope: ALL，v2 修复） |
| `adminRoles` 查询 | ✅ | 返回真实 iam 角色（3 个：admin/student/teacher） |
| `adminPermissions` 查询 | ✅ | 返回真实 iam 权限点（5 个：iam:user:read 等） |
| `auditLogs` 查询 | ✅ | 返回真实 iam 审计日志（5 条） |
| `adminDashboard` 查询 | ✅ | 返回真实统计数据（auditEventsToday: 4） |
| `systemSettings` 查询 | ✅ | 返回真实系统设置（academicYear: 2025-2026） |
| `adminUsers` 查询 | ⚠️ | 返回空（iam REST /v1/iam/users 未实现，降级模式 B） |
| `adminTeachers` / `adminStudents` 查询 | ⚠️ | 返回空（core-edu 未接入，降级模式 B） |
| `adminSchools` / `adminGrades` / `adminDepartments` 查询 | ⚠️ | 返回空（core-edu 未接入，降级模式 B） |
| `viewports` / `adminViewports` 查询 | ⚠️ | 返回空（iam REST /v1/iam/viewports 返回空数组，DB 无 viewport 数据） |
| x-user-data-scope header 透传 | ✅ | CallContext → context.ts → graphql.controller.ts → iam-grpc.client.ts |
| `typecheck` / `lint` / `build` | ✅ | 三项零错误 |
### 1.2 已完成的关键修复
| # | 工作项 | 详情 |
| --- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 | admin.resolver.ts 扁平命名重构 | ARB-001 裁决：`adminUsers`/`adminRoles` 直接挂载在根 Query/Mutation，不再使用 `admin { users }` 命名空间 |
| 2 | graphql.controller.ts 深合并 resolvers | `mergeResolvers(teacherResolvers, adminResolvers)` 深合并 Query/Mutation 字典，避免浅展开覆盖 |
| 3 | x-user-data-scope header 透传链路 | iam PermissionGuard 检查 `data_scope=all` 跳过权限校验，teacher-bff 全链路透传该 header |
| 4 | IamGrpcController 注册修复 | 从 `providers` 数组移到 `controllers` 数组，修复 gRPC GetUserInfo UNIMPLEMENTED 错误 |
| 5 | JWT RS256 密钥生成 | 使用 Node.js crypto 生成 iam-private.pem / iam-public.pem |
| 6 | iam 种子数据 | 插入 4 个角色 + 11 个权限点 + 角色权限关联 + 审计日志 + 设置 data_scope='all' |
| 7 | Dockerfile 修复（v2） | node:20-alpine + bcryptjs（纯 JS）+ shared-ts 预编译 + pnpm prune --prod |
| 8 | bcrypt → bcryptjs 迁移（v2） | 避免 native 编译依赖（python3/make/g++），API 完全兼容 |
| 9 | NODE_ENV=production（v2） | 避免 pino-pretty 在 prune --prod 后缺失（dev 模式才使用 transport） |
| 10 | IamModule 客户端选择逻辑修复（v2） | 按 `IAM_GRPC_TARGET` 是否配置选择 gRPC 或 mock，不再受 DEV_MODE 影响 |
| 11 | DataScope 枚举大小写转换（v2） | iam DB 存小写（self/all），GraphQL enum 需大写，在 iam-grpc.client.ts getUserInfo 中 toUpperCase() |
| 12 | `me` 查询 dataScope 修复（v2） | teacher.service.ts getCurrentUser 改用 `userInfo.dataScope ?? perms.dataScope`，REST /v1/iam/permissions/effective 不返回 dataScope 时回退到 gRPC GetUserInfo 的值 |
---
## 2. 上游依赖（teacher-bff 依赖谁）
### 2.1 iam 服务（ai06 负责）— P0
| # | 依赖项 | 用途 | 状态 |
| --- | ------------------------------------------------ | ------------------------------------------------------------------ | -------------- |
| 1 | gRPC `GetUserInfo(userId)` :50052 | `currentUser` 查询：获取当前用户信息 + 角色 + 权限 | ✅ 已就绪 |
| 2 | gRPC `BatchGetUsers(userIds)` :50052 | `adminUsers` 查询：批量获取用户信息 | ✅ 已就绪 |
| 3 | gRPC `GetEffectivePermissions(userId)` :50052 | 用户有效权限列表 | ✅ 已就绪 |
| 4 | gRPC `GetEffectiveDataScope(userId)` :50052 | 用户数据范围（DataScope 6 级） | ✅ 已就绪 |
| 5 | gRPC `GetViewports(userId)` :50052 | `adminViewports` 查询：视口配置 | ✅ 已就绪 |
| 6 | gRPC `GetPublicKey()` :50052 | RS256 公钥（JWT 验签） | ✅ 已就绪 |
| 7 | gRPC `GetChildrenByParent(parentId)` :50052 | 家长端：获取学生-家长关系 | ✅ 已就绪 |
| 8 | REST `GET /v1/iam/roles` :3002 | `adminRoles` 查询：角色列表 | ✅ 已就绪 |
| 9 | REST `GET /v1/iam/permissions` :3002 | `adminPermissions` 查询：权限点列表 | ✅ 已就绪 |
| 10 | REST `GET /v1/iam/audit` :3002 | `auditLogs` 查询：审计日志 | ✅ 已就绪 |
| 11 | REST `GET /v1/iam/viewports` :3002 | `adminViewports` 查询（备选） | ✅ 已就绪 |
| 12 | REST `GET /v1/iam/permissions/effective` :3002 | 用户有效权限（备选） | ✅ 已就绪 |
| 13 | `GET /.well-known/jwks.json` :3002 | RS256 JWKS（api-gateway / push-gateway 验签） | ⏳ 待 iam 实现 |
| 14 | `POST /v1/iam/register` / `POST /v1/iam/login` | 用户注册/登录（admin `createUser` 需要） | ✅ 已就绪 |
| 15 | `PATCH /v1/iam/users/:id` | 用户更新（admin `updateUser` / `toggleUserStatus` 需要） | ⏳ 待 iam 实现 |
| 16 | `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 `GetDashboard(teacherId)` :50053 | `dashboard` 查询：教师仪表盘聚合 | ⏳ 待 core-edu 实现 |
| 2 | gRPC `ListClasses(teacherId)` :50053 | `classes` / `adminClasses` 查询 | ⏳ 待 core-edu 实现 |
| 3 | gRPC `GetClass(classId)` :50053 | `class` 查询：班级详情 | ⏳ 待 core-edu 实现 |
| 4 | gRPC `ListExams(classId)` :50053 | `exams` 查询：考试列表 | ⏳ 待 core-edu 实现 |
| 5 | gRPC `ListHomework(classId)` :50053 | `homework` 查询：作业列表 | ⏳ 待 core-edu 实现 |
| 6 | gRPC `ListGrades(classId)` :50053 | `grades` 查询：成绩列表 | ⏳ 待 core-edu 实现 |
| 7 | gRPC `CreateExam(input)` :50053 | `createExam` mutation | ⏳ 待 core-edu 实现 |
| 8 | gRPC `AssignHomework(input)` :50053 | `assignHomework` mutation | ⏳ 待 core-edu 实现 |
| 9 | gRPC `RecordGrade(input)` :50053 | `recordGrade` mutation | ⏳ 待 core-edu 实现 |
| 10 | gRPC `GetClassPerformance(classId)` :50053 | `classPerformance` 查询 | ⏳ 待 core-edu 实现 |
| 11 | gRPC `ListSchools()` / `ListGrades(schoolId)` :50053 | `adminSchools` / `adminGrades` 查询 | ⏳ 待 core-edu 实现 |
| 12 | gRPC `ListDepartments(schoolId)` :50053 | `adminDepartments` 查询 | ⏳ 待 core-edu 实现 |
| 13 | gRPC `ListAcademicYears()` :50053 | `adminAcademicYears` 查询 | ⏳ 待 core-edu 实现 |
**当前状态**：teacher-bff 中 `CORE_EDU_GRPC_TARGET` 留空，相关查询走降级模式 B（返回空结果 + warning 日志）。
### 2.3 content 服务（ai08 负责）— P1
| # | 依赖项 | 用途 | 状态 |
| --- | ---------------------------------------- | ----------------------- | ------------------ |
| 1 | gRPC `GetKnowledgePath(classId)` :50054 | `knowledgePath` 查询 | ⏳ 待 content 实现 |
| 2 | gRPC `ListTextbooks()` :50054 | 教材列表 | ⏳ 待 content 实现 |
| 3 | gRPC `ListChapters(textbookId)` :50054 | 章节目录 | ⏳ 待 content 实现 |
| 4 | gRPC `ListLessonPlans(teacherId)` :50054 | `adminLessonPlans` 查询 | ⏳ 待 content 实现 |
| 5 | gRPC `ListCoursePlans(classId)` :50054 | `adminCoursePlans` 查询 | ⏳ 待 content 实现 |
### 2.4 data-ana 服务（ai11 负责）— P1
| # | 依赖项 | 用途 | 状态 |
| --- | ----------------------------------------- | ------------------------- | ------------------- |
| 1 | gRPC `GetStudentWeakness(classId)` :50055 | `studentWeakness` 查询 | ⏳ 待 data-ana 实现 |
| 2 | gRPC `GetLearningTrend(classId)` :50055 | `learningTrend` 查询 | ⏳ 待 data-ana 实现 |
| 3 | gRPC `GetGradeInsights(gradeId)` :50055 | `adminGradeInsights` 查询 | ⏳ 待 data-ana 实现 |
### 2.5 msg 服务（ai10 负责）— P1
| # | 依赖项 | 用途 | 状态 |
| --- | --------------------------------------- | --------------------------------- | -------------- |
| 1 | gRPC `ListNotifications(userId)` :50056 | `notifications` 查询 | ⏳ 待 msg 实现 |
| 2 | gRPC `MarkNotificationRead(id)` :50056 | `markNotificationAsRead` mutation | ⏳ 待 msg 实现 |
| 3 | gRPC `ListAnnouncements(filter)` :50056 | `adminAnnouncements` 查询 | ⏳ 待 msg 实现 |
| 4 | gRPC `CreateAnnouncement(input)` :50056 | `createAnnouncement` mutation | ⏳ 待 msg 实现 |
| 5 | gRPC `PublishAnnouncement(id)` :50056 | `publishAnnouncement` mutation | ⏳ 待 msg 实现 |
### 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 `ListAiProviders()` :50058 | `aiProviders` 查询 | ⏳ 待 ai 实现 |
| 4 | gRPC `GetAiUsage()` :50058 | `aiUsage` 查询 | ⏳ 待 ai 实现 |
### 2.7 Redis（基础设施）— P0
| 项 | 内容 |
| -------- | ------------------------------------- |
| 依赖内容 | /readyz 探针 + DataLoader 缓存（P4+） |
| 端点 | `redis://edu-redis:6379` |
| 当前状态 | ✅ 本地 Docker edu-redis 已就绪 |
### 2.8 Kafka（基础设施）— P2
| 项 | 内容 |
| -------- | --------------------------------------- |
| 依赖内容 | 可选：消费领域事件用于读模型刷新（P3+） |
| 端点 | `kafka:29092` |
| 当前状态 | ✅ 本地 Docker edu-kafka 已就绪 |
---
## 3. 下游依赖（谁依赖 teacher-bff）
### 3.1 admin-portal（ai16 负责）— P0
| 能力 | 配置 | 状态 |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `POST /graphql` :3003 | admin-portal GraphQL 代理目标 | ✅ 已就绪 |
| 40 Query 字段（扁平命名） | currentUser/adminUsers/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 + teacher 域 14 个 | ✅ 全部实现 |
| 20 Mutation 字段（扁平命名） | createUser/updateUser/toggleUserStatus/createRole/updateRolePermissions/updateViewport/updateSystemSettings/createAnnouncement/publishAnnouncement/archiveAnnouncement/toggleAnnouncementPin/generateInvitationCodes/deleteInvitationCodes/deleteFiles/updateAiProvider + teacher 域 5 个 | ✅ 全部实现 |
| x-user-data-scope header 透传 | admin 角色 data_scope=all 跳过 iam 权限校验 | ✅ 已实现 |
| 降级模式 B | 未就绪下游返回空结果 + warning | ✅ 已实现 |
**portal 需求来源**：`apps/admin-portal/docs/nextstep.md` §2.2
### 3.2 teacher-portal（ai13 负责）— P0
| 能力 | 配置 | 状态 |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `POST /graphql` :3003 | teacher-portal GraphQL 代理目标 | ✅ 已就绪 |
| teacher 域 14 Query | dashboard/viewports/me/classes/class/exams/homework/grades/knowledgePath/classPerformance/studentWeakness/learningTrend/notifications | ✅ 全部实现 |
| teacher 域 5 Mutation | createExam/assignHomework/recordGrade/generateQuestion/markNotificationAsRead | ✅ 全部实现 |
| SSE `/v1/teacher/ai/chat/stream` | AI 对话流式透传 | ✅ 已实现（ai-chat-sse.controller.ts） |
| Zod 输入验证 | createExam/assignHomework/recordGrade/generateQuestion | ✅ 已实现 |
**portal 需求来源**：`apps/teacher-portal/nextstep.md`
### 3.3 api-gateway（ai01 负责）— P0
| 能力 | 配置 | 状态 |
| ----------------------------- | ----------------------------------------------------- | --------------------- |
| `/api/v1/teacher/*` 反向代理 | → teacher-bff:3003/*（路径重写剥离 /api/v1/teacher） | ✅ api-gateway 已配置 |
| `/api/admin/graphql` 反向代理 | → teacher-bff:3003/graphql（路径重写剥离 /api/admin） | ✅ api-gateway 已配置 |
| `GET /healthz` 端点 | /readyz 下游健康检查 | ✅ 已实现 |
| `GET /readyz` 端点 | iam gRPC + Redis 健康检查 | ✅ 已实现 |
| `GET /metrics` 端点 | Prometheus 指标 | ✅ 已实现 |
---
## 4. GraphQL Schema 清单
### 4.1 Query 字段（40 个）
**Teacher 域（14 个）**：dashboard / viewports / me / classes / class / exams / homework / grades / knowledgePath / classPerformance / studentWeakness / learningTrend / notifications / serverTime
**Admin 域（26 个）**：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
### 4.2 Mutation 字段（20 个）
**Teacher 域（5 个）**：createExam / assignHomework / recordGrade / generateQuestion / markNotificationAsRead
**Admin 域（15 个）**：createUser / updateUser / toggleUserStatus / createRole / updateRolePermissions / updateViewport / updateSystemSettings / createAnnouncement / publishAnnouncement / archiveAnnouncement / toggleAnnouncementPin / generateInvitationCodes / deleteInvitationCodes / deleteFiles / updateAiProvider
### 4.3 Schema 文件位置
- `packages/shared-ts/contracts/graphql/teacher-bff.schema.graphql`（SDL 定义）
---
## 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 | ⏳ |
### 6.2 P6 硬化任务
| # | 工作项 | 状态 |
| --- | ----------------------------- | ------------------------------- |
| 1 | DataLoader 批量查询（防 N+1） | ⏳ 待下游就绪后实现 |
| 2 | Redis 多层缓存 | ⏳ 待下游就绪后实现 |
| 3 | 熔断器（opossum）配置 | ✅ 已实现（circuit-breaker.ts） |
| 4 | OTel trace 上报 | ✅ 已实现（tracer.ts） |
| 5 | Prometheus 指标 | ✅ 已实现（metrics.ts） |
---
## 7. 已完成项汇总
| 工作项 | 状态 | 验证方式 |
| -------------------------------- | ---- | --------------------------------------------------------------------------------------------------- |
| P2 核心 5 Query | ✅ | typecheck + lint + Docker 联调 |
| P3 teacher 域 Query/Mutation | ✅ | typecheck + lint + Docker 联调 |
| P4 学习分析 Query | ✅ | typecheck + lint |
| P5 通知 + AI Query/Mutation | ✅ | typecheck + lint |
| 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 熔断器（opossum） | ✅ | typecheck |
| P6 SSE 流式透传 | ✅ | typecheck |
| Docker 镜像构建 | ✅ | edu-test-teacher-bff:latest（v2 alpine + bcryptjs） |
| Docker 容器运行 | ✅ | /healthz 200 + /readyz 200 |
| 真实 iam 联调（无 mock） | ✅ | currentUser/me/adminRoles/adminPermissions/auditLogs/adminDashboard/systemSettings 全部返回真实数据 |
| `me` 查询 dataScope 修复（v2） | ✅ | teacher.service.ts 使用 userInfo.dataScope，Docker 验证返回 ALL |
| DataScope 大小写转换（v2） | ✅ | iam-grpc.client.ts toUpperCase()，Docker 验证 GraphQL enum 正常解析 |
| IamModule 客户端选择修复（v2） | ✅ | IAM_GRPC_TARGET 配置后强制 gRPC，DEV_MODE 不再触发 mock |
---
## 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 |
| `services/teacher-bff/src/teacher/teacher.service.ts` | teacher 域业务逻辑层 |
| `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/types.ts` | CallContext（含 dataScope 字段） |
| `services/teacher-bff/src/clients/grpc/grpc.factory.ts` | gRPC 客户端工厂 |
| `services/teacher-bff/Dockerfile` | Docker 构建（含 shared-ts 预编译） |
| `packages/shared-ts/contracts/graphql/teacher-bff.schema.graphql` | GraphQL schema 契约 |
| `packages/shared-proto/proto/iam.proto` | iam gRPC proto 契约 |
---
**本文件由 ai03 维护，上游/下游工作项请各负责 AI 完成后通知 ai03 更新状态。**