# core-edu 对接契约

> 负责人：ai08
> 关联：[matrix.md](./matrix.md)、[core_edu.proto](../../../packages/shared-proto/proto/core_edu.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)、[services/core-edu/docs/02-architecture-design.md](../../../services/core-edu/docs/02-architecture-design.md)、[objections/core-edu_issue.md](../objections/core-edu_issue.md)
> 状态说明：本契约按 P3 目标态描述。P2 已就绪部分标注 ✅，P3 待实施部分标注 ⏳（依赖 [objections/core-edu_issue.md](../objections/core-edu_issue.md) ISSUE-001 ~ ISSUE-006 仲裁结果）

---

## §1 我提供什么（对外接口）

### 1.1 gRPC 接口（P3 启用，端口 50053）

> 包名：`next_edu_cloud.core_edu.v1`（[coord-cross-review §2.1](../../coord-cross-review.md) 仲裁）
> 总计 5 Service / 27 RPC（含 P3 新增 5 RPC）
> 注：当前 `core_edu.proto` 实际仅 3 Service / 14 RPC，缺 ClassService + AttendanceService + P3 新增 RPC（见 [ISSUE-001](../objections/core-edu_issue.md#issue-001-ai08core_eduproto-实际状态与-coord-仲裁声称不一致p0)）

| Service | RPC | 请求 | 响应 | 状态 |
| ------- | --- | ---- | ---- | ---- |
| ClassService | GetClass | GetClassRequest | ClassInfo | ⏳ P3 |
| ClassService | GetClassesByTeacher | GetClassesByTeacherRequest | GetClassesByTeacherResponse | ⏳ P3 |
| ClassService | BatchGetClasses | BatchGetClassesRequest | BatchGetClassesResponse | ⏳ P3 |
| ClassService | ListStudentsByClass | ListStudentsByClassRequest | ListStudentsByClassResponse | ⏳ P3 |
| ExamService | CreateExam | CreateExamRequest | CreateExamResponse | ⏳ proto 已定义 |
| ExamService | GetExam | GetExamRequest | Exam | ⏳ proto 已定义 |
| ExamService | ListExamsByClass | ListExamsByClassRequest | ListExamsResponse | ⏳ proto 已定义 |
| ExamService | UpdateExam | UpdateExamRequest | UpdateExamResponse | ⏳ proto 已定义 |
| ExamService | DeleteExam | DeleteExamRequest | DeleteExamResponse | ⏳ proto 已定义 |
| ExamService | **PublishExam** | PublishExamRequest | PublishExamResponse | ⏳ P3 新增（proto 待补） |
| ExamService | **SubmitExam** | SubmitExamRequest（含 answers） | SubmitExamResponse | ⏳ P3 新增（proto 待补） |
| ExamService | **GradeExam** | GradeExamRequest | GradeExamResponse | ⏳ P3 新增（proto 待补） |
| HomeworkService | AssignHomework | AssignHomeworkRequest | AssignHomeworkResponse | ⏳ proto 已定义 |
| HomeworkService | GetHomework | GetHomeworkRequest | Homework | ⏳ proto 已定义 |
| HomeworkService | ListHomeworkByClass | ListHomeworkByClassRequest | ListHomeworkResponse | ⏳ proto 已定义 |
| HomeworkService | SubmitHomework | SubmitHomeworkRequest（**P3 增强含 answers**） | SubmitHomeworkResponse | ⏳ proto 已定义（缺 answers 字段） |
| HomeworkService | **GradeHomework** | GradeHomeworkRequest | GradeHomeworkResponse | ⏳ P3 新增（proto 待补） |
| GradeService | RecordGrade | RecordGradeRequest | RecordGradeResponse | ⏳ proto 已定义 |
| GradeService | GetGrade | GetGradeRequest | Grade | ⏳ proto 已定义 |
| GradeService | ListGradesByStudent | ListGradesByStudentRequest | ListGradesResponse | ⏳ proto 已定义 |
| GradeService | ListGradesByExam | ListGradesByExamRequest | ListGradesResponse | ⏳ proto 已定义 |
| GradeService | ListGradesByHomework | ListGradesByHomeworkRequest | ListGradesResponse | ⏳ proto 已定义 |
| GradeService | **UpdateGrade** | UpdateGradeRequest | UpdateGradeResponse | ⏳ P3 新增（proto 待补） |
| AttendanceService | **RecordAttendance** | RecordAttendanceRequest | RecordAttendanceResponse | ⏳ P3 新增（proto 待补） |
| AttendanceService | **GetAttendance** | GetAttendanceRequest | Attendance | ⏳ P3 新增（proto 待补） |
| AttendanceService | **ListAttendanceByStudent** | ListAttendanceByStudentRequest | ListAttendanceResponse | ⏳ P3 新增（proto 待补） |
| AttendanceService | **ListAttendanceByClass** | ListAttendanceByClassRequest | ListAttendanceResponse | ⏳ P3 新增（proto 待补） |
| HealthService | Check | grpc.health.v1.HealthCheckRequest | grpc.health.v1.HealthCheckResponse | ⏳ P3 |

**统计**：
- P2 基线（proto 已定义）：3 Service / 14 RPC（ExamService 5 + HomeworkService 4 + GradeService 5）
- P3 目标态：5 Service / 27 RPC（+ClassService 4 + AttendanceService 4 + P3 新增 5 RPC）
- 增量：13 RPC（ClassService 4 + AttendanceService 4 + PublishExam/SubmitExam/GradeExam/GradeHomework/UpdateGrade 5）

### 1.2 HTTP 端点（REST，端口 3004）

> 当前为 REST 入口（P2 已就绪），P3 启用 gRPC 后 REST 保留为 BFF 兼容入口
> 所有端点走 AuthMiddleware + PermissionGuard + Zod ValidationPipe + GlobalErrorFilter（ActionState 信封）

| Method | Path | 权限 | 状态 |
| ------ | ---- | ---- | ---- |
| POST | /exams | CORE_EDU_EXAM_CREATE | ✅ P2 |
| GET | /exams/:id | CORE_EDU_EXAM_READ | ✅ P2 |
| GET | /exams/class/:classId | CORE_EDU_EXAM_READ | ✅ P2 |
| PUT | /exams/:id | CORE_EDU_EXAM_UPDATE | ✅ P2 |
| DELETE | /exams/:id | CORE_EDU_EXAM_DELETE | ✅ P2 |
| POST | /exams/:id/publish | CORE_EDU_EXAM_PUBLISH | ⏳ P3 新增 |
| POST | /exams/:id/start | CORE_EDU_EXAM_SUBMIT | ⏳ P3 新增 |
| POST | /exams/:id/submit | CORE_EDU_EXAM_SUBMIT | ⏳ P3 新增 |
| POST | /exams/:id/grade | CORE_EDU_EXAM_GRADE | ⏳ P3 新增 |
| POST | /exams/:id/archive | CORE_EDU_EXAM_UPDATE | ⏳ P3 新增 |
| POST | /homework | CORE_EDU_HOMEWORK_CREATE | ✅ P2 |
| GET | /homework/:id | CORE_EDU_HOMEWORK_READ | ✅ P2 |
| GET | /homework/class/:classId | CORE_EDU_HOMEWORK_READ | ✅ P2 |
| POST | /homework/:id/submit | CORE_EDU_HOMEWORK_SUBMIT | ⏳ P3 增强（含 answers） |
| POST | /homework/:id/grade | CORE_EDU_HOMEWORK_GRADE | ⏳ P3 新增 |
| POST | /grades | CORE_EDU_GRADE_CREATE | ✅ P2 |
| GET | /grades/:id | CORE_EDU_GRADE_READ | ✅ P2 |
| GET | /grades/student/:studentId | CORE_EDU_GRADE_READ | ✅ P2 |
| GET | /grades/exam/:examId | CORE_EDU_GRADE_READ | ✅ P2 |
| GET | /grades/homework/:homeworkId | CORE_EDU_GRADE_READ | ✅ P2 |
| PUT | /grades/:id | CORE_EDU_GRADE_UPDATE | ⏳ P3 新增 |
| POST | /attendance | CORE_EDU_ATTENDANCE_CREATE | ⏳ P3 新增 |
| GET | /attendance/schedule/:scheduleId | CORE_EDU_ATTENDANCE_READ | ⏳ P3 新增 |
| GET | /attendance/student/:studentId | CORE_EDU_ATTENDANCE_READ | ⏳ P3 新增 |
| POST | /courses | CORE_EDU_COURSE_CREATE | ⏳ P3 新增 |
| POST | /schedules | CORE_EDU_SCHEDULE_CREATE | ⏳ P3 新增 |
| GET | /schedules/teacher/:teacherId | CORE_EDU_SCHEDULE_READ | ⏳ P3 新增 |
| GET | /schedules/class/:classId | CORE_EDU_SCHEDULE_READ | ⏳ P3 新增 |
| GET | /healthz | 无（liveness） | ✅ P2 |
| GET | /readyz | 无（readiness） | ✅ P2（P3 补 Redis/Kafka 探针） |
| GET | /metrics | 无（Prometheus） | ✅ P2 |

### 1.3 GraphQL schema（如 BFF）

不适用。core-edu 是业务服务，不提供 GraphQL。GraphQL 由 teacher-bff / student-bff / parent-bff 提供。

### 1.4 Kafka 事件发布

> Topic 命名遵循 [coord-cross-review §3.1](../../coord-cross-review.md#31-core-edu-教学事件-topic-命名双轨p0-最严重) 仲裁：`edu.teaching.<aggregate>.<action>`
> 所有事件 payload 必须含：`schema_version`（默认 `"v1"`）+ `event_id`（UUID）+ `occurred_at`（业务时间戳）+ `metadata: { traceId, userId }`
> 注：当前 `events.proto` 仍用旧 topic 命名 + 缺 schema_version 字段 + 缺 AttendanceEvent message（见 [ISSUE-002](../objections/core-edu_issue.md#issue-002-ai08eventsproto-未同步-coord-topic-命名仲裁p0)）

| Topic | Event（action） | 触发时机 | 消费方 | 状态 |
| ----- | --------------- | -------- | ------ | ---- |
| `edu.teaching.exam.created` | ExamEvent.created | CreateExam 事务内 | msg / data-ana / push-gateway | ⏳ P3（TOPIC_MAP 改名） |
| `edu.teaching.exam.updated` | ExamEvent.updated | UpdateExam | msg | ⏳ P3 |
| `edu.teaching.exam.deleted` | ExamEvent.deleted | DeleteExam（软删除） | data-ana | ⏳ P3 |
| `edu.teaching.exam.published` | ExamEvent.published | PublishExam（状态机转换） | msg / data-ana | ⏳ P3 新增 |
| `edu.teaching.exam.submitted` | ExamEvent.submitted | 学生提交答卷 | data-ana / msg | ⏳ P3 新增 |
| `edu.teaching.homework.assigned` | HomeworkEvent.assigned | AssignHomework | msg / data-ana | ⏳ P3 |
| `edu.teaching.homework.submitted` | HomeworkEvent.submitted | 学生提交作业 | data-ana / msg | ⏳ P3 |
| `edu.teaching.homework.graded` | HomeworkEvent.graded | 教师批改完成 | msg / data-ana | ⏳ P3 新增 |
| `edu.teaching.grade.recorded` | GradeEvent.recorded | RecordGrade | data-ana / msg / push-gateway / parent-bff | ⏳ P3 |
| `edu.teaching.grade.updated` | GradeEvent.updated | UpdateGrade | data-ana | ⏳ P3 新增 |
| `edu.teaching.attendance.recorded` | AttendanceEvent.recorded | RecordAttendance | data-ana / msg | ⏳ P3 新增（proto 待补 AttendanceEvent） |
| `edu.teaching.class.transferred` | ClassEvent.transferred | classes 合并后 | data-ana / msg | ⏳ P3（topic 待 ISSUE-004 仲裁） |

**注意**：
- `class.transferred` 的 topic 命名存在跨文档不一致（[ISSUE-004](../objections/core-edu_issue.md#issue-004-ai08classtransferred-事件-topic-三处不一致p1)），ai08 倾向 `edu.teaching.class.transferred`，待 coord 仲裁。
- 当前 `events.proto` 文件头注释仍用旧命名（`edu.exam.events` 等），需 coord 同步更新。

### 1.5 CDC 数据流（被动同步，无主动接口）

> core-edu 不主动配合 CDC，由 data-ana 通过 Debezium 监听 MySQL binlog 自动同步

| MySQL 表 | CDC topic | 消费方 | 用途 |
| -------- | --------- | ------ | ---- |
| core_edu_exams | `edu-cdc.next_edu_cloud.core_edu_exams` | data-ana | ClickHouse 宽表 |
| core_edu_homework | `edu-cdc.next_edu_cloud.core_edu_homework` | data-ana | ClickHouse 宽表 |
| core_edu_grades | `edu-cdc.next_edu_cloud.core_edu_grades` | data-ana | ClickHouse 宽表 |
| core_edu_attendance | `edu-cdc.next_edu_cloud.core_edu_attendance` | data-ana | ClickHouse 宽表 |

### 1.6 错误码前缀

`CORE_EDU_*`（[coord-cross-review §5.5](../../coord-cross-review.md#55-p1-问题core-edu-子模块前缀) 仲裁：子域统一 `CORE_EDU_*`，不再细分 `EXAMS_`/`HOMEWORK_`/`GRADES_`）

完整错误码清单见 [02-architecture-design.md §6.2](../../../services/core-edu/docs/02-architecture-design.md#62-错误码清单)。

### 1.7 响应信封

所有 HTTP/gRPC 响应遵循 ActionState 信封（[004 §11.5](../../004_architecture_impact_map.md)）：

```typescript
{
  success: boolean,
  data?: T,
  error?: { code: string, message: string, details?: unknown, traceId?: string }
}
```

---

## §2 我消费什么（依赖上游）

### 2.1 gRPC 调用（同步）

| 调用方 | 目标服务 | RPC | 用途 | 阶段 |
| ------ | -------- | --- | ---- | ---- |
| core-edu | content | ContentService.GetKnowledgePoints | 排课关联知识点（lessons.knowledge_point_ids 校验） | P4（content 就绪后） |
| core-edu | temporal | Workflow.start（examPublishWorkflow） | 考试发布编排工作流 | P3（Temporal 部署后） |

> 注：core-edu **不主动调 iam gRPC**，通过 Kafka 事件接收 iam 用户变更（见 §2.2）。
> P3 不调 content（题库 question_id 仅作外键引用，不校验存在性）。

### 2.2 Kafka 事件订阅（异步）

> Topic 命名遵循 [004 §7.2](../../004_architecture_impact_map.md#72-事件-topic-分类) 事件分类

| Topic | Event | 发布方 | 消费动作 | 幂等策略 | 阶段 |
| ----- | ----- | ------ | -------- | -------- | ---- |
| `edu.identity.user.created` | UserEvent.created | iam (ai06) | 初始化教师默认班级关联（写 core_edu_teacher_associations） | 唯一索引 (teacher_id, class_id, subject_id) | P3 |
| `edu.identity.user.updated` | UserEvent.updated | iam (ai06) | 更新教师关联（角色变更时） | 基于用户事件序列号去重 | P3 |
| `edu.identity.user.deleted` | UserEvent.deleted | iam (ai06) | 软删除教师关联（保留历史成绩归属） | 基于用户 id 去重 | P3 |
| `edu.insight.mastery.updated` | MasteryEvent.updated | data-ana (ai11) | 接收学生掌握度，用于推荐个性化练习 | 基于 mastery_score_id 去重 | P4（P3 可选） |

> 注：当前 `events.proto` 无 UserEvent message 定义（IAM 事件可能在另一个 proto 文件），ai08 在 P3 实施时确认 IAM 事件 proto 定义位置。

### 2.3 HTTP 调用（如有）

无。core-edu 不主动发起 HTTP 调用。

---

## §3 就绪信号

### 3.1 我依赖的上游就绪标志

| 依赖项 | 提供方 | 就绪信号 | 状态 |
| ------ | ------ | -------- | ---- |
| coord 仲裁 ISSUE-001 ~ ISSUE-006 | coord | coord.md 仲裁章节 | ⏳ 待仲裁 |
| core_edu.proto 补全 | coord 或 ai08 | 5 Service / 27 RPC 定义 | ⏳（见 [ISSUE-001](../objections/core-edu_issue.md)） |
| events.proto 同步 | coord | 含 AttendanceEvent + schema_version + `edu.teaching.*` 注释 | ⏳（见 [ISSUE-002](../objections/core-edu_issue.md)） |
| buf.gen.yaml gRPC 插件 | coord | `buf generate` 产出 TS gRPC 代码 | ⏳ |
| iam gRPC 50052 | ai06 | HealthService.Check = SERVING | ⏳（阻塞 P3.9 消费 IAM 事件，core-edu 可先独立运行） |
| Redis 部署 | infra | redis:6379 可连接 | ⏳（阻塞 P3.7 分布式锁 + /readyz 探针） |
| Temporal server 部署 | infra | temporal:7233 可连接 | ⏳（阻塞 P3.10 工作流试点，可降级为纯事件驱动） |
| content gRPC 50054（P4） | ai09 | HealthService.Check = SERVING | ⏳（阻塞 P4.2 知识点关联） |
| data-ana gRPC 50055（P4） | ai11 | HealthService.Check = SERVING | ⏳（阻塞 P4.1 mastery 消费） |
| msg gRPC 50056（P5） | ai10 | HealthService.Check = SERVING | ⏳（阻塞 P5.1 事件联调） |

### 3.2 我的就绪标志（供下游消费）

| 阶段 | 就绪信号 | 消费方 | 状态 |
| ---- | -------- | ------ | ---- |
| P2（已就绪） | HTTP 3004 可访问 + /healthz + /readyz（DB 探针）+ REST CRUD（exams/homework/grades）+ Outbox | 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 8 RPC 可调用（含 PublishExam/SubmitExam/GradeExam） | teacher-bff / student-bff / ai | ⏳ |
| P3 子信号 3 | HomeworkService 5 RPC 可调用（含 GradeHomework） | teacher-bff / student-bff | ⏳ |
| P3 子信号 4 | GradeService 6 RPC 可调用（含 UpdateGrade） | 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 | ⏳ |

---

## §4 Mock 策略

### 4.1 我提供的 mock（供下游消费）

在 core-edu 真实服务就绪前，为下游（teacher-bff / student-bff / parent-bff / content / msg / data-ana）提供以下 mock：

**gRPC mock**（使用 grpc-mock 拦截 50053 端口）：

| Service | RPC | mock 返回 |
| ------- | --- | --------- |
| ClassService | GetClassesByTeacher | 固定 3 个 ClassInfo |
| ClassService | ListStudentsByClass | 固定 30 个 StudentInfo |
| ClassService | BatchGetClasses | 按 id 列表返回对应 ClassInfo |
| ExamService | ListExamsByClass | 固定 2 个 Exam |
| ExamService | GetExam | 固定 1 个 Exam（含题目列表） |
| ExamService | CreateExam | 返回固定 examId |
| HomeworkService | ListHomeworkByClass | 固定 3 个 Homework |
| HomeworkService | SubmitHomework | 返回固定 submissionId |
| GradeService | ListGradesByStudent | 固定 5 个 Grade |
| GradeService | ListGradesByExam | 固定 30 个 Grade（按班级学生数） |
| AttendanceService | ListAttendanceByStudent | 固定 10 条 Attendance |
| AttendanceService | RecordAttendance | 返回固定 attendanceId |
| HealthService | Check | 返回 SERVING |

**Kafka mock**（core-edu 就绪前不发布真实事件）：
- 下游 data-ana / msg 使用本地 stub 事件（固定 JSON payload，含 schema_version/event_id/occurred_at/metadata）
- stub 事件 JSON 文件位置：`services/core-edu/test/stubs/events/`（ai08 P3.12 测试阶段产出）

### 4.2 我消费的 mock（在真实上游就绪前）

在真实 iam 就绪前，core-edu 使用以下 mock：

| 依赖 | mock 方式 | 切换真实时机 |
| ---- | --------- | ------------ |
| 用户数据 | 内置固定 teacher_id / student_id（不订阅 `edu.identity.user.*`） | iam gRPC 50052 就绪 + IAM 事件 topic 有事件发布 |
| 权限校验 | core-edu 内部不校验权限（由 Gateway/BFF 层负责），仅记录 created_by 字段 | iam 就绪后仍由 Gateway/BFF 负责，core-edu 仅做 DataScope 下推 |
| content 知识点 | 不调用 ContentService.GetKnowledgePoints，lessons.knowledge_point_ids 仅存储不校验 | content gRPC 50054 就绪（P4） |
| Temporal 工作流 | 考试发布降级为同步事件驱动（无工作流） | Temporal server 部署就绪 |
| Redis 分布式锁 | 降级为 DB SELECT FOR UPDATE（性能下降但功能可用） | Redis 部署就绪 |

---

## §5 跨模块契约对齐状态（ai08 核查）

> 核查日期：2026-07-10
> 详细核查记录见 [objections/core-edu_issue.md §0](../objections/core-edu_issue.md#0-已有仲裁核查记录ai08-接管后核查)

| 待确认项 | coord 仲裁结论 | 核查状态 |
| -------- | -------------- | -------- |
| iam `user.created` 等事件 topic | `edu.identity.user.created` / `.updated` / `.deleted`（004 §7.2） | ✅ 已仲裁，core-edu P3 实现消费端 |
| core-edu 端口 3004 + gRPC 50053 | 不冲突，已纳入 coord 全局端口矩阵 | ✅ 已仲裁 |
| Kafka topic 命名 | 统一为 `edu.teaching.<aggregate>.<action>`（coord §3.1） | ✅ 已仲裁，core-edu P3 修 TOPIC_MAP |
| proto 包名 | `next_edu_cloud.core_edu.v1`（coord §2.1） | ✅ 已仲裁 |
| 错误码前缀 | `CORE_EDU_*` 统一（coord §5.5） | ✅ 已仲裁 |
| core_edu.proto 补 AttendanceService | coord 整改 #14 | ❌ 仲裁声称已补全，实际未补（ISSUE-001） |
| events.proto 同步 `edu.teaching.*` 命名 | coord §3.1 | ❌ 未同步（ISSUE-002） |
| 考试/作业状态命名 | 未仲裁 | ❌ 跨模块不一致（ISSUE-003） |
| class.transferred topic | 未仲裁 | ❌ 三处不一致（ISSUE-004） |
| RPC 数量统计口径 | 未仲裁 | ❌ 三处不一致（ISSUE-005） |
| 7 项设计决策 | 未仲裁 | ❌ 待提请（ISSUE-006） |