Edu/services/content/docs/01-understanding.md

模块理解确认书 — content

AI 标识：ai05（初稿）→ ai09（复核与阶段 2 接手） 负责模块：content（P4）— 按 ai-allocation.md §3.2 最新分配，content 由 ai09 专责 阶段：架构设计外包 · 阶段 1（全局理解，ai05 初稿）+ ai09 复核 日期：2026-07-09（初稿）/ 2026-07-09（ai09 复核） 关联文档：ai-allocation.md、004 架构影响地图、pending-features.md、coord-cross-review.md、known-issues.md

---

1. 我在架构中的位置

• 层级：业务微服务层（L5），DDD 限界上下文
• 业务领域：D4 内容资源领域（004 §1.1b）
• 上游（谁调用我）：
  • teacher-bff（3003）：教学场景聚合，教师查教材/知识点/题库
  • student-bff（学习场景，P3 起）：学生查学习路径、知识点前置
  • ai（Python，P5）：gRPC 查询知识点/题库用于 AI 出题（004 §4.1 AI -.gRPC.-> Content，§9.3 AI 辅助出题流程）
• 下游（我调用谁）：
  • MySQL（写模型主库，独占）
  • Neo4j（知识图谱，前置依赖图）
  • Elasticsearch（题库全文检索，P4 后续补充，当前未实现）
• 通信方式：
  • 当前：HTTP REST（Controller，无 gRPC controller）
  • 目标态（004 §4.1 / pending-features P4）：gRPC 暴露 TextbookService + KnowledgeGraphService
  • Kafka：消费 core-edu 教学内容变更通知（004 §4.1 CoreEdu -.事件.-> Content）；发布 edu.content.question.published（004 §7.2）
• 端口：3005（见 content env.ts）

2. 我的限界上下文

• 聚合职责：管理 Textbook（教材）、Chapter（章节）、KnowledgePoint（知识点）、Question（题库）四个聚合
• 我的数据属于：D4 内容资源领域
• 我不负责：
  • 不负责学情分析（D6，由 data-ana 承载）
  • 不负责考试/作业/成绩（D3，由 core-edu 承载）
  • 不负责通知分发（D5，由 msg 承载）
  • 不直接访问 core-edu / iam / msg 的数据库
• 现有骨架领域模块（4 个，见 content/src）：
  • textbooks/：教材 CRUD（5 端点）
  • chapters/：章节 CRUD（5 端点，按 textbook 查询）
  • knowledge-points/：知识点 CRUD + Neo4j 知识图谱（7 端点，含前置链路查询/添加）
  • questions/：题库 CRUD（5 端点，4 种题型校验）

3. 我与外部的契约

• 消费的 proto message（从 shared-proto）：
  • 无直接消费其他服务 proto；通过 Kafka 事件接收 core-edu 教学内容变更（事件契约见 events.proto）
• 暴露的契约（见 content.proto，包名 next_edu_cloud.content.v1）：
  • TextbookService：CreateTextbook / GetTextbook / ListTextbooks
  • KnowledgeGraphService：GetPrerequisites / GetLearningPath
  • 当前实现均为 REST，gRPC controller 未实现（proto 已定义待迁移）
• 事件契约：
  • 发布：edu.content.question.published（题库新增/发布，消费者 AI、ES，见 004 §7.2）
  • 消费：core-edu 教学内容变更事件（004 §4.1，具体 topic 待 core-edu ai03 设计确认）
• 错误码前缀：CONTENT_*（CONTENT_VALIDATION_ERROR / NOT_FOUND / PERMISSION_DENIED / CONFLICT / BUSINESS_ERROR / DATABASE_ERROR / INTERNAL_ERROR，见 application-error.ts）
• 权限点（16 个，见 permission.guard.ts）：
  • CONTENT_TEXTBOOK_{CREATE,READ,UPDATE,DELETE}
  • CONTENT_CHAPTER_{CREATE,READ,UPDATE,DELETE}
  • CONTENT_QUESTION_{CREATE,READ,UPDATE,DELETE}
  • CONTENT_KNOWLEDGE_POINT_{CREATE,READ,UPDATE,DELETE}

4. 我的技术栈

