# 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 更新状态。**