Edu/docs/modules/core-edu/README.md

core-edu 教学核心服务

版本：0.1（骨架） 日期：2026-07-07 状态：P3 待交付 关联文档：架构影响地图

---

1. 模块职责

core-edu 是教学核心限界上下文，合并 P1 的 classes 域，管理 Class、Course、Assignment、Exam、Grade 等聚合。 覆盖教学全链路：班级管理、课程编排、作业布置与提交、考试发布与批改、成绩录入与查询。 是整个平台最大的业务服务，承载考试→作答→批改→成绩核心链路。

---

2. 技术栈

类别	技术	版本	用途
语言	TypeScript	5.5+	类型安全
框架	NestJS	10.x	依赖注入、模块化
ORM	Drizzle ORM	0.31+	数据访问
数据库	MySQL	8.x	写模型主库
缓存	Redis	7.x	读模型缓存
读模型	ClickHouse	-	学情宽表（P4 接入）
校验	Zod	3.23+	运行时校验
编排	Temporal	-	考试生命周期编排

---

3. 架构图

graph TB
    BFF[BFF 聚合层] -->|gRPC| CORE[core-edu 服务]
    CORE --> CLASS[Class 模块<br/>P3 合并]
    CORE --> COURSE[Course 模块]
    CORE --> ASSIGN[Assignment 模块]
    CORE --> EXAM[Exam 模块]
    CORE --> GRADE[Grade 模块]
    CORE -->[(MySQL)]
    CORE -->[(Redis)]
    CORE -->[(ClickHouse<br/>读模型)]
    CORE -.事件.-> K[(Kafka<br/>edu.teaching.*)]

待 P3 交付时补充完整的分层架构图与 CQRS 读写分离图。

---

4. 核心流程图

sequenceDiagram
    participant T as 教师
    participant BFF as BFF
    participant CORE as core-edu
    participant K as Kafka

    T->>BFF: 发布考试
    BFF->>CORE: gRPC PublishExam
    CORE->>CORE: 校验 + Outbox 写入
    CORE-->>BFF: 成功
    CORE->>K: edu.teaching.exam.published
    K->>K: Msg 通知学生 / DataAna 创建分析骨架

待 P3 交付时补充：作业提交流程、批改流程、成绩录入流程、考试生命周期 Saga。

---

5. 对外契约

• gRPC 服务：ClassService（P1 迁移）、CourseService、AssignmentService、ExamService、GradeService（待 P3 定义 protobuf）
• 领域事件：edu.teaching.assignment.submitted、edu.teaching.exam.published、edu.teaching.grade.recorded、edu.org.class.created
• 数据库表：classes、courses、assignments、submissions、exams、exam_responses、grades、outbox

待 P3 交付时补充完整 protobuf 定义与表结构。

---

6. 依赖关系

• 上游：teacher-bff、student-bff、parent-bff
• 下游：MySQL、Redis、ClickHouse（读模型）、Kafka、Temporal
• 跨服务：消费 iam 的 edu.identity.user.* 事件初始化关联；被 data-ana 消费学情事件

---

7. 架构约束

1. P3 合并 classes 服务后，protobuf 契约保持不变
2. 考试生命周期使用 Temporal Saga 编排，禁止单体事务
3. 成绩录入后必须发布事件触发 DataAna 掌握度更新
4. Outbox 模式强制，所有写操作同事务写 outbox

待 P3 交付时补充完整约束清单。

---

8. 架构决策

待 P3 交付时补充 ADR 记录，预计包括：classes 合并决策、Temporal 编排选型、CQRS 读模型 ClickHouse 选型、考试并发策略。