Edu/services/content/docs/nextstep.md

content 下一步工作与上下游依赖

模块：content（内容域服务，Textbook/Chapter/KnowledgeGraph/Question 四 Service，端口 HTTP 3005 / gRPC 50054） 负责人：ai09 更新日期：2026-07-13（P4–P6+ 全部完成，Docker 本地测试通过） 关联文档：02-architecture-design.md、content_contract.md、content_workline.md

---

1. 模块当前状态

content 模块已完成 P4–P6+ 全部批次，提供 Textbook / Chapter / KnowledgeGraph / Question 四个 Service 共 22 个 RPC，本地 Docker 镜像构建与运行验证通过（非 mock 数据），ES 全文检索、Neo4j 知识图谱、审核工作流状态机、Outbox 事件驱动全部联调通过。

1.1 服务能力概览

Service	RPC 数量	核心能力
TextbookService	—	教材 CRUD、教材树管理、归档、版本查询
ChapterService	—	章节 CRUD、章节目录树
KnowledgeGraphService	—	知识点 CRUD、知识图谱（Neo4j）、学习路径、前置依赖、可视化
QuestionService	—	题目 CRUD、ES 全文检索、审核工作流状态机、AI 批量出题（待联调）
合计	22	4 Service

1.2 P5 完成项（ES 集成）

验证项	状态	说明
Elasticsearch 容器就绪	✅	本地 Docker edu-es 已就绪
ES config 模块	✅	src/config/elasticsearch.ts（惰性初始化 + ik→standard 回退）
ES Sync Worker（Kafka 消费 → ES 索引）	✅	src/shared/sync/es-sync.worker.ts（event_id 去重 + 软失败）
SearchQuestions API 接入 ES	✅	ES 优先，MySQL LIKE 降级
content_questions 索引映射	✅	ensureQuestionIndex() 幂等创建，ik 不可用时回退 standard
/readyz ES 索引存在性检查	✅	degraded 而非 error

1.3 P6+ 完成项

验证项	状态	说明
Question 审核工作流状态机	✅	draft→pending_review→published/rejected→archived，非法转换拦截
知识图谱可视化 API	✅	GET /knowledge-graph/visualization，Neo4j 优先 + MySQL 降级
教材版本管理	✅	GET /textbooks/versions + POST /textbooks/:id/archive
可观测性硬化	✅	5 个 Prometheus 指标（outbox_pending / neo4j_lag / es_lag / search_total / search_latency）
/readyz Outbox 积压检查	✅	pending > 100 → degraded

1.4 本地 Docker 验证结果（2026-07-13）

测试环境：本地 Docker（edu-mysql + edu-neo4j + edu-es + edu-kafka + edu-redis + edu-content-test，均接入 edu-full_default 网络）

镜像：edu/content:test
容器：edu-content-test（DEV_MODE=true）

测试 1：健康检查
  GET /healthz  → {"status":"ok","service":"content"} ✅
  GET /readyz   → {"status":"ok","dependencies":[mysql:ok, neo4j:ok, kafka:ok, outbox:ok(0), elasticsearch:ok]} ✅

测试 2：REST CRUD（全部通过）
  POST /textbooks        → 创建教材 ✅ (id=l9oo0iycnxlguqvhskjhrksa)
  POST /chapters         → 创建章节 ✅ (id=qdry24sm4ni2lrdf0fe7is2k)
  POST /knowledge-points → 创建知识点 ✅ (id=tuuv90gloo7kf2x1al0b1b6g)
  POST /questions        → 创建题目 ✅ (id=ellr9gi1mnb9ir7ifxukhixs)
  GET  /questions/:id    → 读取题目 ✅ (status=draft)
  GET  /questions?knowledgePointId=... → 列表查询 ✅ (count=1)

测试 3：ES 全文检索
  GET /questions/search?q=3 → total=1 ✅ (ES 索引命中)
  GET /questions/search?q=苹果 → total=0 (standard 分析器中文按字切分，IK 插件可用时改善)

测试 4：审核工作流状态机
  POST /questions/:id/submit-review → draft→pending_review ✅
  POST /questions/:id/approve       → pending_review→published ✅
  POST /questions/:id/archive       → published→archived ✅
  POST /questions/:id/approve       → 非法转换正确拒绝 ✅ (CONTENT_VALIDATION_ERROR)

