377 lines
28 KiB
Markdown
377 lines
28 KiB
Markdown
# 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](../../../docs/architecture/issues/contracts/core-edu_contract.md)、[core-edu_workline.md](../../../docs/architecture/issues/worklines/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 镜像构建
|
||
|
||
```bash
|
||
# 在仓库根目录执行（需要访问 packages/shared-proto + tsconfig.base.json）
|
||
docker build -t edu/core-edu:test -f services/core-edu/Dockerfile .
|
||
```
|
||
|
||
### 5.2 容器启动
|
||
|
||
```bash
|
||
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 健康检查验证
|
||
|
||
```bash
|
||
# 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 服务就绪。**
|