# core-edu 下一步工作与上下游依赖（v2） > 模块：core-edu（教学核心服务，HTTP 3004 + gRPC 50053） > 更新日期：2026-07-14（v2：P3.14 考试实时事件完成 + 上下游依赖确认） > 状态：**9 Service / 43 RPC 全部就绪，本地 Docker 27/27 smoke test 通过** --- ## 1. 本轮完成工作 ### 1.1 P3.14 考试实时事件（3 个新 RPC + 3 个新 Kafka 事件） 下游 push-gateway / student-bff / student-portal 明确要求 core-edu 发布 3 类考试实时事件，用于 WebSocket 推送。本轮已完成实现： | RPC | 触发场景 | Kafka 事件 | Topic | | ---------------------------------- | ---------------- | ------------------------- | -------------------------------------- | | `ExamService.ExtendExam` | 教师延长考试时间 | `exam.extended` | `edu.teaching.exam.extended` | | `ExamService.ForceSubmitExam` | 教师强制收卷 | `exam.force_submitted` | `edu.teaching.exam.force_submitted` | | `ExamService.ReorderExamQuestions` | 教师调整题目顺序 | `exam.question_reordered` | `edu.teaching.exam.question_reordered` | 实现方式： - proto 契约：在 `core_edu.proto` ExamService 中新增 3 个 RPC + 对应 message - 服务层：[exams.service.ts](file:///e:/Desktop/Edu/services/core-edu/src/exams/exams.service.ts) 新增 `extendExam` / `forceSubmitExam` / `reorderExamQuestions` 方法 - 事件发布：通过 Outbox 模式事务内写入 `core_edu_outbox` 表，OutboxPublisher 轮询投递到 Kafka - gRPC handler：[grpc.server.ts](file:///e:/Desktop/Edu/services/core-edu/src/grpc/grpc.server.ts) 注册 3 个新 handler - TOPIC_MAP：[outbox.publisher.ts](file:///e:/Desktop/Edu/services/core-edu/src/shared/outbox/outbox.publisher.ts) 新增 3 个事件类型映射 ### 1.2 修复 pino 导入错误 [logger.ts](file:///e:/Desktop/Edu/services/core-edu/src/shared/observability/logger.ts) 从 `import pino from 'pino'` 改为 `import { pino } from 'pino'`，与其他服务一致。 ### 1.3 验证结果 ``` 镜像：edu/core-edu:test 容器：edu-core-edu-test（DEV_MODE=true, HTTP 13004→3004 + gRPC 50053） smoke test：27/27 PASS（含 3 个 P3.14 新 RPC） ``` --- ## 2. 上下游依赖确认 ### 2.1 下游模块对 core-edu 的依赖状态 | 下游模块 | 依赖类型 | 需求 | core-edu 状态 | | -------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | teacher-bff | gRPC :50053 | 11 个 RPC（ListClasses/ListExamsByClass/ListHomeworkByClass/ListGradesByExam/ListStudentsByClass/GetExam/GetHomework/CreateExam/AssignHomework/RecordGrade/GetClassPerformance） | ✅ 全部就绪（teacher-bff 文档过时，实际全部已实现） | | student-bff | gRPC :50053 | 15 个 RPC（含 P3.13 新增 SaveExamDraft/RecordExamViolation/GetScheduleByStudent/LeaveRequest×3/GetReportCard） | ✅ 全部就绪 | | parent-bff | gRPC :50053 | 3 个 RPC 就绪 + 7 个待补全（详见 §2.2） | ⚠️ 部分就绪（详见 §2.2） | | api-gateway | HTTP :3004 | REST 代理 /api/v1/{classes,exams,homework,grades}/* | ✅ 就绪 | | push-gateway | Kafka | 3 个考试实时事件（ExamExtended/ExamForceSubmitted/ExamQuestionReordered） | ✅ 已实现（P3.14） | | msg | Kafka | 5 个 teaching 事件（exam.published/homework.assigned/grade.recorded/attendance.recorded 等） | ✅ 已实现 | | data-ana | CDC binlog | MySQL binlog（grades/exams/homework/attendance/classes 表） | ✅ MySQL 就绪（Debezium 由 infra 部署） | | admin-portal | 间接（经 teacher-bff） | AdminService 4 RPC | ✅ 就绪（stub） | | student-portal | 间接（经 student-bff） | 10 个 RPC + 3 个考试事件 | ✅ 全部就绪 | | parent-portal | 间接（经 parent-bff） | 7 个 Query + 2 个 Mutation | ⚠️ 部分就绪（详见 §2.2） | ### 2.2 parent-bff 待澄清项（不需要 core-edu 新增 RPC） parent-bff nextstep-v2.md §6.3 列出 7 个"待补全"RPC，经核对全部可由现有 RPC 满足： | parent-bff 提议 | core-edu 现有实现 | 澄清 | | ----------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `ClassService.GetClass`（ISSUE-008） | ✅ `ClassService.GetClass` | proto 已定义，已实现，ISSUE-008 已解决 | | `AttendanceService.ListAttendance` | ✅ `AttendanceService.ListAttendanceByClass` 或 `ListAttendanceByStudent` | parent-bff 按班级或按学生查询，两个 RPC 已实现 | | `ExamResultService.GetExamResult`（新 Service） | ✅ `ExamService.GetExam` + `GradeService.ListGradesByExam` 组合 | 不需要新 Service，考试结果 = 考试详情 + 成绩列表 | | `ReportCardService.GetReportCard`（新 Service） | ✅ `GradeService.GetReportCard` | 不需要新 Service，已在 GradeService 中实现 | | `LeaveRequestService.List/Create` | ✅ `ListLeaveRequestsByStudent` + `CreateLeaveRequest` | 家长视角通过 `studentId=childId` 参数实现 | | `AcademicYearService.List`（新 Service） | ✅ `AdminService.ListAcademicYears` | 不需要新 Service，已在 AdminService 中实现 | | `ExportService.ExportGrades`（新 Service） | ✅ `GradeService.ListGradesByStudent` | 导出属 BFF/Portal 层格式化能力，core-edu 提供数据，BFF 负责格式化 | **结论：core-edu 不需要新增任何 RPC 或 Service。** parent-bff 文档中提议的新 Service 均可由现有 9 Service / 43 RPC 组合满足。 ### 2.3 Kafka topic 名协调结论 push-gateway 期望 topic `edu.notify.notification.sent`，student-bff/student-portal 期望 topic `edu.exam.events`。 **协调结论：core-edu 遵循现有 `edu.teaching.exam.*` 命名规范，不改动。** 正确的事件流： ``` core-edu → edu.teaching.exam.extended → msg 消费 → edu.notify.notification.sent → push-gateway → WebSocket ``` - core-edu 发布到 `edu.teaching.exam.*`（遵循 outbox.publisher.ts TOPIC_MAP 规范） - msg 服务负责消费 `edu.teaching.exam.*` 并转发到 `edu.notify.notification.*` - push-gateway 消费 `edu.notify.notification.*` - student-bff 应消费 `edu.teaching.exam.*`（而不是期望 core-edu 直接发布到 `edu.exam.events`） ### 2.4 事件 payload 字段对齐（msg 服务需求） msg nextstep.md §6 要求 core-edu 发布的事件 payload 字段名与 msg consumer 对齐。core-edu 当前事件 payload 遵循 `event-builder.ts` 的标准格式： ```json { "event_id": "UUID", "aggregate_id": "examId", "event_type": "exam.extended", "occurred_at": 1234567890, "payload": { "examId": "...", "classId": "...", "subjectId": "...", "extensionSeconds": 300, "newDuration": 7200 }, "metadata": { "schema_version": "v1", "trace_id": "...", "user_id": "..." } } ``` msg 服务需按此结构消费。字段名使用驼峰命名（与 events.proto ExamEvent message 的 snake_case 不同，因为 Outbox payload 是 JSON 序列化，不经过 proto 编码）。 --- ## 3. core-edu 需要上下游实现的工作 ### 3.1 需要上游（同层级）实现 | 上游模块 | 需求 | 状态 | | -------- | ------------------------------------------------------------------------ | ----------------------- | | iam | gRPC :50052 — 用户信息查询（DashboardService 学生数统计需要 IAM 集成） | ⏳ 待 iam gRPC 就绪 | | content | gRPC :50054 — 知识点关联（ClassPerformance 学科名需要 content 服务集成） | ⏳ 待 content gRPC 就绪 | | data-ana | Kafka `edu.insight.mastery.updated` — 掌握度事件消费（P4 演进） | ⏳ 待 data-ana 就绪 | | msg | gRPC :50056 — 消息服务联调（P5 演进） | ⏳ 待 msg gRPC 就绪 | | infra | Debezium Connect 部署 — CDC 管道（data-ana 依赖） | ⏳ 待 infra 部署 | | infra | Temporal server 部署 — 工作流试点（P3.10） | ⏳ 待 infra 部署 | ### 3.2 需要下游实现的工作 | 下游模块 | 需求 | 说明 | | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | msg | 消费 `edu.teaching.exam.extended` / `edu.teaching.exam.force_submitted` / `edu.teaching.exam.question_reordered` 三个新 topic | msg 需在 consumer 中订阅这 3 个 topic，生成通知后发布到 `edu.notify.notification.*` | | push-gateway | 消费 `edu.notify.notification.sent`（由 msg 转发） | push-gateway 不直接消费 core-edu 的 topic，应消费 msg 转发后的通知 topic | | student-bff | 消费 `edu.teaching.exam.*` 三个新 topic（或经 msg 转发） | student-bff EventSubscriber 需订阅正确的 topic 名 | | teacher-bff | 更新文档：11 个 RPC 全部已实现，不需要 mock 降级 | teacher-bff nextstep-v2.md §2.2 标注的"待实现"全部过时 | | parent-bff | 更新文档：7 个"待补全"RPC 全部可由现有 RPC 满足 | parent-bff 不需要 core-edu 新增 Service，按 §2.2 澄清映射调用现有 RPC | --- ## 4. 就绪信号 | 信号 | 状态 | 说明 | | ------------------------------- | ---- | -------------------------------------------- | | HTTP :3004 /healthz + /readyz | ✅ | 200，db=ok, redis=ok, kafka=ok | | gRPC :50053 9 Service / 43 RPC | ✅ | 27/27 smoke test 通过 | | Kafka 事件发布（14 个事件类型） | ✅ | 含 3 个 P3.14 新增考试实时事件 | | Outbox 模式 | ✅ | 事务内写入 + 独立 publisher 投递 | | Docker 镜像 | ✅ | edu/core-edu:test，单阶段构建 node:22-alpine | ### 4.1 完整 RPC 清单（43 RPC） | Service | RPC 数 | RPC 列表 | | ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ExamService | 13 | CreateExam, GetExam, ListExamsByClass, UpdateExam, DeleteExam, PublishExam, SubmitExam, GradeExam, SaveExamDraft, RecordExamViolation, **ExtendExam**, **ForceSubmitExam**, **ReorderExamQuestions** | | HomeworkService | 5 | AssignHomework, GetHomework, ListHomeworkByClass, SubmitHomework, GradeHomework | | GradeService | 7 | RecordGrade, GetGrade, ListGradesByStudent, ListGradesByExam, ListGradesByHomework, UpdateGrade, GetReportCard | | ClassService | 4 | GetClass, GetClassesByTeacher, BatchGetClasses, ListStudentsByClass | | AttendanceService | 4 | RecordAttendance, GetAttendance, ListAttendanceByStudent, ListAttendanceByClass | | ScheduleService | 1 | GetScheduleByStudent | | LeaveRequestService | 3 | ListLeaveRequestsByStudent, CreateLeaveRequest, CancelLeaveRequest | | DashboardService | 2 | GetDashboard, GetClassPerformance | | AdminService | 4 | ListSchools, ListGradeLevels, ListDepartments, ListAcademicYears | ### 4.2 完整 Kafka 事件清单（14 个事件类型） | 事件类型 | Topic | 消费方 | | --------------------------- | ---------------------------------------- | --------------------------------------- | | exam.created | edu.teaching.exam.created | msg, data-ana(CDC) | | exam.updated | edu.teaching.exam.updated | msg, data-ana(CDC) | | exam.published | edu.teaching.exam.published | msg | | exam.submitted | edu.teaching.exam.submitted | msg | | exam.graded | edu.teaching.exam.graded | msg | | exam.deleted | edu.teaching.exam.deleted | msg | | **exam.extended** | **edu.teaching.exam.extended** | **msg → push-gateway → student-portal** | | **exam.force_submitted** | **edu.teaching.exam.force_submitted** | **msg → push-gateway → student-portal** | | **exam.question_reordered** | **edu.teaching.exam.question_reordered** | **msg → push-gateway → student-portal** | | homework.assigned | edu.teaching.homework.assigned | msg | | homework.submitted | edu.teaching.homework.submitted | msg | | homework.graded | edu.teaching.homework.graded | msg | | grade.recorded | edu.teaching.grade.recorded | msg | | grade.updated | edu.teaching.grade.updated | msg | | attendance.recorded | edu.teaching.attendance.recorded | msg | --- ## 5. 后续演进任务（不阻塞下游） | 任务 | 优先级 | 阻塞条件 | | --------------------------------------------- | ------ | ----------------------------- | | P3.1 database.ts 改为 getDb() 函数式 | P3 | 无（技术债，14 个文件需重构） | | P3.10 Temporal 工作流试点 | P3 | Temporal server 部署（infra） | | P4.1 消费 data-ana mastery 事件 | P4 | data-ana gRPC 50055 就绪 | | P4.2 content gRPC 调用（知识点关联） | P4 | content gRPC 50054 就绪 | | P4.3 iam gRPC 调用（DashboardService 学生数） | P4 | iam gRPC 50052 就绪 | | P5.1 msg 事件消费联调 | P5 | msg gRPC 50056 就绪 | | P6.1 /readyz 硬化（+Temporal 探针） | P6 | Temporal 部署 | --- **core-edu P3.14 完成。9 Service / 43 RPC + 14 Kafka 事件全部就绪，本地 Docker 27/27 smoke test 通过（无 mock 数据）。下游 9 模块可基于此进行端到端联调。后续 P4+ 任务等待 iam/content/data-ana/msg 服务就绪。**