feat: auto committed

services/ai/README.md

@@ -1,45 +1,130 @@
 # AI 网关服务
 
-> 版本：0.1（P5 骨架）
-> 端口：3008
+> 版本：1.0（P5 完整实现）
+> 端口：HTTP 3008 + gRPC 50058
+> 定位：D6 智能洞察领域 · 生成子域（Python/FastAPI，严格无状态）
 
 ## 职责
 
-AI 网关限界上下文（Python 实现），统一封装 LLM 调用（多模型路由、重试、限流、成本控制）。
-提供辅助出题、表达优化、分层提问等能力。通过 gRPC 查询 content 题库与 data-ana 学情数据。
+统一封装 LLM 调用（多模型路由 + 故障切换 + 熔断 + 限流 + 成本控制），提供：
+- **聊天**：非流式 + SSE 流式
+- **题目生成**：非流式 + 流式 + 评估三道防线（RuleValidator + LLMJudge + QualityGate）
+- **表达优化**：文字清晰度/简洁度/语气优化
+- **备课工作流**：4 步编排（分析学情 → 推荐知识点 → 生成题目 → 教师审核入库）
+
+通过 gRPC 查询 content 题库与 data-ana 学情数据。通过 Kafka 发布 AIUsageEvent 供 data-ana 统计。
 
 ## 技术栈
 
 - Python 3.12 + FastAPI 0.115
-- Pydantic 2 + pydantic-settings
-- OpenTelemetry（LLM 调用链追踪）
-- prometheus-client + structlog
-- SSE 流式响应
+- Pydantic 2 + pydantic-settings（12-factor 配置）
+- grpc.aio（gRPC server 8 RPC + client 拦截器）
+- aiokafka（用量事件发布，事务性 + 幂等，派生数据豁免 Outbox）
+- Jinja2 + YAML（Prompt 模板渲染）
+- redis（限流令牌桶 + 用量记录 + 工作流状态存储）
+- OpenTelemetry（HTTP + gRPC 链路追踪）
+- prometheus-client + structlog（指标 + 结构化日志）
+
+## 架构分层
+
+```
+HTTP 端点（/v1/ai 前缀，ActionState 信封）
+    ↓
+PermissionGuard（权限校验）→ RateLimiter（三维度令牌桶）
+    ↓
+Service 层（ChatService / QuestionService / ExpressionService / LessonPlanWorkflowService）
+    ↓
+LLM ProviderFailoverChain（4 适配器 + CircuitBreaker）
+    ↓
+LLM Provider（OpenAI / Anthropic / Baichuan / LocalOllama）
+
+gRPC server（端口 50058，8 RPC，interceptor 链）
+    ↓
+AiServicer（proto ↔ domain 模型转换）
+    ↓
+Service 层（同 HTTP）
+
+备课工作流：FastAPI BackgroundTasks + Redis 状态存储（24h TTL）
+安全层：PIIRedactor + InputSanitizer + OutputModerator
+用量：UsageRecorder（Redis）→ KafkaProducer → edu.ai.usage topic
+```
 
 ## 开发
 
 ```bash
+# 安装依赖
 uv sync
-uv run uvicorn src.ai.main:app --reload --port 3008
+
+# 启动开发服务（dev_mode=true 跳过 OTel exporter）
+DEV_MODE=true uv run uvicorn src.ai.main:app --reload --port 3008
+
+# Lint
+uv run ruff check src/
+
+# 测试
+uv run pytest
 ```
 
-## API
+## HTTP API
 
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | /healthz | 健康检查 |
-| POST | /chat | LLM 聊天接口 |
-| POST | /chat/stream | 流式聊天（SSE） |
-| POST | /generate/question | 生成题目 |
-| POST | /optimize/expression | 优化表达 |
-| GET | /metrics | Prometheus 指标 |
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | /healthz | — | liveness |
+| GET | /readyz | — | readiness（含 LLM/gRPC/Provider 状态） |
+| GET | /metrics | — | Prometheus 指标 |
+| POST | /v1/ai/chat | ai:chat | 非流式聊天 |
+| POST | /v1/ai/chat/stream | ai:chat | 流式聊天（SSE） |
+| POST | /v1/ai/generate/question | ai:question:generate | 生成题目 |
+| POST | /v1/ai/generate/question/stream | ai:question:generate | 流式生成题目（SSE） |
+| POST | /v1/ai/optimize/expression | ai:expression:optimize | 优化表达 |
+| POST | /v1/ai/lesson-plan/generate | ai:lesson:generate | 启动备课工作流 |
+| GET | /v1/ai/lesson-plan/status/{workflow_id} | — | 查询工作流状态 |
+| POST | /v1/ai/lesson-plan/confirm/{workflow_id} | ai:lesson:confirm | 教师确认入库 |
+
+所有业务响应统一使用 ActionState 信封：`{success, data, error:{code, message, details?, traceId?}}`
+
+降级采用方案 B（总裁裁决 §2.6）：`success=true + error=null + data 内 degraded=true + degraded_reason`
+
+## gRPC API（端口 50058，8 RPC）
+
+| RPC | 请求 | 响应 |
+|-----|------|------|
+| Chat | ChatRequest | ChatResponse |
+| StreamChat | ChatRequest | stream ChatChunk |
+| GenerateQuestion | GenerateQuestionRequest | GeneratedQuestion |
+| StreamGenerateQuestion | GenerateQuestionRequest | stream GeneratedQuestionChunk |
+| OptimizeExpression | OptimizeExpressionRequest | OptimizedExpression |
+| GenerateLessonPlan | GenerateLessonPlanRequest | LessonPlanResponse |
+| GetLessonPlanStatus | GetLessonPlanStatusRequest | LessonPlanStatus |
+| ConfirmLessonPlan | ConfirmLessonPlanRequest | ConfirmResult |
 
 ## 环境变量
 
 | 变量 | 默认值 | 说明 |
 |------|--------|------|
-| port | 3008 | 服务端口 |
-| openai_api_key | - | OpenAI API 密钥 |
-| anthropic_api_key | - | Anthropic API 密钥 |
+| http_port | 3008 | HTTP 端口 |
+| grpc_port | 50058 | gRPC 端口 |
+| dev_mode | false | 开发模式（跳过 OTel + 权限校验） |
+| openai_api_key | — | OpenAI API 密钥 |
+| anthropic_api_key | — | Anthropic API 密钥 |
+| baichuan_api_key | — | 百川 API 密钥 |
+| ollama_base_url | — | 本地 Ollama 地址 |
+| llm_provider_priority | openai,anthropic,baichuan,local_ollama | Provider 故障切换顺序 |
+| redis_url | redis://localhost:6379/0 | Redis 连接 |
+| kafka_bootstrap_servers | localhost:9092 | Kafka 连接 |
+| kafka_ai_usage_topic | edu.ai.usage | 用量事件 topic |
 | otel_endpoint | http://localhost:4318 | OpenTelemetry OTLP 端点 |
-| log_level | info | 日志级别 |
+
+## 限流（三维度）
+
+| 维度 | 限制 | 算法 |
+|------|------|------|
+| user | 10 req/min | Redis Lua 令牌桶 |
+| IP | 30 req/min | Redis Lua 令牌桶 |
+| school | 100 req/min | Redis Lua 令牌桶 |
+
+Redis 不可用时降级放行（记录警告）。
+
+## 错误码
+
+前缀 `AI_*`，完整 21 个错误码见 [02-architecture-design.md §6.2](docs/02-architecture-design.md)。