# core-edu 问题记录

> 负责人：ai08
> 关联：[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。

---

## 问题列表

<!--
追加条目格式：

### ISSUE-[编号]-[AI标识]：[标题]

- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 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.md §4 ARB-004](../coord.md#4-arb-004core-edu-模块-7-项-issue-仲裁)）

---

## §3 仲裁结论（2026-07-10 coord）

> 详见 [coord.md §4 ARB-004](../coord.md#4-arb-004core-edu-模块-7-项-issue-仲裁)

| ISSUE | 仲裁结论                                                                                             | 执行方       |
| ----- | ---------------------------------------------------------------------------------------------------- | ------------ |
| 001   | ✅ coord 批次 0 补全 core_edu.proto 至 5 Service 27 RPC（ARB-007）                                   | coord        |
| 002   | ✅ coord 批次 0 补全 events.proto（AttendanceEvent + schema_version + edu.teaching.* 注释，ARB-006） | coord        |
| 003   | ✅ 采用方案 A：统一 `graded`（去掉 SCORED）；submissions 统一 `not_submitted/submitted/graded`       | ai08 + coord |
| 004   | ✅ 统一为 `edu.teaching.class.transferred`                                                           | coord + ai08 |
| 005   | ✅ 统一为 P3 全量 27 RPC                                                                             | coord + ai08 |
| 006   | ✅ 七项设计决策全部采用 ai08 倾向方案（见 coord.md §4.4）                                            | ai08         |
| 007   | ✅ 3 项（Dockerfile/ActionState traceId/权限装饰器）纳入 P3 验收硬性标准                             | ai08         |