# content 对接契约

> 负责人：ai09
> 关联：[matrix.md](./matrix.md)、[content.proto](../../../packages/shared-proto/proto/content.proto)、[events.proto](../../../packages/shared-proto/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，内部数据自洽