# core-edu 教学核心服务

> P3 核心教学阶段骨架 | 端口 3004

## 职责

core-edu 是教学核心限界上下文，合并 P1 的 classes 域，管理考试 / 作业 / 成绩聚合。
覆盖教学全链路：考试发布、作业提交、成绩录入与查询。

## 模块结构

```
src/
├─ config/           # env / database / kafka
├─ shared/
│  ├─ outbox/        # 事务性发件箱（schema + repository + publisher）
│  ├─ errors/        # 应用错误 + 全局错误过滤器
│  └─ observability/ # logger / metrics / tracer
├─ middleware/       # auth.middleware / permission.guard
├─ classes/          # P3 待合并（骨架）
├─ exams/            # 考试域
├─ homework/         # 作业域
├─ grades/           # 成绩域
├─ app.module.ts
└─ main.ts
```

## 关键机制

- **Outbox 模式**：写业务数据同事务写 `core_edu_outbox`，OutboxPublisher 定时扫描并发送到 Kafka，保证事件可靠投递。
- **Kafka 集成**：idempotent + transactional producer，按 eventType 路由到 `edu.{domain}.events` 主题。
- **事件契约**：见 `packages/shared-proto/proto/events.proto`。

## 开发

```bash
pnpm install
pnpm dev          # 端口 3004
pnpm typecheck
pnpm lint
pnpm test
```

## 环境变量

| 变量                          | 说明                          | 默认           |
| ----------------------------- | ----------------------------- | -------------- |
| `PORT`                        | 服务端口                      | 3004           |
| `DATABASE_URL`                | MySQL 连接串                  | -              |
| `KAFKA_BROKERS`               | Kafka broker 列表（逗号分隔） | localhost:9092 |
| `JWT_SECRET`                  | JWT 密钥                      | -              |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP 上报地址（可选）         | -              |

## 健康检查

| 端点           | 用途                                              | 鉴权 |
| -------------- | ------------------------------------------------- | ---- |
| `GET /healthz` | 存活探针（liveness），仅返回进程状态，不检查依赖  | 无   |
| `GET /readyz`  | 就绪探针（readiness），检查 DB 连接，失败返回 503 | 无   |

实现见 `src/shared/health/health.controller.ts`，5 个 NestJS 服务（iam/core-edu/content/msg/classes）一致。