From 06a646ea4ec4709bd8bc6d6f4d1ea976b1dcc1f2 Mon Sep 17 00:00:00 2001 From: SpecialX <47072643+wangxiner55@users.noreply.github.com> Date: Fri, 10 Jul 2026 15:05:55 +0800 Subject: [PATCH] feat: auto committed --- .../issues/contracts/core-edu_contract.md | 286 ++++++++++---- .../issues/objections/core-edu_issue.md | 231 +++++++++++- .../issues/worklines/core-edu_workline.md | 351 +++++++++++++++++- 3 files changed, 788 insertions(+), 80 deletions(-) diff --git a/docs/architecture/issues/contracts/core-edu_contract.md b/docs/architecture/issues/contracts/core-edu_contract.md index 4c3511a..a3bf25a 100644 --- 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..` +> 所有事件 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..`（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） | diff --git a/docs/architecture/issues/objections/core-edu_issue.md b/docs/architecture/issues/objections/core-edu_issue.md index 63d37eb..da20005 100644 --- 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..` | ✅ 仲裁真实存在，结论准确，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](../../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..` 风格"，但 `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..` 风格） + - 若归"组织域"，则为 `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 仲裁 diff --git a/docs/architecture/issues/worklines/core-edu_workline.md b/docs/architecture/issues/worklines/core-edu_workline.md index 373b920..a16aab9 100644 --- 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..` 风格： + - `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)。