• 语言：TypeScript 5.6（ESM 模式，相对 import 带 .js 后缀）
• 框架：NestJS 10
• ORM：Drizzle ORM 0.31 + mysql2 3.11
• 知识图谱：neo4j-driver 5.23（PREREQUISITE_OF 关系，Cypher 查询深度 1..5）
• 全文检索：Elasticsearch（待引入，env.ts 预留 ES_URL 但 package.json 未装 @elastic/elasticsearch）
• 可观测：pino logger + prom-client metrics + OpenTelemetry tracer（三支柱已具备）
• 消息总线：Kafka（待引入，pending-features P4 未明确要求 content 发事件，但 004 §7.2 列了 edu.content.question.published）

5. 我的阶段归属

• P4 内容分析阶段（pending-features §P4）：
  • 教材/章节/知识点 CRUD（仅 CRUD，不实现检索）+ 知识图谱查询（Neo4j）+ 题库 CRUD（不实现检索）
  • MySQL schema：textbooks / chapters / knowledge_points / questions
  • Neo4j 数据：知识点前置依赖图（从 MySQL 同步）
  • CDC 链路：Debezium 监听 MySQL binlog → Kafka → data-ana 消费写 ClickHouse
• 退出标准：教师查看知识图谱前置依赖（Neo4j 秒级返回）→ 学生查看学情诊断（ClickHouse 宽表 5s 内返回）→ CDC 链路延迟 < 5s
• 依赖上游：P1 黄金模板 classes（横切关注点对齐）、P3 core-edu（教学内容变更事件，待 ai03 设计确认 topic）

6. 我需要对齐的黄金模板项（对照 classes 服务）

• 权限装饰器 @RequirePermission（16 个 CONTENT_* 权限点，全部 Controller 方法已覆盖）
• 错误码前缀统一（CONTENT_*）
• logger / metrics / tracer 三支柱（已具备）
• /healthz 健康检查（HealthModule 已注册）
• [⚠️] /readyz（仅检查 DB SELECT 1，未检查 Neo4j 连通性，Neo4j 故障时仍返回 ok）
• 优雅关闭 SIGTERM（main.ts 已处理：closeNeo4j → closeDb → shutdownTracer）
• 测试覆盖率 ≥ 80%（当前 0%，无测试文件）
• Dockerfile 多阶段构建（已具备）
• [⚠️] Zod 输入验证（questions 用 service 层手动 if 校验抛 ValidationError，非 Controller 层 schema.parse）
• GlobalErrorFilter 统一兜底

7. 现有骨架差距与待决策（提请 coord 仲裁）

#	差距	影响	提请决策
C1	ES 完全未实现：env.ts 预留 ES_URL 但无 @elastic/elasticsearch 依赖、无 config/elasticsearch.ts、无 service 调用	P4 退出标准要求题库检索，pending-features 注明"P4 仅 CRUD，P5 引入 ES"	确认 content 的 ES 检索归属 P4 还是 P5（004 §2.2 列 ES 使用者为 Content、AI）
C2	无 Outbox / Kafka：骨架无 shared/outbox/，无 Kafka producer/consumer	004 §7.2 列 edu.content.question.published 事件需发布	确认 content 是否需 Outbox（iam 无 Outbox，core-edu 有）
C3	README 与实现脱节：README 声称 TextbooksService.createKnowledgeGraph 和 getPrerequisites，源码中 createKnowledgeGraph 不存在，getPrerequisites 在 KnowledgePointsService	文档误导	阶段 2 设计需同步修正 README
C4	gRPC 未实现：proto 定义了 TextbookService/KnowledgeGraphService，但无 gRPC controller	pending-features P4 未强制 gRPC，004 §4.1 目标态 gRPC	确认 P4 是否启用 gRPC（ai03 提请统一决策）
C5	schema 定义分散：textbooks.schema.ts 定义 3 张表（textbooks/chapters/knowledgePoints），chapters/knowledge-points schema 仅 re-export；questions.schema.ts 独立	维护成本	阶段 2 设计统一 schema 归属
C6	DB 连接模式与 iam 不一致：content 用模块级 const db，iam 用 getDb() 函数式懒加载	测试 mock 困难	coord 已在 known-issues 记录"db 常量导出对齐黄金模板"，需确认统一方向
C7	表时间戳不统一：textbooks/questions 有 created_at+updated_at，chapters/knowledge_points 无时间戳	审计追踪缺失	阶段 2 设计补齐
C8	无外键约束：questions.knowledge_point_id → knowledge_points.id 等无 Drizzle 外键	引用完整性靠应用层	阶段 2 设计评估是否加外键
C9	addPrerequisite 降级策略不一致：safeCreateNode 非阻塞（Neo4j 失败仅 warn），addPrerequisite 在 Neo4j 不可用时抛 InternalError	行为不一致	阶段 2 设计统一降级策略
C10	proto 包名：实际 next_edu_cloud.content.v1，project_rules §5 规定 edu.content.v1	命名规范不一致	coord 仲裁（ai03 已提请）

