2ba4250165
- monorepo: pnpm workspace + go.work + pyproject.toml + commitlint/husky - infra: docker-compose (minimal + full profiles) + init-sql + prometheus - arch-scan: multi-language scanner skeleton (TS/Go/Python/Proto) - shared-proto: buf v2 + classes.proto (ClassService CRUD contract) - api-gateway: Go/Gin + JWT HS256 auth + reverse proxy + request ID - classes: NestJS golden template (error system + observability + middleware + CRUD + tests) - teacher-portal: Next.js + paper-feel UI design system - CI/CD: 4 workflows (go/ts/py/proto) - docs: migration guide + project_rules + coding-standards + git-workflow + ui-design-system + 004 + 9 module READMEs + known-issues + spec/plan migration + roadmap
106 lines
3.3 KiB
Markdown
106 lines
3.3 KiB
Markdown
# core-edu 教学核心服务
|
||
|
||
> 版本：0.1（骨架）
|
||
> 日期：2026-07-07
|
||
> 状态：P3 待交付
|
||
> 关联文档：[架构影响地图](../../architecture/004_architecture_impact_map.md)
|
||
|
||
---
|
||
|
||
## 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. 架构图
|
||
|
||
```mermaid
|
||
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. 核心流程图
|
||
|
||
```mermaid
|
||
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 选型、考试并发策略。
|