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

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 仲裁