测试 5：Outbox 事件驱动
  content_outbox_events 表 8 条事件，全部 status=published, retry_count=0 ✅
  事件类型：textbook.created, chapter.created, knowledge_point.created,
            question.created, question.updated×2, question.published, textbook.archived

测试 6：Neo4j 知识图谱同步
  Neo4j KnowledgePoint 节点已创建 ✅ (id=tuuv90gloo7kf2x1al0b1b6g, difficulty=2)
  GET /knowledge-graph/visualization → nodes=1, edges=0 ✅

测试 7：教材归档
  POST /textbooks/:id/archive → status=archived ✅

测试 8：Prometheus 指标
  GET /metrics → content_outbox_pending_total=0, content_neo4j_sync_lag_ms=0,
                 content_es_sync_lag_ms=0, content_question_search_total{source="es"} ✅

---

2. 上游依赖（content 依赖谁）

2.1 MySQL（基础设施）— P0 必需

项	内容
端点	mysql://edu-mysql:3306/next_edu_cloud
用途	主数据存储（textbooks / chapters / knowledge_points / questions / content_outbox_events 表）
状态	✅ 本地 Docker edu-mysql 已就绪
环境变量	DATABASE_URL

2.2 Neo4j（基础设施）— P0 必需

项	内容
端点	bolt://edu-neo4j:7687
用途	知识图谱存储（KnowledgePoint 节点 + PREREQUISITE_OF 关系）
状态	✅ 本地 Docker edu-neo4j 已就绪
环境变量	NEO4J_URL、NEO4J_PASSWORD

2.3 Kafka（基础设施）— P0 必需

项	内容
端点	kafka:29092
用途	Outbox 事件发布（4 个聚合 topic）+ Neo4j Sync Worker 消费 + ES Sync Worker 消费
状态	✅ 本地 Docker edu-kafka 已就绪
环境变量	KAFKA_BROKERS

2.4 Redis（基础设施）— P1 可选

项	内容
端点	redis://edu-redis:6379
用途	缓存（教材树 / 知识点树读多写少场景），env.ts 已预留 REDIS_URL
状态	✅ 本地 Docker edu-redis 已就绪
环境变量	REDIS_URL

2.5 Elasticsearch（基础设施）— P5 必需

项	内容
端点	http://edu-es:9200
用途	题目全文检索（content_questions 索引）
状态	✅ 本地 Docker edu-es 已就绪（profile p5）
环境变量	ES_URL

2.6 ai 服务（ai12 负责）— P5 联调

#	依赖项	用途	状态
1	gRPC GenerateQuestion :50058	AI 批量出题（QuestionService.BatchCreateQuestions 联调）	⏳ 待 ai 服务就绪

关键环境变量：

• AI_GRPC_TARGET=ai:50058（待联调阶段配置）

---

3. 下游依赖（谁依赖 content）

3.1 teacher-bff（ai03 负责）— gRPC :50054

#	依赖项	用途	状态
1	gRPC GetLearningPath(studentId, subjectId) :50054	knowledgePath 查询	✅ content gRPC 已就绪
2	gRPC ListTextbooks(subjectId, gradeId) :50054	教材列表	✅ content gRPC 已就绪
3	gRPC ListChapters(textbookId) :50054	章节目录	✅ content gRPC 已就绪

3.2 student-bff（ai04 负责）— gRPC :50054

#	依赖项	用途	状态
1	gRPC ListTextbooks :50054	学生浏览教材	✅ content gRPC 已就绪
2	gRPC ListChapters :50054	学生浏览章节	✅ content gRPC 已就绪
3	gRPC GetLearningPath :50054	学生学习路径	✅ content gRPC 已就绪
4	gRPC SearchQuestions :50054	题目检索	✅ content ES 已就绪，待 student-bff 联调
5	gRPC BatchCreateQuestions :50054	AI 出题	⏳ 待 ai 服务就绪后联调

3.3 parent-bff（ai05 负责）— gRPC :50054

#	依赖项	用途	状态
1	gRPC ListTextbooks :50054	家长查看孩子教材	✅ content gRPC 已就绪
2	gRPC ListChapters :50054	家长查看孩子章节	✅ content gRPC 已就绪
3	gRPC GetPrerequisites :50054	孩子学习路径前置依赖	✅ content gRPC 已就绪
4	gRPC GetLearningPath :50054	孩子学习路径	✅ content gRPC 已就绪

