faaaf29f67
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md) 2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration) 3.各服务 01/02 文档补全 4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens) 5.Proto 契约补全 6.004 架构影响地图更新 7.端口分配表 8.设计规格文档
6.0 KiB
6.0 KiB
content 对接契约
负责人：ai09 关联：matrix.md、content.proto、events.proto
§1 我提供什么（对外接口）
1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
|---|---|---|---|---|
| TextbookService | CreateTextbook | CreateTextbookRequest | Textbook | 50054 |
| TextbookService | GetTextbook | GetTextbookRequest | Textbook | 50054 |
| TextbookService | ListTextbooks | ListTextbooksRequest | ListTextbooksResponse | 50054 |
| ChapterService | GetChapter | GetChapterRequest | Chapter | 50054 |
| ChapterService | ListChapters | ListChaptersRequest | ListChaptersResponse | 50054 |
| ChapterService | CreateChapter | CreateChapterRequest | Chapter | 50054 |
| ChapterService | UpdateChapter | UpdateChapterRequest | Chapter | 50054 |
| KnowledgeGraphService | GetPrerequisites | GetPrerequisitesRequest | KnowledgePointsResponse | 50054 |
| KnowledgeGraphService | GetLearningPath | GetLearningPathRequest | LearningPath | 50054 |
| KnowledgeGraphService | AddPrerequisite | AddPrerequisiteRequest | AddPrerequisiteResponse | 50054 |
| KnowledgeGraphService | RemovePrerequisite | RemovePrerequisiteRequest | RemovePrerequisiteResponse | 50054 |
| QuestionService | CreateQuestion | CreateQuestionRequest | Question | 50054 |
| QuestionService | GetQuestion | GetQuestionRequest | Question | 50054 |
| QuestionService | ListQuestions | ListQuestionsRequest | ListQuestionsResponse | 50054 |
| QuestionService | UpdateQuestion | UpdateQuestionRequest | Question | 50054 |
| QuestionService | DeleteQuestion | DeleteQuestionRequest | DeleteQuestionResponse | 50054 |
| QuestionService | PublishQuestion | PublishQuestionRequest | PublishQuestionResponse | 50054 |
| QuestionService | SearchQuestions | SearchQuestionsRequest | SearchQuestionsResponse | 50054 |
1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC。
1.3 GraphQL schema（如 BFF）
不适用。
1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
|---|---|---|
| edu.content.knowledge_point.events | KnowledgePointEvent（action: created/updated/prerequisite_added/prerequisite_removed） | data-ana / ai / Neo4j Sync Worker / ES Sync Worker |
| edu.content.question.events | QuestionEvent（action: created/updated/published/deleted） | data-ana |
1.5 错误码前缀
CONTENT_（如 CONTENT_TEXTBOOK_NOT_FOUND、CONTENT_QUESTION_DUPLICATE）
§2 我消费什么（依赖上游）
2.1 gRPC 调用（同步）
无直接 gRPC 调用上游。content 通过 Kafka 事件接收 core-edu 班级/学生变更用于数据一致性。
2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
|---|---|---|---|
| edu.class.events | ClassEvent（action: transferred） | core-edu (ai08) | core-edu 就绪前不订阅，content 内部不依赖班级实时数据 |
| edu.exam.events | ExamEvent | core-edu (ai08) | core-edu 就绪前忽略，题目关联知识点不依赖考试事件 |
2.3 HTTP 调用（如有）
无。
§3 就绪信号
3.1 我依赖的上游就绪标志
- core-edu gRPC 50053 启用（ai08）—— 用于知识点与班级关联（可选，content 可先独立运行）
- edu.class.events / edu.exam.events topic 有事件发布（ai08）
3.2 我的就绪标志（供下游消费）
- content gRPC 50054 启用（HealthService.Check 返回 SERVING）
- TextbookService 3 RPC 可调用
- ChapterService 4 RPC 可调用
- KnowledgeGraphService 4 RPC 可调用（GetPrerequisites/GetLearningPath/AddPrerequisite/RemovePrerequisite）
- QuestionService 7 RPC 可调用（含 SearchQuestions 全文检索）
- edu.content.knowledge_point.events / edu.content.question.events topic 可发布
§4 Mock 策略
4.1 我提供的 mock
在 content 真实服务就绪前，为下游（teacher-bff / student-bff / ai / data-ana）提供以下 mock：
- gRPC mock：使用 grpc-mock 拦截 50054 端口
- TextbookService.ListTextbooks 返回固定 5 个 Textbook（语数英理化）
- ChapterService.ListChapters 返回固定章节树（每教材 10 章）
- KnowledgeGraphService.GetLearningPath 返回固定 8 个 KnowledgePoint 推荐顺序
- KnowledgeGraphService.GetPrerequisites 返回固定 3 个前置知识点
- QuestionService.SearchQuestions 返回固定 20 个 Question（含 options）
- Kafka mock：content 就绪前不发布真实事件，下游使用本地 stub
4.2 我消费的 mock
在真实 core-edu 就绪前，content 使用以下 mock：
- 班级/学生数据：不依赖 core-edu 实时数据，知识点关联使用固定 subject_id/grade
- 事件订阅：不订阅 edu.class.events / edu.exam.events，内部数据自洽