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.设计规格文档
5.9 KiB
5.9 KiB
ai 对接契约
负责人：ai12 关联：matrix.md、ai.proto、events.proto
§1 我提供什么（对外接口）
1.1 gRPC 接口（如有）
| Service | RPC | 请求 | 响应 | 端口 |
|---|---|---|---|---|
| AiService | Chat | ChatRequest | ChatResponse | 50057 |
| AiService | StreamChat | ChatRequest | stream ChatChunk | 50057 |
| AiService | GenerateQuestion | GenerateQuestionRequest | GeneratedQuestion | 50057 |
| AiService | OptimizeExpression | OptimizeExpressionRequest | OptimizedExpression | 50057 |
| AiService | GenerateLessonPlan | GenerateLessonPlanRequest | LessonPlan | 50057 |
| AiService | StreamGenerateQuestion | StreamGenerateQuestionRequest | stream GeneratedQuestion | 50057 |
1.2 HTTP 端点（如有）
无对外 HTTP 端点，仅 gRPC（含 2 个 Server Streaming RPC：StreamChat / StreamGenerateQuestion）。
1.3 GraphQL schema（如 BFF）
不适用。
1.4 Kafka 事件发布（如有）
| Topic | Event | 消费方 |
|---|---|---|
| edu.ai.usage.events | AIUsageEvent（operation: chat/generate_question/optimize_expression/lesson_preparation） | data-ana |
注：AIUsageEvent 豁免 Outbox 模式（派生数据事件，见 004 §12.2 + §15.3 #6）。
1.5 错误码前缀
AI_（如 AI_PROVIDER_UNAVAILABLE、AI_TOKEN_LIMIT_EXCEEDED、AI_CONTENT_FILTERED）
§2 我消费什么（依赖上游）
2.1 gRPC 调用（同步）
| 被调用方 | Service.RPC | 用途 | mock 策略 |
|---|---|---|---|
| content (ai09) | KnowledgeGraphService.GetPrerequisites | 生成题目时获取知识点前置依赖 | content 就绪前使用本地知识点 stub（固定 3 个前置知识点） |
| content (ai09) | QuestionService.SearchQuestions | 备课时检索同类题目参考 | content 就绪前返回空列表 |
| data-ana (ai11) | AnalyticsService.GetStudentWeakness | 个性化出题时获取学生薄弱点 | data-ana 就绪前使用本地薄弱点 stub（固定 2 个 weak_points） |
2.2 Kafka 事件订阅（异步）
| Topic | Event | 发布方 | mock 策略 |
|---|---|---|---|
| edu.content.knowledge_point.events | KnowledgePointEvent | content (ai09) | content 就绪前不订阅，使用内置知识点表 |
| edu.content.question.events | QuestionEvent | content (ai09) | content 就绪前忽略 |
2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 |
|---|---|---|---|
| LLM Provider（OpenAI/百川/本地） | POST /v1/chat/completions | 调用大模型生成内容 | 开发期使用本地 mock server 返回固定 ChatResponse，不消耗真实 token |
§3 就绪信号
3.1 我依赖的上游就绪标志
- content gRPC 50054 启用（ai09）—— 知识点维度 + 题库检索
- edu.content.knowledge_point.events topic 有事件发布（ai09）
- data-ana gRPC 50055 启用（ai11）—— 学生薄弱点（可选，ai 可先独立运行）
3.2 我的就绪标志（供下游消费）
- ai gRPC 50057 启用（HealthService.Check 返回 SERVING）
- AiService.Chat / StreamChat 可调用（含流式响应）
- AiService.GenerateQuestion / StreamGenerateQuestion 可调用
- AiService.GenerateLessonPlan 可调用（P5 补全）
- AiService.OptimizeExpression 可调用
- edu.ai.usage.events topic 可发布（供 data-ana 统计 AI 用量）
§4 Mock 策略
4.1 我提供的 mock
在 ai 真实服务就绪前，为下游（teacher-bff）提供以下 mock：
- gRPC mock：使用 grpc-mock 拦截 50057 端口
- AiService.Chat 返回固定 ChatResponse（content="这是 AI 助手的模拟回复"）
- AiService.StreamChat 返回固定流（3 个 ChatChunk，最后一个 done=true）
- AiService.GenerateQuestion 返回固定 GeneratedQuestion（question/answer/explanation）
- AiService.GenerateLessonPlan 返回固定 LessonPlan（3 个 LessonSection）
- AiService.StreamGenerateQuestion 返回固定流（2 个 GeneratedQuestion）
- Kafka mock：ai 就绪前不发布真实 AIUsageEvent，data-ana 仪表盘 AI 用量显示"暂无数据"
4.2 我消费的 mock
在真实上游就绪前，ai 使用以下 mock：
- LLM Provider mock：本地启动 mock server，POST /v1/chat/completions 返回固定 JSON（不消耗真实 token，不产生费用）
- content 知识点：内置固定知识点表（数学 20 个知识点 + 前置依赖关系），不依赖 content gRPC
- data-ana 薄弱点：内置固定学生薄弱点（2 个 weak_points），不依赖 data-ana gRPC
- 事件订阅：不订阅 content 事件，知识点维度表静态