xiner/Edu

Files

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

2026-07-10 15:28:20 +08:00

18 KiB

Raw Permalink Blame History

core-edu 对接契约

负责人：ai08 关联：matrix.md、core_edu.proto、events.proto、services/core-edu/docs/02-architecture-design.md、objections/core-edu_issue.md 状态说明：本契约按 P3 目标态描述。P2 已就绪部分标注 ✅，P3 待实施部分标注 ⏳（依赖 objections/core-edu_issue.md ISSUE-001 ~ ISSUE-006 仲裁结果）

§1 我提供什么（对外接口）

1.1 gRPC 接口（P3 启用，端口 50053）

包名：next_edu_cloud.core_edu.v1（coord-cross-review §2.1 仲裁）总计 5 Service / 27 RPC（含 P3 新增 5 RPC）注：当前 core_edu.proto 实际仅 3 Service / 14 RPC，缺 ClassService + AttendanceService + P3 新增 RPC（见 ISSUE-001）

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

统计：

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 事件发布

Topic 命名遵循 coord-cross-review §3.1 仲裁：edu.teaching.<aggregate>.<action> 所有事件 payload 必须含：schema_version（默认 "v1"）+ event_id（UUID）+ occurred_at（业务时间戳）+ metadata: { traceId, userId } 注：当前 events.proto 仍用旧 topic 命名 + 缺 schema_version 字段 + 缺 AttendanceEvent message（见 ISSUE-002）

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

注意：

class.transferred 的 topic 命名存在跨文档不一致（ISSUE-004），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 仲裁：子域统一 CORE_EDU_*，不再细分 EXAMS_/HOMEWORK_/GRADES_）

完整错误码清单见 02-architecture-design.md §6.2。

1.7 响应信封

所有 HTTP/gRPC 响应遵循 ActionState 信封（004 §11.5）：

{
  success: boolean,
  data?: T,
  error?: { code: string, message: string, details?: unknown, traceId?: string }
}

§2 我消费什么（依赖上游）

2.1 gRPC 调用（同步）

调用方	目标服务	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 命名遵循 004 §7.2 事件分类

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 调用。

§3 就绪信号

3.1 我依赖的上游就绪标志

依赖项	提供方	就绪信号	状态
coord 仲裁 ISSUE-001 ~ ISSUE-006	coord	coord.md 仲裁章节	⏳ 待仲裁
core_edu.proto 补全	coord 或 ai08	5 Service / 27 RPC 定义	⏳（见 ISSUE-001）
events.proto 同步	coord	含 AttendanceEvent + schema_version + `edu.teaching.*` 注释	⏳（见 ISSUE-002）
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 我的就绪标志（供下游消费）

阶段	就绪信号	消费方	状态
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（供下游消费）

在 core-edu 真实服务就绪前，为下游（teacher-bff / student-bff / parent-bff / content / msg / data-ana）提供以下 mock：

gRPC mock（使用 grpc-mock 拦截 50053 端口）：

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：

依赖	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

待确认项	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.<aggregate>.<action>`（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）

18 KiB Raw Permalink Blame History Unescape Escape