xiner/Edu

Files

SpecialX 7dd5c44406 feat(core-edu): admin/dashboard/leave-requests 模块 + gRPC + 状态机测试 + nextstep 文档

2026-07-14 15:56:10 +08:00

28 KiB

Raw Permalink Blame History

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

镜像：edu/core-edu:test（单阶段构建，node:22-alpine + tsc）
容器：edu-core-edu-test（DEV_MODE=true, HTTP 13004→3004 + gRPC 50053）

验证项	状态	说明
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 镜像构建

# 在仓库根目录执行（需要访问 packages/shared-proto + tsconfig.base.json）
docker build -t edu/core-edu:test -f services/core-edu/Dockerfile .

5.2 容器启动

docker run -d \
  --name edu-core-edu-test \
  --network edu-full_default \
  -p 13004:3004 -p 50053:50053 \
  -e PORT=3004 \
  -e GRPC_PORT=50053 \
  -e DATABASE_URL=mysql://edu:changeme@edu-mysql:3306/next_edu_cloud \
  -e REDIS_URL=redis://edu-redis:6379 \
  -e KAFKA_BROKERS=kafka:29092 \
  -e DEV_MODE=true \
  edu/core-edu:test

5.3 健康检查验证

# HTTP liveness
curl http://localhost:13004/healthz

# HTTP readiness（DB + Redis 探针）
curl -H "x-user-id: dev-teacher" -H "x-user-role: teacher" http://localhost:13004/readyz

# gRPC smoke test（24 RPC）
cd services/core-edu && node test/grpc-smoke.mjs
# 应输出：PASS: 24  FAIL: 0  TOTAL: 24

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 服务就绪。

28 KiB Raw Permalink Blame History Unescape Escape