feat: auto committed

2026-07-10 15:05:55 +08:00
parent 9ba368477d
commit 06a646ea4e
3 changed files with 788 additions and 80 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） |
--- a/docs/architecture/issues/objections/core-edu_issue.md
+++ b/docs/architecture/issues/objections/core-edu_issue.md
@@ -1,11 +1,34 @@
 # core-edu 问题记录

 > 负责人：ai08
-> 关联：[coord.md](../coord.md)、[contracts/core-edu_contract.md](../contracts/core-edu_contract.md)
+> 关联：[coord.md](../coord.md)、[contracts/core-edu_contract.md](../contracts/core-edu_contract.md)、[coord-cross-review.md](../../coord-cross-review.md)
 > 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态

 ---

+## §0 已有仲裁核查记录（ai08 接管后核查）
+
+> 核查日期：2026-07-10
+> 核查范围：01-understanding.md / 02-architecture-design.md 引用的 coord 仲裁结论
+> 核查方法：对照 [coord-cross-review.md](../../coord-cross-review.md) 原文 + 实际 proto 文件 + 实际源码
+
+### 0.1 已核查通过的仲裁
+
+| 仲裁编号 | 位置 | 核查结论 |
+| -------- | ---- | -------- |
+| coord-cross-review §3.1 | topic 命名统一为 `edu.teaching.<aggregate>.<action>` | ✅ 仲裁真实存在，结论准确，core-edu 01/02 文档引用正确 |
+| coord-cross-review §5.5 | 错误码前缀 `CORE_EDU_*` 统一（不再细分 `EXAMS_`/`HOMEWORK_`/`GRADES_`） | ✅ 仲裁真实存在，结论准确 |
+| coord-cross-review §5.7 | ActionState 信封结构统一 | ✅ 仲裁真实存在，core-edu GlobalErrorFilter 已对齐 |
+| coord-cross-review §2.1 | proto 包名 `next_edu_cloud.core_edu.v1` | ✅ 仲裁真实存在，core_edu.proto L3 符合 |
+| coord-cross-review §6 整改 #14 | core_edu.proto 补 AttendanceService | ⚠️ 仲裁真实存在，但状态与实际不符（见 ISSUE-001） |
+| coord-cross-review §6 整改 #16 | buf.gen.yaml 补 gRPC 插件 | ⚠️ 待 ai08 核实 buf.gen.yaml 实际状态 |
+
+### 0.2 核查发现的仲裁状态不一致（升级为 ISSUE）
+
+详见下方 ISSUE-001 ~ ISSUE-003。
+
+---
+
 ## 问题列表

 <!--
@@ -21,4 +44,208 @@
 - **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
 -->

