xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Edu/docs/architecture/issues/objections/core-edu_issue.md
SpecialX c6362f4b04
Some checks failed
CI / quality-ts (push) Failing after 53s
Details
CI / quality-go (push) Failing after 7s
Details
CI / quality-proto (push) Failing after 3s
Details
CI / deploy (push) Has been skipped
Details
docs(docs): 更新 issue 仲裁状态 + 生成集成测试阶段规划 
- 14 个 issue.md 状态字段更新为"已裁决"
  - 对应 coord.md ARB-001~022 章节
  - 共 104 处状态字段更新
- 新增 integration-test-phase.md
  - 集成测试与部署验证阶段(P7)规划
  - 6 个批次任务分解
  - 8 条核心 E2E 链路定义
  - 验收标准和退出标准

Coord-AI
2026-07-10 22:05:37 +08:00

16 KiB
Raw Permalink Blame History

core-edu 问题记录

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

§0 已有仲裁核查记录（ai08 接管后核查）

核查日期：2026-07-10 核查范围：01-understanding.md / 02-architecture-design.md 引用的 coord 仲裁结论 核查方法：对照 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-001-ai08：core_edu.proto 实际状态与 coord 仲裁声称不一致（P0）

  • 提请方：ai08

  • 日期：2026-07-10

  • 类型：契约不明确（仲裁状态与代码实际不符）

  • 描述： 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.md §4）

ISSUE-002-ai08：events.proto 未同步 coord topic 命名仲裁（P0）

  • 提请方：ai08

  • 日期：2026-07-10

  • 类型：契约不明确（仲裁未落实到 proto）

  • 描述： 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.md §4）

ISSUE-003-ai08：考试/作业状态命名跨模块不一致（P1）

  • 提请方：ai08

  • 日期：2026-07-10

  • 类型：契约不明确（跨模块命名冲突）

  • 描述： 02-architecture-design.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.md §4）

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.md §4）

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.md §4）

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.md §4）

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）

Reference in New Issue View Git Blame Copy Permalink