---

服务审计表 — ai05（content 部分）

审计标准对照 project_rules §3 与 known-issues §2.2 classes 黄金模板

服务	权限装饰器	错误码前缀	logger	metrics	tracer	/healthz	/readyz	优雅关闭	测试覆盖率	Dockerfile
content	✅ 16 端点全覆盖	✅ CONTENT_*	✅ pino	✅ prom-client	✅ OTel + auto-instrumentations	✅	⚠️ 仅 DB 不查 Neo4j	✅ closeNeo4j→closeDb	0%	✅

---

跨模块契约对齐提请（coord 交叉审查）

接口一致性检查（content 相关）

本服务声明	对方服务声明	是否匹配	备注
ai05 content: 暴露 KnowledgeGraphService.GetPrerequisites	ai06 ai: 调 content 查知识点（004 §9.3）	⚠️ 待确认	ai06 设计文档需确认调用签名
ai05 content: 暴露 TextbookService.ListTextbooks	ai03 teacher-bff: 聚合 content 查教材（004 §4.1）	⚠️ 待确认	ai03 设计文档需确认调用
ai05 content: 发布 edu.content.question.published	ai06 ai: 消费题库事件（004 §7.2 消费者 AI）	⚠️ 待确认	ai06 设计需确认是否消费

全局冲突检查（content 相关）

检查项	检查结果	备注
端口不冲突	✅ content 3005	与 iam(3002)/classes(3001)/teacher-bff(3003)/core-edu(3004)/data-ana(3006)/msg(3007)/ai(3008) 不冲突
Topic 不重复	⚠️ 待汇总	content 发布 edu.content.question.published
错误码前缀不重叠	✅ CONTENT_* 唯一	与 iam IAM_* / core-edu CORE_EDU_* / msg MSG_* 不重叠
Proto message 不遗漏	⚠️ 待确认	content.proto 缺 Update/Delete/分页（对比 classes.proto 有 page_token）
proto 包名规范	⚠️ 不一致	实际 next_edu_cloud.<domain>.v1，规则要求 edu.<domain>.v1，提请 coord 仲裁（ai03 已提请）

待 coord 仲裁的决策项（content 相关）

1. proto 包名统一：next_edu_cloud.* vs edu.*（影响全部 proto，需 coord 决策）
2. gRPC 启用时机：P4/P5 是否启用 gRPC controller，还是继续 REST（影响 content/msg/iam/core-edu 全部服务）
3. content ES 检索归属：P4（pending-features 注明"P4 仅 CRUD，P5 引入 ES"）vs 004 §2.2（列 ES 使用者 Content、AI）—— 需明确 content 何时引入 ES
4. content Outbox：是否需要（004 §7.2 列 content 发事件，但 pending-features P4 未要求）

---

下一步

1. 等待 coord 审核本确认书（跨模块契约对齐 + 仲裁项）
2. coord 放行后进入阶段 2：模块架构设计文档，按 ai-allocation.md §7 模板产出：
   • content 模块架构设计文档（含 Neo4j 图模型、ES 索引 mapping、题库 CRUD API、与 ai 的 gRPC 接口、教材/章节结构树）
3. 阶段 2 设计完成后同步更新 README（修正 §C3 文档脱节问题）

---

ai09 复核记录（2026-07-09）

ai05 初稿覆盖了位置/限界上下文/契约/技术栈/黄金模板对齐/差距 10 项，作为阶段 1 的骨架是合格的。ai09 在接手阶段 2 前，对初稿做以下复核与补强，依据为 coord-cross-review.md 已仲裁结论与 004 §4.2/§7.2/§11.2/§12.2 最新修订：

A. 已仲裁项状态更新（原 C 列待决策项 → 已裁决）