-（暂无问题）
+### ISSUE-001-ai08：core_edu.proto 实际状态与 coord 仲裁声称不一致（P0）
+
+- **提请方**：ai08
+- **日期**：2026-07-10
+- **类型**：契约不明确（仲裁状态与代码实际不符）
+- **描述**：
+  [coord-cross-review.md](../../coord-cross-review.md) L312 声称：
+
+  > `core_edu.proto 补全 | packages/shared-proto/proto/core_edu.proto | ✅ 5 service（+ClassService +AttendanceService）`
+
+  但 ai08 核查实际文件 `packages/shared-proto/proto/core_edu.proto`，**实际只有 3 个 service**：
+
+  ```
+  service ExamService { ... }       // 5 RPC
+  service HomeworkService { ... }   // 4 RPC
+  service GradeService { ... }      // 5 RPC
+  ```
+
+  **缺失**：
+  - `ClassService`（4 RPC：GetClass / GetClassesByTeacher / BatchGetClasses / ListStudentsByClass）
+  - `AttendanceService`（4 RPC：RecordAttendance / GetAttendance / ListAttendanceByStudent / ListAttendanceByClass）
+
+  同时 Exam/Homework/Grade message **缺 P3 新增字段**：
+  - Exam 缺 `subject_id`、`school_id`、`status_changed_at`、`status_changed_by`、`archived_at`
+  - Homework 缺 `subject_id`、`grace_period`、`school_id`
+  - Grade 缺 `total_score`、`school_id`、`idempotency_key`
+  - SubmitHomeworkRequest 缺 `answers` 字段（02 文档 §4.2 要求含完整 answers）
+
+  缺失 P3 新增 RPC：`PublishExam` / `SubmitExam` / `GradeExam` / `GradeHomework` / `UpdateGrade`。
+- **影响**：
+  1. 01-understanding.md L48 仅声称缺 AttendanceService，遗漏了 ClassService 也缺失
+  2. matrix.md §2 声称 core-edu 22 RPC，但实际 proto 仅 14 RPC（5+4+5）
+  3. 下游 teacher-bff / student-bff / parent-bff 按 22 RPC 设计 mock，实际无 proto 定义可生成代码
+- **建议方案**：
+  coord 确认 `core_edu.proto` 补全工作的实际负责人（coord 自行补全，还是交由 ai08 在 P3 补全）。
+  - 若 coord 已补全但未提交：请 coord 提交最新 proto
+  - 若待 ai08 P3 补全：coord-cross-review.md L312 的 "✅ 已补全" 状态需更正为 "⏳ 待 ai08 P3 补全"，01-understanding.md L48 需补"ClassService 也缺失"
+- **状态**：待 coord 仲裁
+
+---
+
+### ISSUE-002-ai08：events.proto 未同步 coord topic 命名仲裁（P0）
+
+- **提请方**：ai08
+- **日期**：2026-07-10
+- **类型**：契约不明确（仲裁未落实到 proto）
+- **描述**：
+  [coord-cross-review.md](../../coord-cross-review.md) §3.1 仲裁"统一为 `edu.teaching.<aggregate>.<action>` 风格"，但 `packages/shared-proto/proto/events.proto` 实际状态：
+
+  1. **文件头注释（L9-13）仍是旧 topic 命名**：
+
+     ```
+     //   edu.exam.events       <- exam.created / exam.updated / exam.deleted
+     //   edu.homework.events   <- homework.assigned / homework.submitted / homework.graded
+     //   edu.grade.events      <- grade.recorded / grade.updated
+     //   edu.class.events      <- class.transferred
+     ```
+
+     未同步 `edu.teaching.exam.created` 等仲裁后命名。
+
+  2. **缺 `AttendanceEvent` message**：events.proto 仅定义 ClassEvent / ExamEvent / HomeworkEvent / GradeEvent，无 AttendanceEvent。02 文档 §5.1 要求发布 `edu.teaching.attendance.recorded` 事件，但 proto 无对应 message。
+
+  3. **缺 `schema_version` 字段**：所有 Event message（ClassEvent/ExamEvent/HomeworkEvent/GradeEvent）均无 `schema_version` 字段。coord §3.1 仲裁 + known-issues §1.3 + 01-understanding.md L67 + 02-architecture-design.md §5.1 均要求事件 payload 含 `schema_version`，但 proto 未定义。
+
+  4. **matrix.md §4 与 coord §3.1 仲裁不一致**：matrix.md §4 Kafka 事件发布方矩阵仍列 `edu.exam.events` / `edu.homework.events` / `edu.grade.events` / `edu.class.events`，未同步 coord §3.1 仲裁后的 `edu.teaching.*` 命名。
+- **影响**：
+  - core-edu 修改 TOPIC_MAP 后，发布到 `edu.teaching.*` topic，但 events.proto 注释和 matrix.md 仍记录旧 topic，下游 AI 文档被误导
+  - 缺 AttendanceEvent message 导致 AttendanceService 无事件契约可发布
+  - 缺 schema_version 字段导致消费端无法按版本处理
+- **建议方案**：
+  1. coord 同步更新 events.proto：
+     - 文件头注释改为 `edu.teaching.*` 命名
+     - 新增 `AttendanceEvent` message
+     - 所有 Event message 新增 `string schema_version = N;` 字段
+  2. coord 同步更新 matrix.md §4 为 `edu.teaching.*` 命名
+  3. ai08 在 core-edu `outbox.publisher.ts` TOPIC_MAP 按 `edu.teaching.*` 命名实现
+- **状态**：待 coord 仲裁
+
+---
+
+### ISSUE-003-ai08：考试/作业状态命名跨模块不一致（P1）
+
+- **提请方**：ai08
+- **日期**：2026-07-10
+- **类型**：契约不明确（跨模块命名冲突）
+- **描述**：
+  02-architecture-design.md 定义的状态命名与 [coord.md](../coord.md) §1.2 GraphQL schema 枚举不一致：
+
+  | 维度 | 02-architecture-design.md（core-edu） | coord.md §1.2 GraphQL schema（teacher-bff） | 不一致点 |
+  | ---- | ------------------------------------- | ------------------------------------------- | -------- |
+  | ExamStatus | `draft / published / in_progress / grading / graded / archived / cancelled` | `DRAFT / PUBLISHED / IN_PROGRESS / GRADING / SCORED / ARCHIVED` | core-edu 用 `graded`，coord GraphQL 用 `SCORED`；core-edu 多 `cancelled` |
+  | SubmissionStatus（exam） | `in_progress / submitted / graded` | `NOT_SUBMITTED / SUBMITTED / GRADED` | core-edu 用 `in_progress`，coord 用 `NOT_SUBMITTED` |
+  | SubmissionStatus（homework） | `draft / submitted / graded` | `NOT_SUBMITTED / SUBMITTED / GRADED` | core-edu exam 用 `in_progress`，homework 用 `draft`，自身也不一致 |
+
+  02 文档 §3.1.1 exam_submissions.status 注释 `in_progress / submitted / graded`，§3.1.2 homework_submissions.status 注释 `draft / submitted / graded`，**core-edu 内部 exam 与 homework 的初始状态命名也不一致**（`in_progress` vs `draft`）。
+- **影响**：
+  - teacher-bff GraphQL schema 枚举值与 core-edu DB status 字段值无法直接映射，BFF 需要转换层
+  - 前端展示需处理两套命名
+  - coord 仲裁 teacher-bff schema 时未与 core-edu 状态机命名对齐
+- **建议方案**：
+  coord 仲裁统一状态命名（建议二选一）：
+  - **方案 A（推荐）**：core-edu DB status 统一为小写动词形式 `draft / published / in_progress / grading / graded / archived / cancelled`，GraphQL 枚举映射为大写 `DRAFT / PUBLISHED / IN_PROGRESS / GRADING / GRADED / ARCHIVED / CANCELLED`（去掉 `SCORED`，统一用 `GRADED`）。SubmissionStatus 统一为 `NOT_SUBMITTED / SUBMITTED / GRADED`，core-edu exam/homework submissions 初始状态统一为 `not_submitted`（不再用 `in_progress` 或 `draft`）。
+  - **方案 B**：保留 coord GraphQL 现状（`SCORED`），core-edu 改 `graded` 为 `scored`。
+  ai08 倾向方案 A（`graded` 是教育领域通用术语，`scored` 歧义大）。
+- **状态**：待 coord 仲裁
+
+---
+
+### ISSUE-004-ai08：class.transferred 事件 topic 三处不一致（P1）
+
+- **提请方**：ai08
+- **日期**：2026-07-10
+- **类型**：契约不明确（topic 命名跨文档不一致）
+- **描述**：
+  `class.transferred` 事件的 topic 命名在三处文档不一致：
+
+  | 文档 | topic 命名 |
+  | ---- | ---------- |
+  | 01-understanding.md L64 / 02-architecture-design.md §5.1 / §7 | `edu.org.class.created`（合并后归 org 域） |
+  | matrix.md §4 | `edu.class.events`（ClassEvent，action: transferred） |
+  | events.proto L13 注释 | `edu.class.events` |
+
+  core-edu 文档声称"classes 合并后归 org 域"用 `edu.org.class.created`，但 coord 维护的 matrix.md 和 events.proto 仍用 `edu.class.events`。
+- **影响**：
+  - core-edu 按 `edu.org.class.created` 实现 TOPIC_MAP 后，matrix.md 记录的 `edu.class.events` topic 下游消费者订阅不上
+  - 命名归类不一致（org 域 vs class 域）
+- **建议方案**：
+  coord 仲裁统一：
+  - 若 classes 合并到 core-edu 后仍归"教学组织域"，则 topic 应为 `edu.teaching.class.transferred`（遵循 §3.1 仲裁的 `edu.teaching.<aggregate>.<action>` 风格）
+  - 若归"组织域"，则为 `edu.org.class.transferred`（注意 action 应为 `transferred` 而非 `created`）
+  ai08 倾向 `edu.teaching.class.transferred`（与 §3.1 仲裁风格一致，classes 合并到 core-edu 后属教学域）。
+- **状态**：待 coord 仲裁
+
+---
+
+### ISSUE-005-ai08：core-edu gRPC RPC 数量统计口径不一致（P1）
+
+- **提请方**：ai08
+- **日期**：2026-07-10
+- **类型**：契约不明确（统计口径冲突）
+- **描述**：
+  core-edu gRPC RPC 数量在三处文档统计不一致：
+
+  | 文档 | RPC 数 | 包含 ClassService | 包含 P3 新增 RPC |
+  | ---- | ------ | ----------------- | ---------------- |
+  | matrix.md §2 | 22 | ✅ 是（4 RPC） | ❌ 否（P2 基线） |
+  | 02-architecture-design.md §4.2 | 22 | ❌ 否 | ✅ 是（PublishExam/SubmitExam/GradeExam/GradeHomework/UpdateGrade） |
+  | core-edu_contract.md §1.1 | 22 | ✅ 是（4 RPC） | ❌ 否（P2 基线） |
+
+  P3 全量应为：ClassService 4 + ExamService 8（5+3 新增）+ HomeworkService 5（4+1 新增）+ GradeService 6（5+1 新增）+ AttendanceService 4 = **27 RPC**。
+- **影响**：
+  - matrix.md §2 声明 22 RPC 但含 ClassService，02 文档声明 22 RPC 但不含 ClassService，下游 AI 无法判断应实现多少 RPC
+  - 就绪信号"core-edu gRPC 50053 + 22 RPC"含义模糊
+- **建议方案**：
+  coord 统一 RPC 统计口径：
+  - matrix.md §2 改为 "27 RPC（P3 全量：ClassService 4 + ExamService 8 + HomeworkService 5 + GradeService 6 + AttendanceService 4）"
+  - 就绪信号改为 "core-edu gRPC 50053 + 27 RPC + HealthService SERVING"
+  - core-edu_contract.md §1.1 补全 P3 新增 RPC
+- **状态**：待 coord 仲裁
+
+---
+
+### ISSUE-006-ai08：core-edu 02 文档 §13.3 七项未决决策待仲裁（P2）
+
+- **提请方**：ai08
+- **日期**：2026-07-10
+- **类型**：契约不明确（设计决策未仲裁）
+- **描述**：
+  02-architecture-design.md §13.3 列出 7 项未决设计决策，ai08 尚未正式提请 coord 仲裁，现集中提请：
+
+  | # | 决策点 | ai08 倾向 |
+  | - | ------ | --------- |
+  | 1 | classes 服务合并到 core-edu 的时机 | (a) P3 初期合并 |
+  | 2 | 排课 room_id 是否 P3 实现 | (b) 仅预留字段 |
+  | 3 | 成绩计算公式 scope 优先级 | (a) class > subject > school |
+  | 4 | 作业 grace_period 默认值 | (b) 300 秒（5 分钟宽限） |
+  | 5 | P3 是否启用 events.proto schema 强制校验 | (b) 仅文档约束 |
+  | 6 | exam.submitted 事件是否包含完整 answers | (b) 仅含 submission_id |
+  | 7 | archived 考试数据是否物理迁移 | (b) P3 仅软删除 |
+
+  注：决策 #4 与 02 文档 §3.1.2 homework 表 `gracePeriod: int("grace_period").notNull().default(0)` 默认 0 不一致，仲裁后需统一 schema 默认值。
+- **影响**：
+  - 决策未定，core-edu P3 实现无法启动
+  - 决策 #4 schema 默认值与倾向不一致，仲裁前可能实现错
+- **建议方案**：
+  coord 逐项仲裁，ai08 按倾向方案实现。决策 #4 若采 (b) 300 秒，02 文档 §3.1.2 schema 默认值改为 `.default(300)`。
+- **状态**：待 coord 仲裁
+
+---
+
+### ISSUE-007-ai08：core-edu 01 文档审计表"待核对"项待 coord 确认（P2）
+
+- **提请方**：ai08
+- **日期**：2026-07-10
+- **类型**：其他（审计未完成项）
+- **描述**：
+  01-understanding.md 审计表与"黄金模板对齐清单"中 3 项标记"待核对"：
+  1. Dockerfile 多阶段构建（L111 / L128 审计表"待核对"）
+  2. ActionState 信封 traceId 验证（L116）
+  3. homework/grades controller 权限装饰器覆盖核对（L104）
+
+  ai08 在 P3 实施前需 coord 确认这些项是否作为 P3 验收硬性标准。
+- **建议方案**：
+  coord 确认上述 3 项是否纳入 P3 验收标准；若纳入，ai08 在 P3 实施时补齐。
+- **状态**：待 coord 仲裁
--- a/docs/architecture/issues/worklines/core-edu_workline.md
+++ b/docs/architecture/issues/worklines/core-edu_workline.md
@@ -1,45 +1,370 @@
 # core-edu 工作排期

 > 负责人：ai08
-> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/core-edu_contract.md](../contracts/core-edu_contract.md)
+> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/core-edu_contract.md](../contracts/core-edu_contract.md)、[services/core-edu/docs/02-architecture-design.md](../../../services/core-edu/docs/02-architecture-design.md)
 > 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
+> 批次归属：批次 2（P3 核心教学），关键路径

 ---

 ## §1 总览

-core-edu 是教学核心服务，提供 ClassService、ExamService、HomeworkService、GradeService、AttendanceService，并基于 Outbox 模式发布领域事件。全阶段目标：P2 服务骨架+Outbox → P3 五大 Service 实现 → P4-P6 持续优化。
+core-edu 是教学核心服务，承载 D2 教学组织（classes）+ D3 教学核心（exams / homework / grades / attendance / schedule）两个限界上下文。
+
+**全阶段目标**：
+
+| 阶段 | 目标 | 就绪信号 |
+| ---- | ---- | -------- |
+| P2（已部分完成） | 服务骨架 + Outbox 模式 + REST CRUD + 三支柱可观测 | HTTP 3004 可访问 + /healthz + /readyz（DB 探针） |
+| P3（核心） | gRPC 50053 启用 + 5 Service 全量 RPC + 状态机 + Outbox 事件全量 + 排课考勤 + 成绩计算配置化 + Temporal 试点 | gRPC 50053 + 27 RPC + HealthService SERVING |
+| P4 | 持续优化 + 消费 data-ana mastery 事件 + content gRPC 调用（知识点关联） | — |
+| P5 | 配合 msg 服务事件消费联调 + AI 辅助批改预留 | — |
+| P6 | /readyz 硬化 + Outbox relay 迁独立 Go 服务评估 + 多租户行级隔离 | — |
+
+**当前状态（2026-07-10）**：
+- ✅ P2 骨架已就绪（exams/homework/grades 三域 REST CRUD + Outbox + 三支柱）
+- ⏳ P3 待启动（依赖 ISSUE-001 ~ ISSUE-006 仲裁结果）

 ---

-## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
+## §2 全阶段甘特图（P2-P6）

 ```mermaid
 gantt
-    title ai08 core-edu 全阶段排期
+    title ai08 core-edu 全阶段排期（P2-P6）
    dateFormat YYYY-MM-DD
    axisFormat %m-%d

-    section P2-P6
-    [阶段任务] :a8a, 2026-07-10, Xd
+    section P2 骨架（已就绪）
+    P2 服务骨架+Outbox+REST CRUD :done, p2, 2026-07-01, 7d
+
+    section P3 核心教学（批次2 关键路径）
+    P3.0 等待 coord 仲裁 ISSUE-001~006 :crit, p3a, 2026-07-10, 2d
+    P3.1 黄金模板对齐（Drizzle getDb+Zod+kafka logger+/readyz探针） :crit, p3b, after p3a, 2d
+    P3.2 TOPIC_MAP 重命名 edu.teaching.* + payload schema_version/event_id :crit, p3c, after p3b, 1d
+    P3.3 考试状态机+作业状态机+成绩幂等 :crit, p3d, after p3c, 3d
+    P3.4 gRPC server 50053 启用+5 Service 27 RPC :crit, p3e, after p3d, 3d
+    P3.5 排课考勤数据模型+AttendanceService :p3f, after p3e, 2d
+    P3.6 成绩计算配置化（grade_formulas+GradeCalculator） :p3g, after p3e, 2d
+    P3.7 作业提交 Redis 分布式锁 :p3h, after p3e, 1d
+    P3.8 DataScope 下推（Repository WHERE 注入） :p3i, after p3e, 1d
+    P3.9 消费 IAM 事件（user.created/updated/deleted） :p3j, after p3e, 1d
+    P3.10 Temporal 工作流试点（考试发布编排） :p3k, after p3e, 2d
+    P3.11 classes 服务合并到 core-edu :p3l, after p3e, 2d
+    P3.12 测试覆盖率≥80%+Dockerfile多阶段核对 :p3m, after p3l, 2d
+
+    section P4 持续优化
+    P4.1 消费 data-ana mastery.updated 事件 :p4a, after p3m, 2d
+    P4.2 content gRPC 调用（知识点关联） :p4b, after p4a, 2d
+    P4.3 读模型双轨读策略验证（MySQL+ClickHouse） :p4c, after p4b, 1d
+
+    section P5 联调
+    P5.1 msg 事件消费联调（通知触发） :p5a, after p4c, 2d
+    P5.2 AI 辅助批改接口预留（GetExam/ListGradesByExam） :p5b, after p5a, 1d
+
+    section P6 硬化
+    P6.1 /readyz 硬化（Kafka+Redis+Temporal 探针） :p6a, after p5b, 1d
+    P6.2 Outbox relay 迁独立 Go 服务评估 :p6b, after p6a, 2d
+    P6.3 多租户行级隔离验证 :p6c, after p6b, 1d
 ```

