docs(docs): coord 完成 15 模块 issue 仲裁与基础设施同步

coord.md 新增 ARB-019/020/021 三章仲裁章节，修正 ARB-001。 - coord.md: 新增 ARB-019/020/021（student/parent/admin-portal 24 项） - coord.md: 修正 ARB-001（admin P2 预留/schema 文件名/classes 数据源） - 004 §4: 依赖图加 PBFF→DataAna+Msg - 004 §7.2: push-gateway→Redis 软失败标注 - 004 §11.4: 错误码前缀矩阵（11 服务+i18n key） - 004 §11.5: ActionState 信封规范（降级模式方案 B） - matrix §1: 依赖矩阵加 PBFF 边 - matrix §2: 移除 api-gateway 为 iam gRPC 消费方 - matrix §4: admin-portal→teacher-bff - matrix §5: 移除 /sse+鉴权头统一 - matrix §6: 错误码表补 i18n key 列 - 15 个 issue.md: 仲裁结论回写 - push-gateway_contract: 移除 /sse+鉴权头改 X-Internal-Token - packages/contracts: 新建包 ADMIN_* 权限点常量 AI: coord
2026-07-10 16:30:51 +08:00
parent df62ffc176
commit c179af64a6
22 changed files with 2320 additions and 382 deletions
--- a/docs/architecture/issues/objections/core-edu_issue.md
+++ b/docs/architecture/issues/objections/core-edu_issue.md
@@ -14,14 +14,14 @@

 ### 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 实际状态 |
+| 仲裁编号                       | 位置                                                                    | 核查结论                                               |
+| ------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------ |
+| 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）

@@ -73,6 +73,7 @@
  - 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）
@@ -109,6 +110,7 @@
  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 无事件契约可发布
@@ -132,13 +134,14 @@
 - **描述**：
  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-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 需要转换层
  - 前端展示需处理两套命名
@@ -147,7 +150,7 @@
  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` 歧义大）。
+    ai08 倾向方案 A（`graded` 是教育领域通用术语，`scored` 歧义大）。
 - **状态**：待 coord 仲裁

 ---
@@ -160,13 +163,14 @@
 - **描述**：
  `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` |
+  | 文档                                                          | 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 域）
@@ -174,7 +178,7 @@
  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 后属教学域）。
+    ai08 倾向 `edu.teaching.class.transferred`（与 §3.1 仲裁风格一致，classes 合并到 core-edu 后属教学域）。
 - **状态**：待 coord 仲裁

 ---
@@ -187,13 +191,14 @@
 - **描述**：
  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 基线） |
+  | 文档                           | 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"含义模糊
@@ -214,17 +219,18 @@
 - **描述**：
  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 仅软删除 |
+  | #   | 决策点                                   | 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 默认值与倾向不一致，仲裁前可能实现错
@@ -246,6 +252,22 @@
  3. homework/grades controller 权限装饰器覆盖核对（L104）

  ai08 在 P3 实施前需 coord 确认这些项是否作为 P3 验收硬性标准。
- **建议方案**：
-  coord 确认上述 3 项是否纳入 P3 验收标准；若纳入，ai08 在 P3 实施时补齐。
- **状态**：待 coord 仲裁
+
+- **建议方案**：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         |