3.4 data-ana（ai11 负责）— Kafka 消费

#	依赖项	用途	状态
1	消费 topic edu.content.knowledge_point.events	分析知识点难度分布	✅ content Kafka 已就绪
2	消费 topic edu.content.question.events	题目来源统计	✅ content Kafka 已就绪

3.5 api-gateway（ai01 负责）— HTTP REST :3005

能力	配置	状态
/api/v1/textbooks 反向代理	→ content:3005	✅ api-gateway 已配置路由
/api/v1/chapters 反向代理	→ content:3005	✅ api-gateway 已配置路由
/api/v1/knowledge-points 反向代理	→ content:3005	✅ api-gateway 已配置路由
/api/v1/questions 反向代理	→ content:3005	✅ api-gateway 已配置路由
GET /healthz 端点	/readyz 下游健康检查	✅ 已实现

3.6 ai 服务（ai12 负责）— Kafka 消费

#	依赖项	用途	状态
1	消费 topic edu.content.question.events	AI 出题时获取知识点信息	✅ content Kafka 已就绪

---

4. 环境变量清单

变量	必填	示例值	说明
PORT	是	3005	HTTP 监听端口
GRPC_PORT	是	50054	gRPC 监听端口
DATABASE_URL	是	mysql://edu:changeme@edu-mysql:3306/next_edu_cloud	MySQL 连接
REDIS_URL	否	redis://edu-redis:6379	Redis 缓存
NEO4J_URL	否	bolt://edu-neo4j:7687	Neo4j 连接
NEO4J_PASSWORD	否	changeme	Neo4j 密码
ES_URL	否	http://edu-es:9200	Elasticsearch 连接
KAFKA_BROKERS	是	kafka:29092	Kafka broker
JWT_SECRET	否	—	JWT 密钥
DEV_MODE	否	false	开发模式
OTEL_EXPORTER_OTLP_ENDPOINT	否	http://otel-collector:4318	OTLP 端点
LOG_LEVEL	否	info	日志级别

---

5. 剩余工作

#	工作项	阶段	状态
1	ES 集成（config + sync worker + search API）	P5	✅ 完成
2	Question 审核工作流状态机	P6+	✅ 完成
3	知识图谱可视化 API	P6+	✅ 完成
4	教材版本管理	P6+	✅ 完成
5	可观测性硬化（Prometheus 指标 + readyz 检查）	P6+	✅ 完成
6	AI 批量出题联调（BatchCreateQuestions + ai12）	联调	⏳ 待 ai 服务就绪

content 模块自身功能已全部完成，无剩余开发任务。唯一待办为 ai 服务（ai12）就绪后的 AI 出题联调。

---

6. Docker 本地测试

6.1 镜像构建

docker build -t edu/content:test -f services/content/Dockerfile .

6.2 容器启动

docker run -d \
  --name edu-content-test \
  --network edu-full_default \
  -p 3005:3005 -p 50054:50054 \
  -e DATABASE_URL=mysql://edu:changeme@edu-mysql:3306/next_edu_cloud \
  -e NEO4J_URL=bolt://edu-neo4j:7687 \
  -e NEO4J_PASSWORD=changeme \
  -e ES_URL=http://edu-es:9200 \
  -e KAFKA_BROKERS=kafka:29092 \
  -e REDIS_URL=redis://edu-redis:6379 \
  -e NODE_ENV=production \
  -e DEV_MODE=true \
  edu/content:test

---

7. 关键文件路径

文件	用途
packages/shared-proto/proto/content.proto	gRPC 契约（22 RPC）
packages/shared-proto/proto/events.proto	事件契约（4 content message）
services/content/src/main.ts	服务入口
services/content/src/app.module.ts	NestJS 模块注册
services/content/src/grpc/	4 个 gRPC controller
services/content/src/shared/outbox/	Outbox 模式实现
services/content/src/shared/sync/neo4j-sync.worker.ts	Neo4j 异步同步
services/content/Dockerfile	Docker 构建
docs/architecture/issues/contracts/content_contract.md	契约文档
docs/architecture/issues/worklines/content_workline.md	工作排期

---

本文件由 ai09 维护，上游/下游工作项请各负责 AI 完成后通知 ai09 更新状态。