-> **注意**：以上为 coord 初始规划，ai08 接管后必须自行细化为完整 P2-P6 排期。
+**关键路径**：P3.0（仲裁）→ P3.1（模板对齐）→ P3.2（TOPIC_MAP）→ P3.3（状态机）→ P3.4（gRPC）→ P3.5/P3.6/P3.7/P3.8/P3.9/P3.10/P3.11（并行）→ P3.12（测试）
+
+**预计工期**：
+- P3：13 天（含 2 天等待仲裁）
+- P4：5 天
+- P5：3 天
+- P6：4 天
+- 合计：25 天（P3 后）

 ---

 ## §3 详细任务

-### 全阶段任务
+### P3.0 等待 coord 仲裁 ISSUE-001 ~ ISSUE-006
+
+- **负责人**：ai08（等待 coord）
+- **依赖**：无
+- **交付物**：coord 出具仲裁结论（见 [coord.md](../coord.md) 后续章节）
+- **验收标准**：6 项 ISSUE 全部裁决，状态更新为"已裁决"
+- **阻塞说明**：
+  - ISSUE-001（proto 实际状态）：阻塞 P3.4 gRPC 实现
+  - ISSUE-002（events.proto 未同步）：阻塞 P3.2 TOPIC_MAP 重命名
+  - ISSUE-003（状态命名不一致）：阻塞 P3.3 状态机实现
+  - ISSUE-004（class.transferred topic）：阻塞 P3.11 classes 合并
+  - ISSUE-005（RPC 数量口径）：阻塞就绪信号声明
+  - ISSUE-006（7 项设计决策）：阻塞 P3 全部实施
+
+### P3.1 黄金模板对齐（P0）

 - **负责人**：ai08
