Merge worktree branch merge-15-modules-to-main-5ug5xJ

2026-07-10 15:28:20 +08:00
parent 60d7173545
commit df62ffc176
51 changed files with 11559 additions and 1908 deletions
--- a/docs/architecture/issues/contracts/core-edu_contract.md
+++ b/docs/architecture/issues/contracts/core-edu_contract.md
@@ -1,59 +1,151 @@
 # 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)
+> 关联：[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 接口（如有）
+### 1.1 gRPC 接口（P3 启用，端口 50053）

-| 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 |
+> 包名：`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)）

-### 1.2 HTTP 端点（如有）
+| 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 |

-无对外 HTTP 端点，仅 gRPC。
+**统计**：
+- 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 事件发布（如有）
+### 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 |
+> 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)）

-### 1.5 错误码前缀
+| 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 仲裁） |

-`CORE_EDU_`（如 CORE_EDU_CLASS_NOT_FOUND、CORE_EDU_EXAM_CONFLICT）
+**注意**：
+- `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 }
+}
+```

 ---

@@ -61,18 +153,30 @@

 ### 2.1 gRPC 调用（同步）

-无直接 gRPC 调用上游。core-edu 通过 Kafka 事件接收 iam 用户变更，不主动调 iam。
+| 调用方 | 目标服务 | 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               | 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                        |
+> 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 调用。

 ---

@@ -80,39 +184,91 @@

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

- [ ] iam gRPC 50052 启用（ai06）—— 用于用户身份一致性校验（可选，core-edu 可先独立运行）
- [ ] edu.iam.user.events topic 有事件发布（ai06）—— 用于同步用户缓存
+| 依赖项 | 提供方 | 就绪信号 | 状态 |
+| ------ | ------ | -------- | ---- |
+| 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 我的就绪标志（供下游消费）

- [ ] 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 可发布
+| 阶段 | 就绪信号 | 消费方 | 状态 |
+| ---- | -------- | ------ | ---- |
+| 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
+### 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 事件
+**gRPC mock**（使用 grpc-mock 拦截 50053 端口）：

-### 4.2 我消费的 mock
+| 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：

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