# 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)

---

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

### 1.1 gRPC 接口（如有）

| Service           | RPC                     | 请求                           | 响应                        | 端口  |
| ----------------- | ----------------------- | ------------------------------ | --------------------------- | ----- |
| ClassService      | GetClass                | GetClassRequest                | ClassInfo                   | 50053 |
| ClassService      | GetClassesByTeacher     | GetClassesByTeacherRequest     | GetClassesByTeacherResponse | 50053 |
| ClassService      | BatchGetClasses         | BatchGetClassesRequest         | BatchGetClassesResponse     | 50053 |
| ClassService      | ListStudentsByClass     | ListStudentsByClassRequest     | ListStudentsByClassResponse | 50053 |
| ExamService       | CreateExam              | CreateExamRequest              | CreateExamResponse          | 50053 |
| ExamService       | GetExam                 | GetExamRequest                 | Exam                        | 50053 |
| ExamService       | ListExamsByClass        | ListExamsByClassRequest        | ListExamsResponse           | 50053 |
| ExamService       | UpdateExam              | UpdateExamRequest              | UpdateExamResponse          | 50053 |
| ExamService       | DeleteExam              | DeleteExamRequest              | DeleteExamResponse          | 50053 |
| HomeworkService   | AssignHomework          | AssignHomeworkRequest          | AssignHomeworkResponse      | 50053 |
| HomeworkService   | GetHomework             | GetHomeworkRequest             | Homework                    | 50053 |
| HomeworkService   | ListHomeworkByClass     | ListHomeworkByClassRequest     | ListHomeworkResponse        | 50053 |
| HomeworkService   | SubmitHomework          | SubmitHomeworkRequest          | SubmitHomeworkResponse      | 50053 |
| GradeService      | RecordGrade             | RecordGradeRequest             | RecordGradeResponse         | 50053 |
| GradeService      | GetGrade                | GetGradeRequest                | Grade                       | 50053 |
| GradeService      | ListGradesByStudent     | ListGradesByStudentRequest     | ListGradesResponse          | 50053 |
| GradeService      | ListGradesByExam        | ListGradesByExamRequest        | ListGradesResponse          | 50053 |
| GradeService      | ListGradesByHomework    | ListGradesByHomeworkRequest    | ListGradesResponse          | 50053 |
| AttendanceService | RecordAttendance        | RecordAttendanceRequest        | RecordAttendanceResponse    | 50053 |
| AttendanceService | GetAttendance           | GetAttendanceRequest           | Attendance                  | 50053 |
| AttendanceService | ListAttendanceByStudent | ListAttendanceByStudentRequest | ListAttendanceResponse      | 50053 |
| AttendanceService | ListAttendanceByClass   | ListAttendanceByClassRequest   | ListAttendanceResponse      | 50053 |

### 1.2 HTTP 端点（如有）

无对外 HTTP 端点，仅 gRPC。

### 1.3 GraphQL schema（如 BFF）

不适用。

### 1.4 Kafka 事件发布（如有）

| Topic               | Event                                              | 消费方         |
| ------------------- | -------------------------------------------------- | -------------- |
| edu.exam.events     | ExamEvent（action: created/updated/deleted）       | msg / data-ana |
| edu.homework.events | HomeworkEvent（action: assigned/submitted/graded） | msg / data-ana |
| edu.grade.events    | GradeEvent（action: recorded/updated）             | msg / data-ana |
| edu.class.events    | ClassEvent（action: transferred）                  | msg / data-ana |

### 1.5 错误码前缀

`CORE_EDU_`（如 CORE_EDU_CLASS_NOT_FOUND、CORE_EDU_EXAM_CONFLICT）

---

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

### 2.1 gRPC 调用（同步）

无直接 gRPC 调用上游。core-edu 通过 Kafka 事件接收 iam 用户变更，不主动调 iam。

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

| Topic               | Event                                                     | 发布方     | mock 策略                                                            |
| ------------------- | --------------------------------------------------------- | ---------- | -------------------------------------------------------------------- |
| edu.iam.user.events | UserEvent（action: created/updated/deleted/role_changed） | iam (ai06) | iam 就绪前不订阅，使用本地内置用户数据（teacher_id/student_id 固定） |
| edu.iam.role.events | RoleEvent（action: created/updated）                      | iam (ai06) | iam 就绪前忽略，权限校验在 core-edu 内部 mock                        |

### 2.3 HTTP 调用（如有）

无。

---

## §3 就绪信号

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

- [ ] iam gRPC 50052 启用（ai06）—— 用于用户身份一致性校验（可选，core-edu 可先独立运行）
- [ ] edu.iam.user.events topic 有事件发布（ai06）—— 用于同步用户缓存

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

- [ ] core-edu gRPC 50053 启用（HealthService.Check 返回 SERVING）
- [ ] ClassService 4 RPC 可调用（GetClass/GetClassesByTeacher/BatchGetClasses/ListStudentsByClass）
- [ ] ExamService 5 RPC 可调用
- [ ] HomeworkService 4 RPC 可调用
- [ ] GradeService 5 RPC 可调用
- [ ] AttendanceService 4 RPC 可调用
- [ ] edu.exam.events / edu.homework.events / edu.grade.events / edu.class.events topic 可发布

---

## §4 Mock 策略

### 4.1 我提供的 mock

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

- **gRPC mock**：使用 grpc-mock 拦截 50053 端口
  - ClassService.GetClassesByTeacher 返回固定 3 个 ClassInfo
  - ClassService.ListStudentsByClass 返回固定 30 个 StudentInfo
  - ExamService.ListExamsByClass 返回固定 2 个 Exam
  - HomeworkService.ListHomeworkByClass 返回固定 3 个 Homework
  - GradeService.ListGradesByStudent 返回固定 5 个 Grade
  - AttendanceService.ListAttendanceByStudent 返回固定 10 条 Attendance
- **Kafka mock**：core-edu 就绪前不发布真实事件，下游 data-ana/msg 使用本地 stub 事件

### 4.2 我消费的 mock

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

- 用户数据：内置固定 teacher_id / student_id（不订阅 edu.iam.user.events）
- 权限校验：core-edu 内部不校验权限（由 Gateway/BFF 层负责），仅记录 created_by 字段