- **交付物**：⚠️ 由 ai08 自行补充
- **依赖**：见 [contracts/core-edu_contract.md](../contracts/core-edu_contract.md)
- **验收标准**：⚠️ 由 ai08 自行补充
+- **依赖**：无（可与其他 P3 任务并行）
+- **交付物**：
+  1. `src/config/database.ts` 改为 `getDb()` 函数式（对齐 classes 黄金模板）
+  2. `src/config/kafka.ts` L20/L22 `console.log`/`console.warn` → `logger.info`/`logger.warn`
+  3. 全部 Controller 接入 Zod ValidationPipe（exams/homework/grades schema 已存在，需接入到 Controller）
+  4. `src/shared/health/health.controller.ts` /readyz 补 Redis ping + Kafka producer 连接探针
+- **验收标准**：
+  - `pnpm run lint` + `pnpm run typecheck` 零错误
+  - /readyz 返回 3 项依赖状态（MySQL + Redis + Kafka）
+  - kafka.ts 无 console.* 调用
+
+### P3.2 TOPIC_MAP 重命名 + payload 补字段（P0）
+
+- **负责人**：ai08
+- **依赖**：ISSUE-002 仲裁（events.proto 同步）
+- **交付物**：
+  1. `src/shared/outbox/outbox.publisher.ts` TOPIC_MAP 改为 `edu.teaching.<aggregate>.<action>` 风格：
+     - `edu.exam.events` → `edu.teaching.exam.created` / `.updated` / `.deleted` / `.published` / `.submitted`
+     - `edu.homework.events` → `edu.teaching.homework.assigned` / `.submitted` / `.graded`
+     - `edu.grade.events` → `edu.teaching.grade.recorded` / `.updated`
+     - `edu.class.events` → 按 ISSUE-004 仲裁结果
+     - 新增 `edu.teaching.attendance.recorded`
+  2. outbox payload 补 `schema_version`（默认 `"v1"`）+ `event_id`（UUID）+ `occurred_at`（业务时间戳）+ `metadata: { traceId, userId }`
+  3. `src/shared/outbox/outbox.schema.ts` 补 `event_id`、`occurred_at`、`next_retry_at` 字段 + `uniq_event_id` 唯一索引
+- **验收标准**：
+  - TOPIC_MAP 命名符合 coord §3.1 仲裁
+  - outbox 表新增字段已迁移
+  - payload JSON 含 schema_version + event_id + occurred_at + metadata
+
+### P3.3 考试/作业状态机 + 成绩幂等（P1）
+
+- **负责人**：ai08
+- **依赖**：ISSUE-003 仲裁（状态命名统一）
+- **交付物**：
+  1. `src/exams/domain/exam-state-machine.ts`（纯函数：canTransition / transition）
+  2. `src/homework/domain/homework-state-machine.ts`（纯函数）
+  3. `src/exams/exams.service.ts` 接入状态机（PublishExam / StartExam / SubmitExam / GradeExam / ArchiveExam）
+  4. `src/homework/homework.service.ts` 接入状态机（SubmitHomework / GradeHomework）
+  5. `src/grades/grades.schema.ts` 补 `idempotency_key` 字段 + `uniq_student_exam` / `uniq_student_hw` / `uniq_idempotency` 唯一索引
+  6. `src/grades/grades.service.ts` 实现幂等录入（先 SELECT 检查，再 INSERT）
+- **验收标准**：
+  - 状态机非法转换抛 `CORE_EDU_EXAM_INVALID_STATUS_TRANSITION`（409）
+  - 同一学生同一考试/作业重复录入返回已存在成绩（幂等）
+  - 状态命名按 ISSUE-003 仲裁结果统一
+
+### P3.4 gRPC server 启用 + 5 Service 27 RPC（P1）
+
+- **负责人**：ai08
+- **依赖**：ISSUE-001 仲裁（proto 补全）、ISSUE-005 仲裁（RPC 统计口径）
+- **交付物**：
+  1. `src/main.ts` 启用 gRPC server（端口 50053，`@grpc/grpc-js` + `@bufbuild/protobuf`）
+  2. `src/exams/exams.grpc-controller.ts`（ExamService 8 RPC：CreateExam / GetExam / ListExamsByClass / UpdateExam / DeleteExam / PublishExam / SubmitExam / GradeExam）
+  3. `src/homework/homework.grpc-controller.ts`（HomeworkService 5 RPC：AssignHomework / GetHomework / ListHomeworkByClass / SubmitHomework / GradeHomework）
+  4. `src/grades/grades.grpc-controller.ts`（GradeService 6 RPC：RecordGrade / GetGrade / ListGradesByStudent / ListGradesByExam / ListGradesByHomework / UpdateGrade）
+  5. `src/attendance/attendance.grpc-controller.ts`（AttendanceService 4 RPC：RecordAttendance / GetAttendance / ListAttendanceByStudent / ListAttendanceByClass）
+  6. `src/classes/classes.grpc-controller.ts`（ClassService 4 RPC：GetClass / GetClassesByTeacher / BatchGetClasses / ListStudentsByClass）
+  7. `src/shared/health/health.grpc-controller.ts`（HealthService.Check 返回 SERVING）
+- **验收标准**：
+  - gRPC 50053 可连接，HealthService.Check 返回 SERVING
+  - 27 RPC 全部可调用（含 P3 新增 5 RPC）
+  - gRPC 调用走 AuthMiddleware + PermissionGuard（gRPC 上下文适配）
+
+### P3.5 排课考勤数据模型 + AttendanceService（P2）
+
+- **负责人**：ai08
+- **依赖**：P3.4 gRPC 启用
+- **交付物**：
+  1. `src/schedule/schedule.schema.ts`（core_edu_courses / core_edu_lessons / core_edu_schedules 三表）
+  2. `src/attendance/attendance.schema.ts`（core_edu_attendance 表）
+  3. `src/schedule/schedule.service.ts`（含 ScheduleConflictChecker：教师/班级时间冲突检测）
+  4. `src/attendance/attendance.service.ts`（含唯一索引幂等）
+  5. `src/schedule/schedule.controller.ts` + `src/attendance/attendance.controller.ts`（REST + gRPC 双入口）
+- **验收标准**：
+  - 排课冲突检测正确（教师时间重叠抛 CORE_EDU_SCHEDULE_CONFLICT 409）
+  - 考勤录入幂等（同一学生同一课时仅 1 条）
+
+### P3.6 成绩计算配置化（P2）
+
+- **负责人**：ai08
+- **依赖**：P3.4 gRPC 启用、ISSUE-006 决策 #3（scope 优先级）
+- **交付物**：
+  1. `src/grades/grade-formulas.schema.ts`（core_edu_grade_formulas 表：scope / scope_id / formula_type / weights / custom_expression / effective_from / effective_to）
+  2. `src/grades/domain/grade-calculator.ts`（纯函数：按 scope 优先级查询公式 → 加权/平均/自定义求值）
+  3. `src/grades/grades.service.ts` 接入 GradeCalculator
+  4. custom 公式安全求值（白名单正则 + Function 沙箱）
+- **验收标准**：
+  - 三种公式类型（weighted / average / custom）均正确计算
+  - scope 优先级按 ISSUE-006 决策 #3 仲裁结果
+  - custom 公式禁止函数调用 / 对象访问 / eval（白名单校验）
+
+### P3.7 作业提交 Redis 分布式锁（P2）
+
+- **负责人**：ai08
+- **依赖**：P3.4 gRPC 启用、Redis 部署
+- **交付物**：
+  1. `src/shared/redis/redis.client.ts`（Redis 单例）
+  2. `src/homework/homework.service.ts` submitHomework 接入 Redis 分布式锁
+     - 锁 key：`lock:hw:submit:{homeworkId}:{studentId}`
+     - 锁过期：30s
+     - 重试：5 次 × 100ms 间隔
+     - 超时：429 CORE_EDU_HOMEWORK_SUBMIT_LOCK_TIMEOUT
+  3. 同步对 exam submit 也接入锁（锁 key：`lock:exam:submit:{examId}:{studentId}`）
+- **验收标准**：
+  - 50 并发提交同一作业，仅 1 条提交入库
+  - 锁超时返回 429
+  - DB 唯一索引兜底（锁失效时仍幂等）
+
+### P3.8 DataScope 下推（P1）
+
+- **负责人**：ai08
+- **依赖**：无
+- **交付物**：
+  1. `src/shared/datascope/datascope-injector.ts`（根据 x-user-data-scope 头注入 WHERE 条件）
+  2. `src/exams/exams.repository.ts` 接入 DataScopeInjector（按 class_id / school_id 过滤）
+  3. `src/grades/grades.repository.ts` 接入 DataScopeInjector（按 student_id / class_id / school_id 过滤）
+  4. `src/middleware/permission.guard.ts` 增强：解析 dataScope 注入到 request
+- **验收标准**：
+  - 教师仅能查自己班级的考试/成绩
+  - 学生仅能查自己的成绩
+  - 校管理员可查全校
+
+### P3.9 消费 IAM 事件（P1）
+
+- **负责人**：ai08
+- **依赖**：IAM gRPC 50052 就绪（ai06）
+- **交付物**：
+  1. `src/shared/kafka/kafka.consumer.ts`（Kafka consumer 单例）
+  2. `src/iam-events/iam-user.consumer.ts`（订阅 edu.identity.user.created / .updated / .deleted）
+  3. `src/iam-events/teacher-associations.schema.ts`（core_edu_teacher_associations 表 + uniq_teacher_class_subject 唯一索引）
+  4. 消费幂等（基于 user_id + class_id + subject_id 唯一索引）
+- **验收标准**：
+  - IAM 发布 user.created 事件后，core-edu 写入 teacher_associations
+  - 重复消费同一事件不重复写入（幂等）
+  - user.deleted 事件软删除教师关联（保留历史成绩归属）
+
+### P3.10 Temporal 工作流试点（P3）
+
+- **负责人**：ai08
+- **依赖**：Temporal server 部署（infra）、P3.4 gRPC 启用
+- **交付物**：
+  1. `src/workflows/exam-publish.workflow.ts`（考试发布编排工作流）
+  2. `src/workflows/exam-publish.activities.ts`（5 个 Activity：创建提交骨架 / 通知 msg / 等待作答窗口 / 自动提交未答 / 通知教师）
+  3. `src/exams/exams.service.ts` publishExam 调用 `workflowClient.start(examPublishWorkflow, ...)`
+  4. `src/shared/temporal/temporal.client.ts`（Temporal client 单例）
+- **验收标准**：
+  - 考试发布后 Temporal UI 可见工作流实例
+  - 工作流完成 5 个 Activity
+  - 失败可重试
+
+### P3.11 classes 服务合并到 core-edu（P3）
+
+- **负责人**：ai08
+- **依赖**：ISSUE-006 决策 #1（合并时机）仲裁、P3.4 gRPC 启用
+- **交付物**：
+  1. `services/classes/src/` 代码迁入 `services/core-edu/src/classes/`
+  2. 删除独立 `services/classes/` 目录
+  3. `src/classes/classes.module.ts` 接入 core-edu AppModule
+  4. `src/classes/classes.grpc-controller.ts`（ClassService 4 RPC）
+  5. classes 错误码 `CLASSES_*` 保留（coord §5.5 仲裁，黄金模板历史遗留）
+- **验收标准**：
+  - classes 服务代码完全迁入 core-edu
+  - ClassService 4 RPC 可调用
+  - 原 classes 服务端口 3001 不再存在
+  - `pnpm run arch:scan` 确认 arch.db 已更新
+
+### P3.12 测试覆盖率 + Dockerfile 核对（P3）
+
+- **负责人**：ai08
+- **依赖**：P3.1 ~ P3.11 全部完成
+- **交付物**：
+  1. 单元测试：状态机 / GradeCalculator / ScheduleConflictChecker / DataScopeInjector（纯函数优先）
+  2. 集成测试：ExamsService / HomeworkService / GradesService / AttendanceService / ScheduleService
+  3. Outbox relay 测试（mock Kafka）
+  4. `Dockerfile` 多阶段构建核对（builder → runner，最终镜像无 devDependencies）
+- **验收标准**：
+  - `pnpm run test` 通过
+  - 覆盖率 ≥ 80%
+  - Dockerfile 多阶段构建，最终镜像 ≤ 200MB
+
+### P4.1 消费 data-ana mastery.updated 事件
+
+- **负责人**：ai08
+- **依赖**：data-ana gRPC 50055 就绪（ai11）
+- **交付物**：`src/data-ana-events/mastery.consumer.ts`（订阅 edu.insight.mastery.updated，基于 mastery_score_id 幂等）
+- **验收标准**：重复消费不重复写入
+
+### P4.2 content gRPC 调用（知识点关联）
+
+- **负责人**：ai08
+- **依赖**：content gRPC 50054 就绪（ai09）
+- **交付物**：`src/content/content.client.ts`（调用 ContentService.GetKnowledgePoints，排课关联知识点）
+- **验收标准**：lessons.knowledge_point_ids 引用的知识点在 content 服务可查
+
+### P4.3 读模型双轨读策略验证
+
+- **负责人**：ai08
+- **依赖**：data-ana CDC 链路就绪
+- **交付物**：验证刚提交成绩查 MySQL（强一致），聚合统计查 ClickHouse（最终一致 < 5s）
+- **验收标准**：双轨读策略符合 02 文档 §3.3
+
+### P5.1 msg 事件消费联调
+
+- **负责人**：ai08
+- **依赖**：msg gRPC 50056 就绪（ai10）
+- **交付物**：验证 msg 消费 core-edu 事件触发通知（edu.teaching.exam.created / homework.assigned / grade.recorded）
+- **验收标准**：端到端事件链路通
+
+### P5.2 AI 辅助批改接口预留
+
+- **负责人**：ai08
+- **依赖**：无
+- **交付物**：确认 ExamService.GetExam / GradeService.ListGradesByExam 接口对 ai 服务可用
+- **验收标准**：ai 服务可调用上述 RPC
+
+### P6.1 /readyz 硬化
+
+- **负责人**：ai08
+- **依赖**：无
+- **交付物**：/readyz 补 Temporal client 连接探针
+- **验收标准**：/readyz 返回 4 项依赖状态（MySQL + Redis + Kafka + Temporal）
+
+### P6.2 Outbox relay 迁独立 Go 服务评估
+
+- **负责人**：ai08（评估，不实施）
+- **依赖**：无
+- **交付物**：评估报告（是否迁出进程内 relay）
+- **验收标准**：产出评估结论
+
+### P6.3 多租户行级隔离验证
+
+- **负责人**：ai08
+- **依赖**：无
+- **交付物**：验证 school_id 行级隔离（不同学校数据互不可见）
+- **验收标准**：跨学校查询返回空

 ---

 ## §4 依赖与就绪信号

