core-edu 下一步工作与上下游依赖
模块：core-edu（教学核心服务，HTTP 3004 + gRPC 50053）
负责人：ai08
更新日期：2026-07-13（v3：P3.13 12 个 RPC 补全完成 + 本地 Docker 24/24 smoke test 通过）
关联：core-edu_contract.md、core-edu_workline.md
1. 模块当前状态
core-edu 是教学核心服务，承载 exams / homework / grades / attendance / scheduling / classes 六个域，提供 HTTP REST + gRPC 双入口。
1.1 已完成
| 能力 |
状态 |
说明 |
| P2 服务骨架 + Outbox + REST CRUD |
✅ |
exams/homework/grades 三域 REST + Outbox 事件发布 |
| P3.2 TOPIC_MAP 重命名 edu.teaching.* |
✅ |
12 个 topic + payload 含 schema_version/event_id/occurred_at/metadata |
| P3.3 考试/作业状态机 + 成绩幂等 |
✅ |
scheme A（graded 统一、cancelled 终态、not_submitted 初始态） |
| P3.4 gRPC server 50053 + 5 Service 27 RPC |
✅ |
ExamService(8) + HomeworkService(5) + GradeService(6) + ClassService(4) + AttendanceService(4) |
| P3.5 排课考勤数据模型 + AttendanceService |
✅ |
schedule-conflict 冲突检测 + 幂等 |
| P3.6 成绩计算配置化 |
✅ |
GradeCalculator：weighted_average / sum / custom，scope 优先级 class > subject > school |
| P3.7 Redis 分布式锁 |
✅ |
homework submit 接入 acquireLock/releaseLock |
| P3.8 DataScope 下推 |
✅ |
datascope-injector.ts，auth.middleware 解析 x-user-data-scope 头 |
| P3.9 IAM 事件消费 |
✅ |
iam-consumer 订阅 teacher.assigned / class.created，幂等 |
| P3.11 classes 合并到 core-edu |
✅ |
classes/ 目录已迁入，ClassesModule 已接入 AppModule |
| P3.12 单元测试 |
✅ |
4 个测试文件共 78 个测试用例（状态机/GradeCalculator/ScheduleConflict） |
| 三支柱可观测性 |
✅ |
pino 结构化日志 + Prometheus /metrics + OpenTelemetry tracer |
| Docker 多阶段构建 |
✅ |
node:22-alpine，EXPOSE 3004 50053 |
| P3.13 下游缺失 RPC 补全（13 个） |
✅ |
9 Service / 40 RPC 全部就绪 |
1.2 待完成
| 任务 |
优先级 |
阻塞条件 |
| 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 就绪 |
| P5.1 msg 事件消费联调 |
P5 |
msg gRPC 50056 就绪 |
| P6.1 /readyz 硬化（+Temporal 探针） |
P6 |
Temporal 部署 |
1.3 本地 Docker 验证结果（2026-07-13 v3 - P3.13 完成）
测试环境：edu-core-edu-test 容器接入 edu-full_default 网络，直连 edu-mysql / edu-redis / edu-kafka
| 验证项 |
状态 |
说明 |
| Docker 镜像构建 |
✅ |
node:22-alpine + shared-proto + tsconfig.base.json + tsc 编译 |
| 容器启动 |
✅ |
HTTP + gRPC 双启动成功，日志 "HTTP + gRPC" |
| HTTP /healthz |
✅ |
200，{"status":"ok","service":"core-edu"} |
| HTTP /readyz |
✅ |
200，checks: db=ok, redis=ok, kafka=ok |
| gRPC 9 Service 可达 |
✅ |
24/24 RPC smoke test 全部通过 |
| proto 路径解析 |
✅ |
/app/proto/core_edu.proto（运行时复制） |
| Redis 连接 |
✅ |
分布式锁就绪 |
| Kafka 连接 |
✅ |
Outbox publisher + IAM consumer 已订阅 |
| gRPC smoke test |
✅ |
services/core-edu/test/grpc-smoke.mjs 24/24 PASS |
1.3.1 P3.13 新增 13 RPC smoke test 结果
| Service |
RPC |
结果 |
说明 |
| ExamService |
SaveExamDraft |
✅ |
upsert 成功（exam_id + student_id 唯一） |
| ExamService |
RecordExamViolation |
✅ |
违规记录写入 |
| GradeService |
GetReportCard |
✅ |
成绩聚合，按学科计算 A/B/C/D/F |
| ScheduleService |
GetScheduleByStudent |
✅ |
通过 attendance 反查 class_ids |
| LeaveRequestService |
ListLeaveRequestsByStudent |
✅ |
列表为空（无数据） |
| LeaveRequestService |
CreateLeaveRequest |
✅ |
返回 UUID（d5eeefba-...） |
| LeaveRequestService |
CancelLeaveRequest |
✅ |
状态机 pending→cancelled |
| DashboardService |
GetDashboard |
✅ |
教师仪表盘聚合 |
| DashboardService |
GetClassPerformance |
✅ |
班级绩效（NotFound 为正常业务错误） |
| AdminService |
ListSchools |
✅ |
stub 返回空数组（待 IAM 集成） |
| AdminService |
ListGradeLevels |
✅ |
stub 返回空数组 |
| AdminService |
ListDepartments |
✅ |
stub 返回空数组 |
| AdminService |
ListAcademicYears |
✅ |
stub 返回空数组 |
2. 上游依赖（core-edu 依赖谁）
2.1 MySQL（基础设施）— P0
| 项 |
内容 |
| 依赖内容 |
全部业务数据持久化（exams/homework/grades/attendance/schedule/classes/outbox） |
| 端点 |
mysql://edu-mysql:3306/next_edu_cloud |
| 当前状态 |
✅ 本地 Docker edu-mysql 已就绪 |
2.2 Redis（基础设施）— P0
| 项 |
内容 |
| 依赖内容 |
分布式锁（homework/exam submit 幂等）+ /readyz 探针 |
| 端点 |
redis://edu-redis:6379 |
| 当前状态 |
✅ 本地 Docker edu-redis 已就绪 |
| 降级策略 |
Redis 不可用时锁操作降级为 DB 唯一索引兜底 |
2.3 Kafka（基础设施）— P1
| 项 |
内容 |
| 依赖内容 |
Outbox 事件发布到 edu.teaching.* topic（12 个 topic） |
| 端点 |
kafka:29092 |
| 当前状态 |
✅ 本地 Docker edu-kafka 已就绪 |
| 降级策略 |
Kafka 不可用时事件暂存 outbox 表，服务不阻塞 |
2.4 iam 服务（ai06 负责）— P1
| # |
依赖项 |
用途 |
状态 |
| 1 |
gRPC GetUserInfo(userId) :50052 |
考勤录入时校验教师身份 |
⏳ 待 iam 就绪 |
| 2 |
gRPC GetChildrenByParent(parentId) :50052 |
家长端查询孩子成绩/考勤 |
⏳ 待 iam 就绪 |
| 3 |
Kafka edu.iam.user.created/updated/deleted |
IAM 事件消费（P3.9 已实现消费者） |
⏳ 待 iam 发布事件 |
| 4 |
GET /healthz :3002 |
/readyz 下游健康检查 |
⏳ |
环境变量：IAM_GRPC_TARGET=iam:50052
2.5 Temporal server（基础设施）— P3
| 项 |
内容 |
| 依赖内容 |
考试发布编排工作流（P3.10 试点） |
| 端点 |
temporal:7233 |
| 当前状态 |
⏳ 未部署 |
3. 下游依赖（谁依赖 core-edu）
3.1 teacher-bff（ai03 负责）— P0
| # |
gRPC RPC :50053 |
用途 |
状态 |
| 1 |
ExamService.ListExamsByClass |
exams 查询：考试列表 |
✅ 已实现 |
| 2 |
ExamService.CreateExam |
createExam mutation |
✅ 已实现 |
| 3 |
ExamService.GetExam |
考试详情 |
✅ 已实现 |
| 4 |
HomeworkService.ListHomeworkByClass |
homework 查询：作业列表 |
✅ 已实现 |
| 5 |
HomeworkService.AssignHomework |
assignHomework mutation |
✅ 已实现 |
| 6 |
HomeworkService.GetHomework |
作业详情 |
✅ 已实现 |
| 7 |
GradeService.RecordGrade |
recordGrade mutation |
✅ 已实现 |
| 8 |
GradeService.ListGradesByStudent |
grades 查询：成绩列表 |
✅ 已实现 |
| 9 |
ClassService.GetClass |
class 查询：班级详情 |
✅ 已实现 |
| 10 |
ClassService.GetClassesByTeacher |
classes 查询：教师班级列表 |
✅ 已实现 |
| 11 |
ClassService.ListStudentsByClass |
班级学生列表 |
✅ 已实现 |
| 12 |
AttendanceService.ListAttendanceByClass |
考勤列表 |
✅ 已实现 |
环境变量（teacher-bff 侧）：CORE_EDU_GRPC_TARGET=core-edu:50053
3.2 student-bff（ai04 负责）— P0
| # |
gRPC RPC :50053 |
用途 |
状态 |
| 1 |
ExamService.GetExam |
examDetail Query |
✅ 已实现 |
| 2 |
ExamService.SubmitExam |
submitExam Mutation |
✅ 已实现 |
| 3 |
HomeworkService.GetHomework |
homeworkDetail Query |
✅ 已实现 |
| 4 |
HomeworkService.SubmitHomework |
submitHomework Mutation |
✅ 已实现 |
| 5 |
GradeService.ListGradesByStudent |
myGrades Query |
✅ 已实现 |
| 6 |
AttendanceService.ListAttendanceByStudent |
myAttendance Query |
✅ 已实现 |
环境变量（student-bff 侧）：CORE_EDU_GRPC_TARGET=core-edu:50053
3.3 parent-bff（ai05 负责）— P0
| # |
gRPC RPC :50053 |
用途 |
状态 |
| 1 |
GradeService.ListGradesByStudent |
childGrades / childSummary |
✅ 已实现 |
| 2 |
HomeworkService.ListHomeworkByClass |
childHomework / childSummary |
✅ 已实现 |
| 3 |
ExamService.ListExamsByClass |
childExams / childSummary |
✅ 已实现 |
| 4 |
ClassService.GetClass |
班级信息 |
✅ 已实现 |
| 5 |
AttendanceService.ListAttendanceByStudent |
childAttendance |
✅ 已实现 |
环境变量（parent-bff 侧）：CORE_EDU_GRPC_TARGET=core-edu:50053
3.4 api-gateway（ai01 负责）— P1
| # |
依赖项 |
用途 |
状态 |
| 1 |
HTTP GET /healthz :3004 |
/readyz 下游健康检查 |
✅ 已实现 |
| 2 |
HTTP REST /api/v1/exams/* :3004 |
考试域 REST 代理 |
✅ 已实现 |
| 3 |
HTTP REST /api/v1/homework/* :3004 |
作业域 REST 代理 |
✅ 已实现 |
| 4 |
HTTP REST /api/v1/grades/* :3004 |
成绩域 REST 代理 |
✅ 已实现 |
| 5 |
HTTP REST /api/v1/classes/* :3004 |
班级域 REST 代理 |
✅ 已实现 |
3.5 msg 服务（ai10 负责）— P2
| # |
依赖项 |
用途 |
状态 |
| 1 |
Kafka edu.teaching.exam.published |
考试发布通知触发 |
✅ 已发布 |
| 2 |
Kafka edu.teaching.homework.assigned |
作业布置通知触发 |
✅ 已发布 |
| 3 |
Kafka edu.teaching.grade.recorded |
成绩录入通知触发 |
✅ 已发布 |
| 4 |
Kafka edu.teaching.attendance.recorded |
考勤异常通知触发 |
✅ 已发布 |
3.6 data-ana 服务（ai11 负责）— P2
| # |
依赖项 |
用途 |
状态 |
| 1 |
Kafka edu.teaching.*（全量 12 topic） |
CDC 数据分析消费 |
✅ 已发布 |
| 2 |
gRPC ExamService.GetExam :50053 |
考试详情查询（P4 联调） |
✅ 已实现 |
3.7 下游 9 模块缺失 RPC 清单（v2 新增，2026-07-13）
来源：4 个 portal + 2 个 gateway + 3 个 BFF 的 nextstep.md 依赖分析
3.7.1 teacher-bff（ai03）缺失 RPC（7 个）
| # |
RPC |
用途 |
当前状态 |
计划 |
| 1 |
ExamService.SaveExamDraft |
学生考试草稿保存 |
❌ 缺失 |
新增 |
| 2 |
GradeService.GetReportCard |
学生成绩报告卡 |
❌ 缺失 |
新增 |
| 3 |
ScheduleService.GetScheduleByStudent |
学生课表 |
❌ 缺失 |
新增 |
| 4 |
LeaveRequestService.ListLeaveRequestsByStudent |
学生请假列表 |
❌ 缺失 |
新增 |
| 5 |
LeaveRequestService.CreateLeaveRequest |
创建请假 |
❌ 缺失 |
新增 |
| 6 |
LeaveRequestService.CancelLeaveRequest |
取消请假 |
❌ 缺失 |
新增 |
| 7 |
DashboardService.GetDashboard(teacherId) |
教师仪表盘聚合 |
❌ 缺失 |
新增 |
| 8 |
DashboardService.GetClassPerformance(classId) |
班级绩效聚合 |
❌ 缺失 |
新增 |
| 9 |
AdminService.ListSchools |
学校列表（admin 域） |
❌ 缺失 |
新增（聚合 stub） |
| 10 |
AdminService.ListGradeLevels(schoolId) |
年级列表（admin 域） |
❌ 缺失 |
新增（聚合 stub） |
| 11 |
AdminService.ListDepartments(schoolId) |
部门列表（admin 域） |
❌ 缺失 |
新增（聚合 stub） |
| 12 |
AdminService.ListAcademicYears |
学年列表（admin 域） |
❌ 缺失 |
新增（聚合 stub） |
3.7.2 student-bff（ai04）缺失 RPC（7 个）
| # |
RPC |
用途 |
当前状态 |
| 1 |
ExamService.SaveExamDraft |
saveExamDraft Mutation |
❌ 缺失（同 teacher-bff） |
| 2 |
ExamService.RecordExamViolation |
recordExamViolation Mutation |
❌ 缺失（新增） |
| 3 |
ScheduleService.GetScheduleByStudent |
mySchedule Query |
❌ 缺失（同 teacher-bff） |
| 4 |
LeaveRequestService.ListLeaveRequestsByStudent |
myLeaveRequests Query |
❌ 缺失（同 teacher-bff） |
| 5 |
LeaveRequestService.CreateLeaveRequest |
createLeaveRequest Mutation |
❌ 缺失（同 teacher-bff） |
| 6 |
LeaveRequestService.CancelLeaveRequest |
cancelLeaveRequest Mutation |
❌ 缺失（同 teacher-bff） |
| 7 |
GradeService.GetReportCard |
myReportCard Query |
❌ 缺失（同 teacher-bff） |
3.7.3 parent-bff（ai05）缺失 RPC（5 个）
| # |
RPC |
用途 |
当前状态 |
| 1 |
AttendanceService.ListAttendanceByStudent |
childAttendance |
✅ 已实现 |
| 2 |
GradeService.GetReportCard |
childReportCard |
❌ 缺失（同上） |
| 3 |
LeaveRequestService.ListLeaveRequestsByStudent |
childLeaveRequests |
❌ 缺失（同上） |
| 4 |
LeaveRequestService.CreateLeaveRequest |
createLeaveRequest Mutation |
❌ 缺失（同上） |
| 5 |
AdminService.ListAcademicYears |
academicYears |
❌ 缺失（同上） |
3.7.4 api-gateway（ai01）依赖
| 依赖项 |
状态 |
HTTP GET /healthz :3004 |
✅ 已实现 |
HTTP REST /api/v1/exams/* :3004 |
✅ 已实现 |
HTTP REST /api/v1/homework/* :3004 |
✅ 已实现 |
HTTP REST /api/v1/grades/* :3004 |
✅ 已实现 |
HTTP REST /api/v1/classes/* :3004 |
✅ 已实现 |
3.7.5 4 个 portal（ai13/14/15/16）间接依赖
portal 不直接调用 core-edu，通过各自 BFF 转发。需求已在 §3.7.1-3.7.3 中体现。
3.7.6 潜在缺口说明（parent-bff/parent-portal 提及）
parent-bff §4.6 降级查询清单和 parent-portal §4.2 提到 ExamResultService 和 ExportService，这两个 Service 在 core-edu 9 Service / 40 RPC 清单中不存在。
| 下游提及的能力 |
core-edu 现状 |
归属判断 |
| 考试结果详情（ExamResultService） |
GradeService.GetReportCard 可承接成绩报告卡；ExamService.GetExam 返回考试基础信息 |
需 parent-bff 联调时确认是否需要独立 RPC，或由现有 RPC 组合 |
| 成绩导出（ExportService） |
无对应 RPC（导出属 BFF/Portal 层格式化能力） |
建议由 parent-bff 调用 GradeService.ListGradesByStudent + 本地格式化实现 |
结论：这两项不阻塞下游联调，core-edu 不新增 RPC，待 parent-bff 联调时协商归属。
4. 就绪信号
| 阶段 |
就绪信号 |
消费方 |
状态 |
| P2（已就绪） |
HTTP 3004 可访问 + /healthz + /readyz（DB 探针） |
teacher-bff（REST 调用） |
✅ |
| P3（核心） |
gRPC 50053 + 27 RPC + HealthService SERVING |
teacher-bff / student-bff / parent-bff / ai |
✅ |
| P3 子信号 1 |
ClassService 4 RPC 可调用 |
teacher-bff（班级列表） |
✅ |
| P3 子信号 2 |
ExamService 10 RPC 可调用（含 SaveExamDraft/RecordExamViolation） |
teacher-bff / student-bff / ai |
✅ |
| P3 子信号 3 |
HomeworkService 5 RPC 可调用 |
teacher-bff / student-bff |
✅ |
| P3 子信号 4 |
GradeService 7 RPC 可调用（含 GetReportCard） |
teacher-bff / student-bff / parent-bff |
✅ |
| P3 子信号 5 |
AttendanceService 4 RPC 可调用 |
parent-bff |
✅ |
| P3 子信号 6 |
edu.teaching.* topic 可发布（含 attendance.recorded） |
msg / data-ana / push-gateway |
✅ |
| P3.13（已就绪） |
gRPC 50053 + 40 RPC（9 Service）+ 24/24 smoke test |
teacher-bff / student-bff / parent-bff |
✅ |
| P3.13 子信号 1 |
ScheduleService.GetScheduleByStudent 可调用 |
teacher-bff / student-bff |
✅ |
| P3.13 子信号 2 |
LeaveRequestService 3 RPC 可调用 |
teacher-bff / student-bff / parent-bff |
✅ |
| P3.13 子信号 3 |
DashboardService 2 RPC 可调用 |
teacher-bff |
✅ |
| P3.13 子信号 4 |
AdminService 4 RPC 可调用（stub） |
teacher-bff / parent-bff |
✅ |
5. Docker 部署
5.1 镜像构建
5.2 容器启动
5.3 健康检查验证
5.4 环境变量清单
| 变量 |
必填 |
示例值 |
说明 |
PORT |
是 |
3004 |
HTTP 监听端口 |
GRPC_PORT |
是 |
50053 |
gRPC 监听端口 |
DATABASE_URL |
是 |
mysql://edu:pass@edu-mysql:3306/next_edu_cloud |
MySQL 连接串 |
REDIS_URL |
否 |
redis://edu-redis:6379 |
Redis 连接地址（缺失时降级） |
KAFKA_BROKERS |
否 |
kafka:29092 |
Kafka broker 地址（缺失时 outbox 暂存） |
JWT_SECRET |
否 |
— |
JWT 校验密钥（可选） |
DEV_MODE |
否 |
false |
开发模式（跳过部分校验） |
OTEL_EXPORTER_OTLP_ENDPOINT |
否 |
http://otel-collector:4318 |
OTLP 上报端点 |
LOG_LEVEL |
否 |
info |
日志级别 |
6. 关键文件路径
| 文件 |
用途 |
services/core-edu/src/main.ts |
服务入口（HTTP + gRPC 双启动，含 startGrpcServer） |
services/core-edu/src/grpc/grpc.server.ts |
gRPC server（9 Service / 40 RPC handler） |
services/core-edu/src/app.module.ts |
NestJS 根模块 |
services/core-edu/src/exams/exam-state-machine.ts |
考试状态机（纯函数） |
services/core-edu/src/homework/homework-state-machine.ts |
作业状态机（纯函数） |
services/core-edu/src/grades/grade-calculator.ts |
成绩计算器（scope 优先级） |
services/core-edu/src/scheduling/schedule-conflict.ts |
排课冲突检测（纯函数） |
services/core-edu/src/leave-requests/leave-requests.service.ts |
请假服务（P3.13 新增） |
services/core-edu/src/dashboard/dashboard.service.ts |
仪表盘聚合（P3.13 新增） |
services/core-edu/src/admin/admin.service.ts |
Admin 聚合 stub（P3.13 新增） |
services/core-edu/src/shared/outbox/outbox.publisher.ts |
Outbox 事件发布（TOPIC_MAP） |
services/core-edu/src/shared/datascope/datascope-injector.ts |
DataScope WHERE 注入 |
services/core-edu/src/config/database.ts |
MySQL 连接池 |
services/core-edu/src/config/kafka.ts |
Kafka producer |
services/core-edu/src/config/redis.ts |
Redis 客户端 + 分布式锁 |
services/core-edu/Dockerfile |
Docker 构建（单阶段，node:22-alpine + tsc） |
services/core-edu/test/grpc-smoke.mjs |
gRPC smoke test（24 RPC） |
packages/shared-proto/proto/core_edu.proto |
gRPC proto 契约（9 Service / 40 RPC） |
本文件由 ai08 维护。core-edu P3 核心功能 + P3.13 下游缺失 RPC 补全已全部完成（9 Service / 40 RPC 就绪），本地 Docker 24/24 smoke test 通过。下游 9 模块（4 portal + 2 gateway + 3 BFF）可基于此进行端到端联调。P4+ 任务等待 data-ana/content/msg 服务就绪。