原编号	原待决策	coord 裁决	状态
C2	content 是否需 Outbox	需要。004 §7.2 列 edu.content.question.published 为领域事件，004 §12.2 规定领域事件强制 Outbox 模式（业务事务事件不豁免）	✅ 已裁决：P4 必须引入 Outbox
C4	gRPC 启用时机	P4 启用。004 §4.2 gRPC 启用阶段矩阵明确：P4 content + data-ana 启用 gRPC server	✅ 已裁决：P4 必须实现 gRPC controller
C10	proto 包名规范	保持现状 next_edu_cloud.content.v1。coord 已修订 project_rules §5 与 004 §11.2	✅ 已裁决

B. 初稿遗漏项（必须在阶段 2 补全）

#	遗漏	依据	阶段 2 处理
L1	教材/章节结构树缺 section 层级	ai-allocation §5 ai09 任务：textbook → chapter → section → knowledge-point 四级结构	数据模型补 content_sections 表
L2	题库批量导入 Excel/CSV 完整未设计	ai-allocation §5 明确要求"题库 CRUD 完整 API（含批量导入 Excel/CSV）"	API 设计补 POST /questions/batch-import + 异步任务 + 模板下载
L3	知识图谱可视化数据 API 缺失	ai-allocation §5 明确要求"知识图谱可视化数据 API"	API 设计补 GET /knowledge-graph/visualization 返回 nodes/edges 结构
L4	与 ai12（ai 服务）的 gRPC 接口未细化	ai-allocation §5 明确要求"查询知识点/题库用于 AI 出题" + 004 §9.3 AI 辅助出题流程	契约设计补 QuestionBankService.ListQuestions/SearchQuestions/BatchCreateQuestions
L5	ES 索引 mapping 完整未设计	ai-allocation §5 明确要求"ES 索引 mapping 设计（题库全文检索 + 标签过滤 + 难度/年级 facet）"	阶段 2 完整设计 mapping，但实现归属 P5（pending-features P5 才引入 ES）
L6	readyz 未检查 Neo4j 连通性	阶段 1 §C 已识别但未决议	阶段 2 横切关注点补 Neo4j 健康检查
L7	题目审核状态机未设计	长远考虑：教师录入/AI 生成/审核/发布/归档的全生命周期	阶段 2 领域模型补 Question.status 状态机
L8	题库版本化与协作编辑未考虑	长远考虑：教材版本变更、多人协作出题	阶段 2 数据模型补 version/updated_by/lock_version 字段
L9	DataScope 下推未在 Repository 体现	004 §5.3 DataScope 6 级需 Repository 注入 WHERE	阶段 2 Repository 设计补 DataScope 下推
L10	题目/知识点与学科年级的多对多关联未明确	跨教材/跨学科复用题目需多对多	数据模型补 content_question_grades/content_kp_grades 关联表
L11	AI 生成题目回写契约	004 §9.3：教师审核后入库 → content.CreateQuestions	契约设计补 QuestionBankService.BatchCreateQuestions
L12	知识点掌握度反查（data-ana → content 反向查询）未设计	004 §8.3 闭环：掌握度更新后推荐练习	契约补 KnowledgeGraphService.GetRecommendations(mastery)

C. 长远架构必须铺垫的方面（ai09 在阶段 2 重点设计）

维度	铺垫点	理由
多版本教材并存	textbook.version 字段 + 教材版本切换不破坏题库引用	K12 教材迭代周期长但必须支持新旧版本共存
跨学科知识图谱	Neo4j 节点带 subject_id，未来跨学科知识关联（数学→物理前置）	长远支撑综合题、跨学科出题
题目去重/相似度	设计 content 字段长度 + 未来 embedding 字段占位	AI 批量出题必然带来重复检测需求
ES 与 MySQL 双写一致性	阶段 2 设计 CDC/Outbox → ES 投递方案（P5 落地）	避免 P5 引入 ES 时再重构数据流
知识图谱版本控制	Neo4j 节点带 version/textbook_id 属性	教材版本切换时图谱可追溯
国际化（i18n）	题目/知识点 content 字段预留 lang 维度	未来支持少数民族语言版本
题库审核工作流	Question.status 状态机 + 审核记录表	接入 Temporal 工作流时无需重构
gRPC Streaming 出题	契约预留 StreamGenerateQuestions 方法占位	AI 流式出题未来需求

---

AI Agent: ai09 (content) Coordinator: coord-ai Branch: 单仓库并行模式（直接 push main） 阶段 1 状态: ✅ ai05 初稿 + ai09 复核补强完成，进入阶段 2