- **我依赖**：⚠️ 由 ai08 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai08 自行补充
+### 4.1 我依赖的上游就绪标志
+
+| 依赖项 | 提供方 | 就绪信号 | 状态 | 影响 |
+| ------ | ------ | -------- | ---- | ---- |
+| coord 仲裁 ISSUE-001 ~ ISSUE-006 | coord | coord.md 仲裁章节 | ⏳ 待仲裁 | 阻塞 P3 全部 |
+| iam gRPC 50052 | ai06 | HealthService.Check = SERVING | ⏳ | 阻塞 P3.9 消费 IAM 事件 |
+| events.proto 同步 | coord | events.proto 含 AttendanceEvent + schema_version | ⏳ | 阻塞 P3.2 TOPIC_MAP |
+| core_edu.proto 补全 | coord 或 ai08 | 5 service 27 RPC 定义 | ⏳ | 阻塞 P3.4 gRPC 实现 |
+| Redis 部署 | infra | redis:6379 可连接 | ⏳ | 阻塞 P3.7 分布式锁 + P3.1 /readyz |
+| Temporal server 部署 | infra | temporal:7233 可连接 | ⏳ | 阻塞 P3.10 工作流试点 |
+| buf.gen.yaml gRPC 插件 | coord | buf generate 产出 TS gRPC 代码 | ⏳ | 阻塞 P3.4 gRPC 实现 |
+| data-ana gRPC 50055（P4） | ai11 | HealthService.Check = SERVING | ⏳ | 阻塞 P4.1 mastery 消费 |
+| content gRPC 50054（P4） | ai09 | HealthService.Check = SERVING | ⏳ | 阻塞 P4.2 知识点关联 |
+| msg gRPC 50056（P5） | ai10 | HealthService.Check = SERVING | ⏳ | 阻塞 P5.1 事件联调 |
+
+### 4.2 我的就绪标志（供下游消费）
+
+| 阶段 | 就绪信号 | 消费方 | 状态 |
+| ---- | -------- | ------ | ---- |
+| P2（已就绪） | HTTP 3004 可访问 + /healthz + /readyz（DB 探针） | 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 可调用 | teacher-bff / student-bff / ai | ⏳ |
+| P3 子信号 3 | HomeworkService 5 RPC 可调用 | teacher-bff / student-bff | ⏳ |
+| P3 子信号 4 | GradeService 6 RPC 可调用 | 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.3 Mock 策略（全并行开发期间）
+
+详见 [contracts/core-edu_contract.md §4](../contracts/core-edu_contract.md)。