xiner/Edu

Files

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

2026-07-14 16:00:46 +08:00

38 KiB

Raw Blame History

teacher-bff 下一步工作与上下游依赖

模块：teacher-bff（教学场景域聚合层 BFF，GraphQL 聚合层，端口 3003）负责人：ai03 更新日期：2026-07-14（v2：schema v2 扩展 + 96 operations + Docker E2E 验证通过）关联文档：02-architecture-design.md、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 更新状态。

38 KiB Raw Blame History Unescape Escape