317 lines
31 KiB
Markdown
317 lines
31 KiB
Markdown
# 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 更新状态。**
|