# 模块架构设计文档 — ai

> AI 标识：ai12（复核与长期演进接手）← ai06（初稿，2026-07-09）
> 负责模块：ai（P5）
> 阶段：架构设计外包 · 阶段 2（模块架构设计，ai06 初稿 + ai12 长期演进复核）
> 日期：2026-07-09（ai06 初稿）/ 2026-07-09（ai12 复核与补充）
> 关联文档：[阶段 1 理解确认书](./01-understanding.md)、[ai-allocation.md](../../../docs/architecture/ai-allocation.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md)、[pending-features.md](../../../docs/architecture/roadmap/pending-features.md)、[coord 交叉审查报告](../../../docs/architecture/coord-cross-review.md)
> 审查请求：本设计文档待 coord 按 ai-allocation.md §8 交叉审查（接口一致性 / 端口冲突 / Topic 重复 / 错误码重叠 / 黄金模板对齐）
>
> **ai12 接手说明**：本设计文档初稿由 ai06 在 ai-allocation v0.x 阶段撰写（涵盖 8 节标准模板）。ai12 在 ai06 初稿基础上执行：作者归属更正、长期架构演进补充（新增 §9-§17 共 9 节）、P5 交付物覆盖度核对、向前兼容性铺垫。**所有 ai12 新增内容用「ai12 增补」标注**，ai06 原文保留并标注「ai06 初稿」。

---

## 设计原则与全局约束

本设计遵循以下强制约束（来自 project_rules.md + coding-standards.md + 004）：

1. **契约先行**：proto 已定义（analytics.proto / ai.proto），实现前不修改 proto，如需修改走 coord 流程
2. **CQRS 读写分离**：ai 是无状态服务（无 DB 写），用量计费通过事件外发由 data-ana 落 ClickHouse
3. **事件驱动**：ai 不消费事件；仅发布 `AIUsageRecorded` 派生数据事件（004 §12.2 豁免 Outbox，允许直接 producer）
4. **gRPC 优先**：004 §4.1 + §4.2 明确 P5 ai 启用 gRPC server（含 StreamChat 流式 RPC），HTTP 保留作 Gateway 直连降级
5. **三支柱可观测**：structlog + prometheus-client + OpenTelemetry（已具备，需补业务指标 + gRPC interceptor）
6. **降级模式**：外部依赖（LLM / 下游 gRPC / Redis）不可用时返回骨架数据 + ActionState `details: {degraded: true}`
7. **Python 规范**：pydantic-settings 配置 / Pydantic 模型校验 / async 优先 / 类型注解强制 / ruff 零错误
8. **响应信封**（ai12 增补）：004 §11.5 强制 ActionState，禁止 `{success, data, degraded}` 偏离结构
9. **端口规范**（ai12 增补）：HTTP 3008 + gRPC 50058（HTTP+10050 规则），提请 coord 在 004 §1.2 + `infra/port-allocation.md` 补登
10. **错误码前缀**（ai12 增补）：`AI_*`（004 §11.4 错误码前缀矩阵已确认 ai 前缀为 `AI_`）

---

## 1. 模块内部分层图

### 1.1 ai06 初稿：分层图

```mermaid
flowchart TB
    subgraph Entry["入口层"]
        HTTP[FastAPI HTTP Router<br/>/ai/* + /healthz + /readyz]
        GRPC[grpc.aio Server<br/>AiService 含 StreamChat]
    end

    subgraph Middleware["中间件层"]
        AUTH[AuthDepends<br/>校验 x-user-id / x-user-roles]
        RATE[RateLimitDepends<br/>Redis 令牌桶限流]
        TRACE[OTel + grpc interceptor]
    end

    subgraph Service["应用服务层"]
        S1[ChatService<br/>聊天编排 + Prompt 模板渲染]
        S2[QuestionGenerationService<br/>出题工作流编排]
        S3[ExpressionOptimizationService<br/>表达优化]
        S4[LessonPreparationWorkflow<br/>备课工作流 4 步编排]
    end

    subgraph Provider["LLM Provider 适配层"]
        P0[LLMProvider 抽象接口<br/>chat / stream_chat]
        P1[OpenAIProvider<br/>httpx 异步]
        P2[AnthropicProvider<br/>httpx 异步]
        P3[BaichuanProvider<br/>httpx 异步]
        P4[LocalOllamaProvider<br/>httpx 异步]
    end

    subgraph Template["Prompt 模板管理"]
        T1[PromptTemplateRegistry<br/>模板注册 + 渲染]
        T2[模板存储<br/>YAML 文件 / DB]
    end

    subgraph Client["下游 gRPC client"]
        C1[ContentClient<br/>查询知识点 / 题库]
        C2[DataAnaClient<br/>查询学情 / 薄弱点]
    end

    subgraph Usage["用量计费"]
        U1[UsageRecorder<br/>token 消耗统计]
        U2[KafkaProducer<br/>发布 edu.insight.ai.usage]
    end

    subgraph External["外部 / 存储"]
        LLM[LLM Provider API<br/>OpenAI/Anthropic/百川/Ollama]
        CONTENT[content:3005 gRPC]
        DATAANA[data-ana:3006 gRPC]
        KAFKA[(Kafka)]
        REDIS[(Redis<br/>限流 + 缓存)]
    end

    HTTP --> AUTH --> RATE --> S1
    HTTP --> S2
    HTTP --> S3
    GRPC --> S1
    GRPC --> S2
    S2 --> S4
    S4 --> C1
    S4 --> C2
    S1 --> T1
    S2 --> T1
    S1 --> P0
    S2 --> P0
    P0 --> P1
    P0 --> P2
    P0 --> P3
    P0 --> P4
    P1 --> LLM
    P2 --> LLM
    P3 --> LLM
    P4 --> LLM
    S1 --> U1
    S2 --> U1
    U1 --> U2
    U2 --> KAFKA
    RATE --> REDIS
    C1 --> CONTENT
    C2 --> DATAANA
```

### 1.2 ai12 增补：完整分层图（含安全 / 评估 / 缓存 / 工作流持久化）

```mermaid
flowchart TB
    subgraph Entry["入口层"]
        HTTP[FastAPI HTTP Router<br/>/ai/v1/* + /healthz + /readyz + /metrics]
        GRPC[grpc.aio Server<br/>AiService 含 StreamChat/StreamGenerateQuestion]
    end

    subgraph Middleware["中间件层"]
        AUTH[AuthDepends<br/>JWT claims → UserContext]
        RATE[RateLimitDepends<br/>Redis 多维度令牌桶<br/>user/IP/school/token]
        TRACE[OTel FastAPIInstrumentor<br/>+ grpc.aio ServerInterceptor<br/>+ grpc.aio ClientInterceptor]
        REQID[RequestContextMiddleware<br/>X-Request-Id 注入与透传]
    end

    subgraph Security["安全层 ai12 增补"]
        PII[PIIRedactor<br/>学生姓名/手机号脱敏]
        SAN[InputSanitizer<br/>Prompt 注入防御]
        MOD[OutputModerator<br/>敏感词过滤 + 安全校验]
    end

    subgraph Service["应用服务层"]
        S1[ChatService<br/>聊天编排 + Prompt 渲染]
        S2[QuestionGenerationService<br/>出题 + 逐字流式生成]
        S3[ExpressionOptimizationService<br/>表达优化]
        S4[LessonPreparationWorkflow<br/>备课工作流 4 步编排]
        S5[PromptTemplateService<br/>模板 CRUD + 版本化]
        S6[UsageService<br/>用量查询 + 配额校验]
    end

    subgraph Provider["LLM Provider 适配层"]
        P0[LLMProvider 抽象接口<br/>chat / stream_chat / embed?]
        P1[OpenAIProvider]
        P2[AnthropicProvider]
        P3[BaichuanProvider]
        P4[LocalOllamaProvider]
        PF[ProviderFailoverChain<br/>多 Provider 故障切换]
    end

    subgraph Template["Prompt 模板管理"]
        T1[PromptTemplateRegistry<br/>模板注册 + Jinja2 渲染]
        T2[模板存储<br/>YAML 文件 P5 / DB P6+]
        T3[模板版本化 + A/B 路由 P6+]
    end

    subgraph Evaluation["评估层 ai12 增补"]
        E1[RuleValidator<br/>题型/答案/解析规则校验]
        E2[LLMJudge<br/>LLM-as-judge 质量评分]
        E3[QualityGate<br/>质量门禁 不达标重新生成或降级]
    end

    subgraph Workflow["工作流持久化 ai12 增补"]
        W1[WorkflowStateStore<br/>Redis 短期 24h TTL P5<br/>Temporal P6+ 评估]
        W2[WorkflowEventLog<br/>工作流步骤事件日志]
    end

    subgraph Cache["缓存层 ai12 增补"]
        CA1[PromptCache<br/>hash 缓存 P5]
        CA2[SemanticCache<br/>embedding 相似度 P6+]
        CA3[TemplateCache<br/>模板缓存 1h TTL]
    end

    subgraph Client["下游 gRPC client"]
        C1[ContentClient<br/>查询知识点/教材/题库]
        C2[DataAnaClient<br/>查询学情/薄弱点/趋势]
        C3[IamClient<br/>查询 DataScope P4+]
    end

    subgraph Usage["用量计费"]
        U1[UsageRecorder<br/>token 消耗统计]
        U2[KafkaProducer<br/>发布 edu.insight.ai.usage]
        U3[QuotaEnforcer<br/>学校/年级/教师配额校验]
    end

    subgraph External["外部 / 存储"]
        LLM[LLM Provider API<br/>OpenAI/Anthropic/百川/Ollama]
        CONTENT[content:3005 gRPC]
        DATAANA[data-ana:3006 gRPC]
        IAM[iam:3002 gRPC]
        KAFKA[(Kafka)]
        REDIS[(Redis<br/>限流/缓存/工作流状态)]
    end

    HTTP --> REQID --> AUTH --> RATE --> Security
    GRPC --> Security
    Security --> S1 & S2 & S3 & S4 & S5 & S6
    S1 & S2 --> T1
    S1 & S2 --> CA1
    S1 & S2 --> P0
    P0 --> PF
    PF --> P1 & P2 & P3 & P4
    P1 & P2 & P3 & P4 --> LLM
    S2 --> E1 --> E2 --> E3
    S2 --> CA1
    S4 --> C1 & C2
    S4 --> W1
    S4 --> W2
    S5 --> T2
    S5 --> CA3
    S6 --> U3
    S1 & S2 & S3 --> U1 --> U2 --> KAFKA
    RATE --> REDIS
    CA1 & CA3 & W1 --> REDIS
    C1 --> CONTENT
    C2 --> DATAANA
    C3 --> IAM
```

**ai12 增补：分层规则**

- **入口层**：HTTP（保留作 Gateway 直连降级 + 前端 SSE 流式）+ gRPC（主入口，BFF 调用，含 `StreamChat` / `StreamGenerateQuestion` 流式 RPC）
- **中间件层**：RequestContextMiddleware（X-Request-Id）→ AuthDepends（JWT claims 解析）→ RateLimitDepends（多维度限流）→ OTel 自动埋点
- **安全层**（ai12 增补）：PIIRedactor → InputSanitizer → OutputModerator，所有进出 LLM 的数据必须经过安全层
- **应用服务层**：6 个 Service，每个对应一类 AI 能力
- **Provider 适配层**：抽象 `LLMProvider` 接口 + 多适配器实现（策略模式）+ `ProviderFailoverChain` 故障切换（resilience 模式）
- **Prompt 模板**：模板注册 + Jinja2 渲染 + 版本化（P5 YAML，P6+ DB + A/B）
- **评估层**（ai12 增补）：规则校验 + LLM-as-judge + 质量门禁，构成生成质量保障三道防线
- **工作流持久化**（ai12 增补）：Redis 短期（P5）+ Temporal（P6+ 评估），保证长运行工作流状态不丢失
- **缓存层**（ai12 增补）：Prompt hash 缓存（P5）+ 语义缓存（P6+ 评估）+ 模板缓存
- **下游 client**：gRPC 调 content / data-ana / iam（DataScope），均带 client interceptor（trace + retry + circuit breaker）
- **用量计费**：token 消耗统计 + Kafka 事件外发 + 配额校验

## 2. 领域模型

ai 是**无状态服务**，不持有持久化聚合根。领域模型为**请求/响应模型 + 工作流编排**：

### 2.1 聚合根（请求型，无持久化）（ai06 初稿）

| 聚合根                       | 含义         | 生命周期                                                     |
| ---------------------------- | ------------ | ------------------------------------------------------------ |
| `ChatConversation`           | 单次聊天请求 | 单次请求                                                     |
| `QuestionGenerationTask`     | 出题任务     | 单次请求（备课工作流中多步）                                 |
| `ExpressionOptimizationTask` | 表达优化任务 | 单次请求                                                     |
| `LessonPreparationWorkflow`  | 备课工作流   | 跨多步（分析学情 → 推荐知识点 → 生成题目 → 教师审核 → 入库） |

### 2.2 ai12 增补：扩展聚合根与值对象

| 聚合根             | 含义             | 生命周期            | 持久化                                   |
| ------------------ | ---------------- | ------------------- | ---------------------------------------- |
| `PromptTemplate`   | Prompt 模板      | 持久化（YAML/DB）   | YAML 文件 P5 / DB P6+                    |
| `UsageRecord`      | 用量记录         | 单次 LLM 调用       | 不持久化，Kafka 事件外发                 |
| `EvaluationResult` | 生成结果质量评估 | 单次生成调用        | 不持久化（P6+ 评估落 ClickHouse 供分析） |
| `WorkflowState`    | 工作流状态       | 跨多步（数小时/天） | Redis 短期 P5 / Temporal P6+             |

### 2.3 值对象

- `ChatMessage`：role + content
- `Usage`：prompt_tokens + completion_tokens + total_tokens + latency_ms
- `GeneratedQuestion`：question + answer + explanation + question_type + difficulty + knowledge_point_ids
- `PromptTemplate`：name + system_prompt + user_template + variables + version
- **ai12 增补**：`UserContext`：user_id + roles + data_scope + school_id + request_id
- **ai12 增补**：`ProviderConfig`：provider_name + model + api_key + base_url + timeout + max_retries
- **ai12 增补**：`EvaluationReport`：rule_score + judge_score + overall_score + reasons + pass
- **ai12 增补**：`WorkflowStep`：step_name + status + started_at + completed_at + result + error
- **ai12 增补**：`QuotaContext`：school_id + grade_id + teacher_id + budget + used + remaining

### 2.4 ai12 增补：备课工作流状态机

备课工作流是 ai 服务最复杂的工作流，明确状态机避免实现混乱：

```mermaid
stateDiagram-v2
    [*] --> Pending: 教师发起备课请求
    Pending --> Analyzing: 工作流启动
    Analyzing --> Analyzed: 查询 data-ana 学情成功
    Analyzing --> AnalyzeFailed: data-ana 不可达 + 降级跳过
    AnalyzeFailed --> Recommending: 降级（仅基于 prompt 生成）
    Analyzed --> Recommending: 查询 content 知识点
    Recommending --> Recommended: 知识点推荐完成
    Recommended --> Generating: 启动 LLM 出题
    Generating --> Generated: LLM 生成完成 + 评估通过
    Generating --> Regenerating: 评估未通过 + 重试 < 3 次
    Regenerating --> Generated: 重试生成通过
    Regenerating --> GenerationFailed: 重试 ≥ 3 次仍失败
    GenerationFailed --> [*]: 返回错误 + 工作流终止
    Generated --> PendingReview: 暂存题目 + 通知教师审核
    PendingReview --> Confirmed: 教师确认入库
    PendingReview --> Modified: 教师修改后确认
    PendingReview --> Rejected: 教师拒绝
    PendingReview --> Expired: 24h 未审核
    Confirmed --> Persisting: 调 content.CreateQuestions
    Modified --> Persisting: 调 content.CreateQuestions
    Persisting --> Persisted: 入库成功
    Persisting --> PersistFailed: 入库失败
    PersistFailed --> Persisting: 重试（最多 3 次）
    PersistFailed --> [*]: 重试失败 + 告警
    Persisted --> [*]: 工作流完成
    Rejected --> [*]: 工作流终止
    Expired --> [*]: 工作流过期
```

**ai12 增补：状态持久化策略**

| 状态                               | P5 持久化                                 | P6+ 持久化                          |
| ---------------------------------- | ----------------------------------------- | ----------------------------------- |
| Pending-Analyzing-Generated        | Redis（key: `ai:workflow:{id}`，TTL 24h） | Temporal workflow history           |
| PendingReview                      | Redis + 通知 BFF（前端轮询/SSE）          | Temporal signal（教师审核事件）     |
| 终态（Persisted/Rejected/Expired） | Redis 标记 + 事件日志                     | Temporal workflow 完成 + ClickHouse |

**ai12 增补：工作流事件日志**（供审计 + RLHF 数据收集）

```json
{
  "workflow_id": "uuid",
  "user_id": "user-xxx",
  "school_id": "school-xxx",
  "step": "Generating",
  "status": "completed",
  "duration_ms": 1200,
  "llm_provider": "openai",
  "llm_model": "gpt-4o-mini",
  "tokens_used": 230,
  "evaluation_score": 0.85,
  "occurred_at": "2026-07-09T12:00:00Z"
}
```

### 2.5 ai12 增补：备课工作流序列图（细化 004 §9.3）

```mermaid
sequenceDiagram
    participant T as 教师
    participant BFF as teacher-bff
    participant AI as ai 服务
    participant IAM as iam
    participant DA as data-ana
    participant Content as content
    participant LLM as LLM Provider
    participant Redis as Redis（工作流状态）
    participant Kafka as Kafka

    T->>BFF: POST /lesson/preparation {class_id, subject_id, topic}
    BFF->>AI: gRPC GenerateLessonPlan
    AI->>IAM: gRPC GetEffectiveDataScope(user_id)
    IAM-->>AI: DataScope
    AI->>Redis: 创建工作流（状态=Pending）
    AI->>AI: 工作流启动（状态=Analyzing）
    par 并行查询
        AI->>DA: gRPC GetClassPerformance(class_id, subject_id)
        DA-->>AI: 班级学情
    and
        AI->>DA: gRPC GetStudentWeakness(student_id, subject_id)
        DA-->>AI: 薄弱知识点
    end
    AI->>Content: gRPC GetPrerequisites(knowledge_point_id)
    Content-->>AI: 前置依赖知识点
    AI->>Redis: 更新工作流（状态=Recommended）
    AI->>AI: 渲染 Prompt 模板
    AI->>LLM: stream_chat（题目逐字生成）
    loop 流式 chunks
        LLM-->>AI: chunk
        AI-->>BFF: stream chunk（透传给前端）
    end
    AI->>AI: 规则校验 + LLM-as-judge
    alt 评估通过
        AI->>Redis: 更新工作流（状态=PendingReview）
        AI-->>BFF: 题目列表 + workflow_id
        BFF-->>T: 题目供审核
    else 评估未通过 + 重试 < 3
        AI->>AI: 调整 Prompt + 重新生成
    else 重试 ≥ 3 仍失败
        AI-->>BFF: 错误响应
    end
    AI->>Kafka: 发布 AIUsageRecorded 事件
    T->>BFF: POST /lesson/preparation/{id}/confirm
    BFF->>AI: gRPC ConfirmLessonPlan(workflow_id)
    AI->>Redis: 更新工作流（状态=Persisting）
    AI->>Content: gRPC CreateQuestions(questions)
    Content-->>AI: 入库成功
    AI->>Redis: 更新工作流（状态=Persisted）
    AI-->>BFF: 入库结果
    BFF-->>T: 入库成功
```

## 3. 数据模型

### 3.1 ai06 初稿：无 DB 设计

ai 服务**无独占数据库**，无 MySQL schema。所有数据通过 Kafka 事件外发（用量计费）或 gRPC 查询下游。

### 3.2 ai12 增补：Redis schema 详细设计

虽然 ai 无 DB，但 Redis 承载多种数据结构，需明确 schema：

| Key 模式                              | 数据类型 | TTL      | 用途                             |
| ------------------------------------- | -------- | -------- | -------------------------------- |
| `ai:ratelimit:user:{user_id}`         | Hash     | 滑动窗口 | 用户级令牌桶（每分钟 10 次）     |
| `ai:ratelimit:ip:{ip}`                | Hash     | 滑动窗口 | IP 级令牌桶（每分钟 30 次）      |
| `ai:ratelimit:school:{school_id}`     | Hash     | 滑动窗口 | 学校级令牌桶（每分钟 100 次）    |
| `ai:quota:school:{school_id}`         | Hash     | 月度重置 | 学校月度 token 预算 + 已用       |
| `ai:quota:teacher:{user_id}`          | Hash     | 月度重置 | 教师月度 token 预算 + 已用       |
| `ai:cache:prompt:{hash}`              | String   | 30 分钟  | LLM 响应缓存（hash 缓存）        |
| `ai:cache:template:{template_name}`   | String   | 1 小时   | Prompt 模板缓存                  |
| `ai:cache:datascope:{user_id}`        | String   | 5 分钟   | DataScope 缓存（避免重复查 iam） |
| `ai:workflow:{workflow_id}`           | Hash     | 24 小时  | 备课工作流状态                   |
| `ai:workflow:user:{user_id}`          | Set      | 24 小时  | 用户的活跃工作流 ID 集合         |
| `ai:dedup:event:{event_id}`           | String   | 7 天     | 事件去重（SETNX）                |
| `ai:circuit:provider:{provider_name}` | String   | 60 秒    | Provider 熔断状态                |

### 3.3 ai12 增补：用量计费 Kafka 事件 payload（建议 events.proto 新增 `AIUsageEvent`）

```protobuf
// 建议 coord 在 events.proto 新增（ai12 提请，待仲裁）
message AIUsageEvent {
  string event_id = 1;            // UUID，幂等去重
  string aggregate_id = 2;        // workflow_id 或 request_id
  string event_type = 3;          // 固定 "AIUsageRecorded"
  int64 occurred_at = 4;          // Unix 毫秒时间戳
  string user_id = 5;
  string school_id = 6;           // 用于多租户配额
  string request_id = 7;          // 链路追踪 ID
  string provider = 8;            // openai/anthropic/baichuan/local
  string model = 9;               // gpt-4o-mini/claude-3-haiku/...
  string operation = 10;          // chat/generate_question/optimize_expression/lesson_preparation
  uint32 prompt_tokens = 11;
  uint32 completion_tokens = 12;
  uint32 total_tokens = 13;
  uint32 latency_ms = 14;
  bool success = 15;
  bool degraded = 16;             // 是否降级（LLM 不可用时）
  map<string, string> metadata = 17;  // 额外上下文（subject/grade/difficulty 等）
}
```

### 3.4 ai12 增补：缓存策略

| 数据                         | 存储                     | TTL      | 失效策略                                     |
| ---------------------------- | ------------------------ | -------- | -------------------------------------------- |
| Prompt 模板                  | Redis（template cache）  | 1 小时   | 文件/DB 变更时主动失效（pub/sub 通知）       |
| LLM 响应（相同 prompt hash） | Redis（prompt cache）    | 30 分钟  | 短 TTL，避免陈旧；用户反馈差时主动失效       |
| DataScope（避免重复查 iam）  | Redis（datascope cache） | 5 分钟   | 短 TTL，权限变更时由 iam 主动失效（pub/sub） |
| 限流计数                     | Redis（ratelimit hash）  | 滑动窗口 | 自动过期                                     |
| 配额计数                     | Redis（quota hash）      | 月度重置 | 月初定时任务重置                             |
| 工作流状态                   | Redis（workflow hash）   | 24 小时  | 工作流终态后保留 1h 再过期（供审计）         |
| **P6+ 语义缓存**             | Redis + 向量索引         | 30 分钟  | embedding 相似度 > 0.95 命中                 |

## 4. API 设计

### 4.1 HTTP 端点（保留作 Gateway 直连降级，ai06 初稿 + ai12 增补）

> **ai12 增补**：所有路径加 `/v1` 版本前缀（P5 起强制），便于未来破坏性变更；响应统一为 ActionState

| method | path                                              | 权限                     | 请求体                        | 响应                                   | 说明                              |
| ------ | ------------------------------------------------- | ------------------------ | ----------------------------- | -------------------------------------- | --------------------------------- |
| GET    | `/healthz`                                        | —                        | —                             | `{status, service}`                    | liveness                          |
| GET    | `/readyz`                                         | —                        | —                             | `{status, llm_configured, ...}`        | readiness                         |
| GET    | `/metrics`                                        | —                        | —                             | Prometheus                             | 指标                              |
| POST   | `/ai/v1/chat`                                     | `AI_CHAT`                | `ChatRequest`                 | `ActionState<ChatData>`                | LLM 聊天                          |
| POST   | `/ai/v1/chat/stream`                              | `AI_CHAT`                | `ChatRequest`                 | SSE stream                             | 流式聊天                          |
| POST   | `/ai/v1/generate/question`                        | `AI_QUESTION_GENERATE`   | `GenerateQuestionRequest`     | `ActionState<GeneratedQuestionData>`   | 生成题目                          |
| POST   | `/ai/v1/generate/question/stream`                 | `AI_QUESTION_GENERATE`   | `GenerateQuestionRequest`     | SSE stream（题目逐字生成）             | **ai12 增补**：题目逐字流式       |
| POST   | `/ai/v1/optimize/expression`                      | `AI_EXPRESSION_OPTIMIZE` | `OptimizeExpressionRequest`   | `ActionState<OptimizedExpressionData>` | 优化表达                          |
| POST   | `/ai/v1/lesson/preparation`                       | `AI_LESSON_PREPARE`      | `LessonPreparationRequest`    | `ActionState<LessonPreparationData>`   | **ai12 增补**：备课工作流启动     |
| GET    | `/ai/v1/lesson/preparation/{workflow_id}`         | `AI_LESSON_PREPARE`      | —                             | `ActionState<WorkflowState>`           | **ai12 增补**：查询工作流状态     |
| POST   | `/ai/v1/lesson/preparation/{workflow_id}/confirm` | `AI_LESSON_PREPARE`      | `ConfirmRequest`              | `ActionState<PersistResult>`           | **ai12 增补**：教师确认入库       |
| GET    | `/ai/v1/prompts`                                  | `AI_PROMPT_READ`         | query: `?page&size`           | `ActionState<Page<TemplateSummary>>`   | **ai12 增补**：模板列表           |
| POST   | `/ai/v1/prompts`                                  | `AI_PROMPT_CREATE`       | `CreatePromptRequest`         | `ActionState<PromptTemplate>`          | **ai12 增补**：创建模板           |
| GET    | `/ai/v1/prompts/{id}`                             | `AI_PROMPT_READ`         | —                             | `ActionState<PromptTemplate>`          | **ai12 增补**：获取模板           |
| PUT    | `/ai/v1/prompts/{id}`                             | `AI_PROMPT_UPDATE`       | `UpdatePromptRequest`         | `ActionState<PromptTemplate>`          | **ai12 增补**：更新模板（版本化） |
| GET    | `/ai/v1/usage/me`                                 | `AI_USAGE_READ`          | query: `?start_date&end_date` | `ActionState<UsageSummary>`            | **ai12 增补**：当前用户用量       |
| GET    | `/ai/v1/usage/school/{school_id}`                 | `AI_USAGE_READ_ALL`      | query: `?start_date&end_date` | `ActionState<UsageSummary>`            | **ai12 增补**：学校用量（管理员） |

### 4.2 gRPC 契约（ai.proto，待实现 server，ai06 初稿 + ai12 增补）

| RPC                      | 请求                                                                                                         | 响应                                                        | 权限                     | 说明                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | ------------------------ | ------------------------------- |
| `Chat`                   | `ChatRequest{messages, model, temperature, user_id?, session_id?, data_scope?}`                              | `ChatResponse{content, model, usage}`                       | `AI_CHAT`                | 非流式聊天                      |
| `StreamChat`             | `ChatRequest`                                                                                                | `stream ChatChunk`                                          | `AI_CHAT`                | 流式聊天（SSE over gRPC）       |
| `GenerateQuestion`       | `GenerateQuestionRequest{prompt, subject, difficulty, grade?, knowledge_point_ids?, question_type?, count?}` | `GeneratedQuestion`                                         | `AI_QUESTION_GENERATE`   | 生成题目                        |
| `StreamGenerateQuestion` | `GenerateQuestionRequest`                                                                                    | `stream GeneratedQuestionChunk`                             | `AI_QUESTION_GENERATE`   | **ai12 增补**：题目逐字流式生成 |
| `OptimizeExpression`     | `OptimizeExpressionRequest{text, context}`                                                                   | `OptimizedExpression`                                       | `AI_EXPRESSION_OPTIMIZE` | 优化表达                        |
| `GenerateLessonPlan`     | `GenerateLessonPlanRequest{class_id, subject_id, topic, user_id, data_scope}`                                | `LessonPlanResponse{workflow_id, status, questions?}`       | `AI_LESSON_PREPARE`      | **ai12 增补**：备课工作流启动   |
| `GetLessonPlanStatus`    | `GetLessonPlanStatusRequest{workflow_id}`                                                                    | `LessonPlanStatus{workflow_id, status, questions?, error?}` | `AI_LESSON_PREPARE`      | **ai12 增补**：查询工作流状态   |
| `ConfirmLessonPlan`      | `ConfirmLessonPlanRequest{workflow_id, modifications?}`                                                      | `ConfirmResult{success, persisted_question_ids?}`           | `AI_LESSON_PREPARE`      | **ai12 增补**：教师确认入库     |

### 4.3 ai12 增补：Pydantic 请求/响应模型（ActionState 对齐）

```python
from typing import Any, Literal
from pydantic import BaseModel, Field


# === ActionState 信封（004 §11.5 强制约束） ===
class ErrorDetail(BaseModel):
    code: str
    message: str
    details: dict[str, Any] | None = None
    trace_id: str | None = None


class ActionState(BaseModel):
    """统一响应信封，所有响应必须使用此结构."""
    success: bool
    data: Any | None = None
    error: ErrorDetail | None = None


# === 聊天 ===
class ChatMessage(BaseModel):
    role: Literal["system", "user", "assistant"]
    content: str = Field(..., min_length=1, max_length=8000)


class ChatRequest(BaseModel):
    messages: list[ChatMessage] = Field(..., min_length=1, max_length=50)
    model: str = "gpt-4o-mini"
    temperature: float = Field(0.7, ge=0.0, le=2.0)
    stream: bool = False


class Usage(BaseModel):
    prompt_tokens: int
    completion_tokens: int
    total_tokens: int
    latency_ms: int


class ChatData(BaseModel):
    content: str
    model: str
    usage: Usage


# === 题目生成 ===
class GenerateQuestionRequest(BaseModel):
    prompt: str = Field(..., min_length=1, max_length=2000)
    subject: str = Field(..., max_length=50)
    difficulty: Literal["easy", "medium", "hard"]
    grade: str | None = Field(None, max_length=20)
    knowledge_point_ids: list[str] = Field(default_factory=list, max_length=20)
    question_type: Literal["single_choice", "multi_choice", "fill_blank", "short_answer", "essay"] = "short_answer"
    count: int = Field(1, ge=1, le=10)


class GeneratedQuestionData(BaseModel):
    question: str
    answer: str
    explanation: str
    question_type: str
    difficulty: str
    knowledge_point_ids: list[str] = []
    evaluation_score: float | None = None  # ai12 增补：质量评分


# === 备课工作流 ===
class LessonPreparationRequest(BaseModel):
    class_id: str
    subject_id: str
    topic: str = Field(..., max_length=500)
    target_difficulty: Literal["easy", "medium", "hard"] = "medium"
    question_count: int = Field(5, ge=1, le=20)


class LessonPreparationData(BaseModel):
    workflow_id: str
    status: Literal["pending", "analyzing", "generating", "pending_review", "persisted", "failed"]
    estimated_completion_seconds: int


class ConfirmRequest(BaseModel):
    modifications: dict[str, str] | None = None  # question_id → 修改后内容
```

### 4.4 ai12 增补：Prompt 模板 YAML 格式

```yaml
# services/ai/src/ai/prompts/generate_question.yaml
name: generate_question
version: "1.0.0"
description: 通用出题 Prompt 模板
variables:
  - name: subject
    description: 学科
    required: true
  - name: difficulty
    description: 难度
    required: true
    allowed: ["easy", "medium", "hard"]
  - name: grade
    description: 年级
    required: false
  - name: knowledge_points
    description: 知识点列表
    required: false
  - name: question_type
    description: 题型
    required: true
  - name: count
    description: 题目数量
    required: true
system_prompt: |
  你是一名经验丰富的{subject}教师，擅长根据学情出题。
  出题要求：
  1. 难度：{difficulty}
  2. 题型：{question_type}
  3. 数量：{count} 道
  {%- if grade %}
  4. 年级：{grade}
  {%- endif %}
  {%- if knowledge_points %}
  5. 必须覆盖以下知识点：{knowledge_points}
  {%- endif %}
  输出格式：JSON 数组，每道题包含 question/answer/explanation 三个字段。
user_template: |
  请根据以上要求出题。
```

## 5. 事件设计

### 5.1 消费的事件

ai 服务**不消费任何事件**（无状态，纯请求-响应）。

**ai12 增补：长期可考虑消费的事件**（P6+ 评估）

- `edu.content.question.published`：题库新增题目事件，可用于"题目查重"——避免 AI 生成与已有题目重复
- `edu.identity.user.role_changed`：用户角色变更，主动失效 DataScope 缓存（替代当前定时 5min TTL 失效）

### 5.2 发布的事件

| 事件              | Topic                                     | 触发时机          | 消费者                                 | Payload                                                                                                                                                           |
| ----------------- | ----------------------------------------- | ----------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AIUsageRecorded` | `edu.insight.ai.usage`（004 §7.2 已确认） | 每次 LLM 调用完成 | data-ana（落 ClickHouse ai_usage_log） | `{event_id, user_id, school_id, request_id, provider, model, operation, prompt_tokens, completion_tokens, total_tokens, latency_ms, success, degraded, metadata}` |

**ai12 增补：长期可发布事件**（P6+ 评估，待 coord 仲裁）

| 事件                 | Topic                      | 触发时机           | 消费者         | 用途                     |
| -------------------- | -------------------------- | ------------------ | -------------- | ------------------------ |
| `AIContentGenerated` | `edu.insight.ai.generated` | 生成内容审计       | data-ana       | 落 ClickHouse 供质量分析 |
| `AIFeedbackRecorded` | `edu.insight.ai.feedback`  | 教师对生成结果反馈 | data-ana       | RLHF 数据集构建          |
| `AIWorkflowEvent`    | `edu.insight.ai.workflow`  | 工作流步骤状态变更 | data-ana + msg | 工作流监控 + 失败告警    |

**发布实现**：

- 每次 LLM 调用后异步发布（不阻塞响应）
- `aiokafka.AIOKafkaProducer` + `acks=all` + `idempotent=true` + `transactional_id`
- 失败重试 3 次（指数退避：1s/2s/4s），仍失败记录日志（不影响主流程，用量计费为派生数据可丢失）
- **幂等性**：`event_id` UUID + Redis SETNX 去重（TTL 7 天），防止 producer 重试导致重复投递

## 6. 横切关注点对齐清单

### 6.1 权限装饰器等价物（ai06 初稿 + ai12 增补）

```python
class Permissions:
    AI_CHAT = "ai:chat"
    AI_QUESTION_GENERATE = "ai:question:generate"
    AI_EXPRESSION_OPTIMIZE = "ai:expression:optimize"
    AI_LESSON_PREPARE = "ai:lesson:prepare"
    AI_PROMPT_READ = "ai:prompt:read"
    AI_PROMPT_CREATE = "ai:prompt:create"
    AI_PROMPT_UPDATE = "ai:prompt:update"
    AI_USAGE_READ = "ai:usage:read"           # ai12 增补：查询自身用量
    AI_USAGE_READ_ALL = "ai:usage:read_all"   # ai12 增补：查询学校用量（管理员）


async def require_permission(permission: str) -> UserContext:
    """FastAPI Depends 权限校验.

    从 x-user-id / x-user-roles 头提取身份，校验角色是否含 permission。
    DataScope 通过 iam.GetEffectiveDataScope 查询，Redis 缓存 5min。
    """
    ...
```

### 6.2 错误码清单（前缀 `AI_*`，ai06 初稿 + ai12 增补）

| 错误码                           | 触发条件                                              | HTTP                | gRPC status         |
| -------------------------------- | ----------------------------------------------------- | ------------------- | ------------------- |
| `AI_UNAUTHORIZED`                | 缺失 x-user-id 或 token 无效                          | 401                 | UNAUTHENTICATED     |
| `AI_FORBIDDEN`                   | 角色无对应权限                                        | 403                 | PERMISSION_DENIED   |
| `AI_RATE_LIMITED`                | 触发限流（user/IP/school 维度）                       | 429                 | RESOURCE_EXHAUSTED  |
| `AI_QUOTA_EXCEEDED`              | 学校/教师月度 token 配额耗尽                          | 429                 | RESOURCE_EXHAUSTED  |
| `AI_LLM_UNAVAILABLE`             | LLM Provider 不可达（降级模式仍返回骨架）             | 200 + degraded:true | OK + degraded flag  |
| `AI_LLM_TIMEOUT`                 | LLM 调用超时（30s）                                   | 504                 | DEADLINE_EXCEEDED   |
| `AI_LLM_ALL_PROVIDERS_FAILED`    | 所有 Provider 故障切换链均失败                        | 503                 | UNAVAILABLE         |
| `AI_INVALID_MODEL`               | model 名不支持                                        | 400                 | INVALID_ARGUMENT    |
| `AI_INVALID_DIFFICULTY`          | difficulty 不在 easy/medium/hard                      | 400                 | INVALID_ARGUMENT    |
| `AI_INVALID_QUESTION_TYPE`       | question_type 不在枚举内                              | 400                 | INVALID_ARGUMENT    |
| `AI_DOWNSTREAM_UNAVAILABLE`      | content / data-ana gRPC 不可达                        | 502                 | UNAVAILABLE         |
| `AI_PROMPT_RENDER_FAILED`        | Prompt 模板渲染失败（变量缺失）                       | 500                 | INTERNAL            |
| `AI_PROMPT_TEMPLATE_NOT_FOUND`   | Prompt 模板不存在                                     | 404                 | NOT_FOUND           |
| `AI_WORKFLOW_NOT_FOUND`          | 备课工作流 ID 不存在                                  | 404                 | NOT_FOUND           |
| `AI_WORKFLOW_EXPIRED`            | 工作流已过期（24h 未审核）                            | 410                 | FAILED_PRECONDITION |
| `AI_WORKFLOW_STATE_INVALID`      | 工作流状态不允许此操作（如已 Persisted 再次 Confirm） | 409                 | FAILED_PRECONDITION |
| `AI_EVALUATION_FAILED`           | 生成质量评估未通过且重试耗尽                          | 503                 | UNAVAILABLE         |
| `AI_PII_DETECTED`                | 输入包含未脱敏 PII（脱敏失败）                        | 400                 | INVALID_ARGUMENT    |
| `AI_PROMPT_INJECTION_DETECTED`   | 输入疑似 Prompt 注入攻击                              | 400                 | INVALID_ARGUMENT    |
| `AI_CONTENT_MODERATION_REJECTED` | 输出内容审核不通过（敏感词）                          | 503                 | UNAVAILABLE         |
| `AI_INTERNAL_ERROR`              | 未捕获异常                                            | 500                 | INTERNAL            |

### 6.3 Logger 初始化

- 位置：`main.py`（已具备）
- 配置：`structlog.make_filtering_bound_logger(level)` + `TimeStamper(fmt="iso")` + `ConsoleRenderer`
- **改进**：生产环境改用 `structlog.processors.JSONRenderer()`（当前 ConsoleRenderer 适合开发）
- **ai12 增补**：日志必须包含 `request_id`（从 RequestContextMiddleware 注入）、`user_id`、`workflow_id`（如适用），便于全链路追踪

### 6.4 Metrics 指标清单（ai06 初稿 + ai12 增补）

| 指标名                             | 类型      | 标签                                      | 描述                               |
| ---------------------------------- | --------- | ----------------------------------------- | ---------------------------------- |
| `ai_http_requests_total`           | Counter   | method, path, status                      | HTTP 请求总数                      |
| `ai_http_request_duration_seconds` | Histogram | method, path                              | HTTP 请求延迟                      |
| `ai_grpc_requests_total`           | Counter   | method, status                            | gRPC 请求总数（ai12 增补）         |
| `ai_grpc_request_duration_seconds` | Histogram | method                                    | gRPC 请求延迟（ai12 增补）         |
| `ai_llm_calls_total`               | Counter   | provider, model, operation, status        | LLM 调用总数                       |
| `ai_llm_call_duration_seconds`     | Histogram | provider, model, operation                | LLM 调用延迟                       |
| `ai_llm_tokens_total`              | Counter   | provider, model, type (prompt/completion) | token 消耗总数                     |
| `ai_llm_stream_chunks_total`       | Counter   | provider, model                           | 流式 chunk 总数                    |
| `ai_llm_first_token_seconds`       | Histogram | provider, model                           | 流式首字延迟（ai12 增补，SLO）     |
| `ai_provider_failover_total`       | Counter   | from_provider, to_provider, reason        | Provider 故障切换次数（ai12 增补） |
| `ai_grpc_downstream_calls_total`   | Counter   | downstream, method, status                | 下游 gRPC 调用总数                 |
| `ai_rate_limit_hits_total`         | Counter   | dimension (user/ip/school)                | 限流命中次数                       |
| `ai_quota_used_ratio`              | Gauge     | school_id, dimension (school/teacher)     | 配额使用率（ai12 增补）            |
| `ai_usage_events_published_total`  | Counter   | status                                    | 用量事件发布数                     |
| `ai_prompt_template_renders_total` | Counter   | template_name, status                     | 模板渲染次数                       |
| `ai_prompt_cache_hits_total`       | Counter   | —                                         | Prompt 缓存命中（ai12 增补）       |
| `ai_workflow_active_count`         | Gauge     | status                                    | 活跃工作流数（ai12 增补）          |
| `ai_workflow_duration_seconds`     | Histogram | status                                    | 工作流总耗时（ai12 增补）          |
| `ai_evaluation_pass_rate`          | Gauge     | operation                                 | 评估通过率（ai12 增补）            |
| `ai_circuit_breaker_state`         | Gauge     | provider, state (closed/open/half_open)   | 熔断器状态（ai12 增补）            |

### 6.5 Tracer 初始化

- 位置：`main.py` `init_tracer()`（已具备，dev_mode 跳过）
- **改进**：
  - gRPC server 注册 `grpc.aio.ServerInterceptor` 透传 W3C trace context（从 metadata 提取 `traceparent`）
  - 下游 gRPC client 注册 `grpc.aio.ClientInterceptor` 注入 `traceparent` 到 metadata
  - LLM 调用创建子 span（`ai_llm_call`），记录 provider/model/tokens/latency
  - 备课工作流每步创建子 span（`ai_workflow_step`），记录 step_name/status/duration

### 6.6 /healthz 检查逻辑

- liveness：仅进程存活（已具备）

### 6.7 /readyz 检查逻辑（ai06 初稿 + ai12 增补）

```python
async def readyz() -> dict:
    return {
        "status": "ok" if all_ready else "degraded",
        "ready": all_ready,
        "service": "ai",
        "llm_configured": settings.llm_available,
        "degraded": not all_ready,
        "providers": {
            "openai": bool(settings.openai_api_key),
            "anthropic": bool(settings.anthropic_api_key),
            "baichuan": bool(settings.baichuan_api_key),
            "local_ollama": bool(settings.ollama_base_url),
        },
        "downstream_grpc": {
            "content": "ok" | "unreachable" | "not_configured",
            "data_ana": "ok" | "unreachable" | "not_configured",
            "iam": "ok" | "unreachable" | "not_configured",  # ai12 增补
        },
        "redis": "ok" | "unreachable",  # 限流 + 缓存 + 工作流状态依赖
        "kafka": "ok" | "unreachable",  # ai12 增补：用量事件发布依赖
        "timestamp": datetime.now(UTC).isoformat(),
    }
```

### 6.8 优雅关闭顺序（ai06 初稿 + ai12 增补）

1. HTTP server stop accepting new requests（uvicorn graceful shutdown）
2. **ai12 增补**：拒绝新工作流启动（返回 `AI_SERVICE_SHUTTING_DOWN` 503）
3. gRPC server graceful stop（**关键**：等待在途 `StreamChat` / `StreamGenerateQuestion` 流式 RPC 完成，60s 超时，避免截断用户响应）
4. LLM 流式请求 drain（等待 httpx stream 完成）
5. **ai12 增补**：在途工作流状态保存（Redis 已持久化，无需额外操作；Temporal 模式下需 complete workflow）
6. Kafka producer flush + close（确保用量事件已投递）
7. 下游 gRPC channels close（content / data-ana / iam）
8. Redis connection close

**信号处理**：注册 `signal.SIGTERM` handler，触发上述顺序，总超时 90s（gRPC 60s + 其他 30s）。

## 7. 与其他模块的交互点（契约清单）

| 方向   | 对方服务     | 协议  | 接口/事件                                                    | 用途                            |
| ------ | ------------ | ----- | ------------------------------------------------------------ | ------------------------------- |
| 被调用 | api-gateway  | HTTP  | `/ai/*`                                                      | Gateway 代理                    |
| 被调用 | teacher-bff  | gRPC  | `AiService.*`                                                | BFF 聚合 AI 能力                |
| 调用   | content      | gRPC  | `KnowledgeGraphService.GetPrerequisites / GetLearningPath`   | 出题上下文查询                  |
| 调用   | content      | gRPC  | `TextbookService.ListTextbooks`                              | 出题教材关联（ai12 增补）       |
| 调用   | content      | gRPC  | `QuestionService.CreateQuestions`（**待 coord 补全 proto**） | 备课工作流入库（ai12 增补）     |
| 调用   | data-ana     | gRPC  | `AnalyticsService.GetStudentWeakness / GetLearningTrend`     | 个性化出题学情查询              |
| 调用   | data-ana     | gRPC  | `AnalyticsService.GetClassPerformance`                       | 备课工作流班级学情（ai12 增补） |
| 调用   | iam          | gRPC  | `IamService.GetEffectiveDataScope`（**待 coord P4 补全**）   | DataScope 解析（ai12 增补）     |
| 调用   | LLM Provider | HTTP  | OpenAI 兼容 REST `/chat/completions`                         | LLM 推理                        |
| 发布   | —            | Kafka | `edu.insight.ai.usage`（004 §7.2 已确认）                    | 用量计费外发                    |
| 发布   | —            | Kafka | `edu.insight.ai.generated`（**P6+ 待 coord 仲裁**）          | 生成内容审计（ai12 增补）       |
| 发布   | —            | Kafka | `edu.insight.ai.feedback`（**P6+ 待 coord 仲裁**）           | RLHF 反馈数据（ai12 增补）      |

## 8. 风险与假设

### 8.1 假设

- **假设 1**：content 服务实现了 `KnowledgeGraphService` gRPC server。当前 content.proto 已定义但未实现 gRPC server（ai05 阶段 2 设计中）。ai 调用前需确认 content gRPC 可用
- **假设 2**：data-ana 实现了 `AnalyticsService` gRPC server（ai11 设计文档已设计）。ai 调用前需确认 data-ana gRPC 可用
- **假设 3**：coord 同意新增 `edu.insight.ai.usage` topic + `AIUsageEvent` proto message。**004 §7.2 已确认 topic**，events.proto message 待 coord 补全
- **假设 4**：Redis 可用（限流 + 缓存 + 工作流状态依赖）。若 Redis 不可用：
  - 限流降级为"无限制"（风险：LLM 成本失控），或降级为内存令牌桶（单实例有效，多实例不一致）
  - 缓存失效，所有 LLM 调用直达 Provider（成本增加）
  - 工作流状态丢失，在途工作流失效（影响教师审核流程）
- **假设 5**（ai12 增补）：iam 提供 `GetEffectiveDataScope` gRPC API。coord 已仲裁 P4 补全（§15.3 #5）
- **假设 6**（ai12 增补）：LLM Provider API 稳定性符合 SLA（OpenAI 99.5%+）。多 Provider 故障切换可覆盖单 Provider 故障
- **假设 7**（ai12 增补）：教师审核备课结果在 24h 内完成。超过 24h 工作流过期，需重新发起

### 8.2 技术风险

| 风险                   | 影响                   | 缓解措施                                                                                             |
| ---------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------- |
| LLM 调用延迟高（>30s） | 用户体验差             | 超时 30s + 降级骨架响应 + 流式优先（用户感知首字延迟）                                               |
| LLM 成本失控           | 财务风险               | Redis 令牌桶限流（user/IP/school 三维度）+ 月度配额 + 用量计费监控 + 告警阈值                        |
| LLM Provider 单点故障  | 服务不可用             | 多 Provider 适配器 + ProviderFailoverChain 自动 failover（OpenAI 失败切 Anthropic，再切本地 Ollama） |
| 流式 RPC 中断          | 用户响应截断           | gRPC server graceful shutdown 60s drain + 客户端重连机制 + 工作流状态持久化支持重试                  |
| Prompt 注入攻击        | LLM 输出恶意内容       | InputSanitizer 过滤 + system prompt 加安全约束 + OutputModerator 过滤                                |
| 下游 gRPC 不可达       | 备课工作流失败         | 降级：跳过学情查询，仅基于 prompt 生成题目 + `degraded: true`                                        |
| PII 数据泄露给 LLM     | 合规风险               | PIIRedactor 在写入 prompt 前脱敏（学生姓名→"学生A"，手机号→"***"）                                   |
| 生成质量低             | 教师审核拒绝率高       | RuleValidator + LLMJudge 双重校验 + 不达标重试（最多 3 次）                                          |
| 工作流状态丢失         | 教师审核流程中断       | Redis 持久化 + 24h TTL + 事件日志（P6+ Temporal）                                                    |
| Redis 单点故障         | 限流/缓存/工作流全失效 | Redis 哨兵/集群（P6 硬化）+ 降级策略（限流无限制/缓存失效/工作流拒绝启动）                           |

### 8.3 未决设计决策（需 coord 仲裁）

1. **备课工作流是否引入 Temporal**：004 §2.3 列出 Temporal 用于 AI 编排，但简单 4 步工作流可用 FastAPI BackgroundTasks + Redis 状态。建议：P5 用 BackgroundTasks + Redis（24h TTL），P6 评估迁移 Temporal（支持长运行 + 复杂状态机）
2. **`edu.insight.ai.usage` topic 已确认，`AIUsageEvent` proto message 待补全**：需 coord 在 shared-proto events.proto 新增（ai12 已给出建议 schema §3.3）
3. **LLM Provider 配置化路由**：是否在 shared-py 建立通用 `LLMProvider` 抽象（供未来其他 Python 服务复用）。建议 P5 阶段在 ai 服务内部实现，P6 评估是否提取到 shared-py
4. **Prompt 模板存储位置**：YAML 文件（简单，无 DB）vs DB（动态更新）。建议 P5 用 YAML 文件（`services/ai/src/ai/prompts/*.yaml`），P6 评估迁移 DB
5. **ai12 新增 10 项提请**（详见 01-understanding.md §"ai12 新增提请项"）：ai gRPC 端口 50058、ai.proto 待补全、events.proto 待补 AIUsageEvent、iam GetEffectiveDataScope、响应信封整改、长运行工作流持久化、多模态规划、评估框架归属、RLHF 数据收集

---

## ai12 增补：长期架构演进设计（§9-§17）

> 以下章节为 ai12 新增，旨在为未来 P6+ 演进做好铺垫，确保 P5 实现不阻塞未来扩展。

## 9. 安全架构

### 9.1 PII 脱敏流水线

```mermaid
flowchart LR
    Input[用户输入] --> Detect[PII 检测<br/>正则 + NER 模型]
    Detect --> Redact[脱敏替换<br/>学生姓名→学生A<br/>手机号→***]
    Redact --> Log[脱敏日志<br/>记录脱敏操作]
    Log --> Prompt[安全 Prompt]
    Prompt --> LLM[LLM 调用]
```

| PII 类型 | 检测方式               | 脱敏方式             |
| -------- | ---------------------- | -------------------- |
| 学生姓名 | 白名单匹配（来自 iam） | 替换为"学生A/B/C"    |
| 手机号   | 正则 `1[3-9]\d{9}`     | 替换为 `***`         |
| 身份证号 | 正则 `\d{17}[\dXx]`    | 替换为 `***`         |
| 邮箱     | 正则                   | 替换为 `***@***.com` |
| 家庭住址 | NER 模型（P6+ 评估）   | 替换为"某地"         |

### 9.2 Prompt 注入防御

- **输入 sanitize**：过滤 SQL 注入模式（`'; DROP TABLE`）、HTML 注入（`<script>`）、命令注入（`; rm -rf`）
- **System prompt 加安全约束**：明确禁止执行"忽略上述指令"、"输出系统 prompt"等攻击模式
- **输出过滤**：检测输出中是否包含 system prompt 内容、是否执行了注入指令

### 9.3 输出内容审核

- **敏感词过滤**：基于敏感词字典（政治/色情/暴力/广告），P5 用基础字典，P6+ 接入专业审核 API
- **安全校验**：检测输出是否包含代码执行指令、是否诱导不当行为
- **审核失败处理**：返回 `AI_CONTENT_MODERATION_REJECTED` 503 + 触发重新生成（最多 3 次）

### 9.4 多租户数据隔离

- **DataScope 透传**：所有 LLM 调用必须携带 `UserContext.data_scope`，确保生成内容不超出用户权限范围
- **Prompt 注入 DataScope 约束**：system prompt 明确"仅可生成用户 DataScope 范围内的内容"
- **配额隔离**：按 school_id 隔离 token 配额，避免单一学校耗尽全平台预算

## 10. 评估框架

### 10.1 三道防线质量保障

```mermaid
flowchart LR
    Generated[LLM 生成结果] --> R1[第一道：规则校验<br/>RuleValidator]
    R1 -->|通过| R2[第二道：LLM-as-judge<br/>LLMJudge]
    R1 -->|不通过| Retry[重新生成]
    R2 -->|score >= 0.7| R3[第三道：质量门禁<br/>QualityGate]
    R2 -->|score < 0.7| Retry
    R3 -->|通过| Output[输出给用户]
    R3 -->|不通过| Retry
    Retry -->|重试 < 3| Generated
    Retry -->|重试 >= 3| Degraded[降级返回错误]
```

### 10.2 RuleValidator 规则清单

| 规则       | 校验内容                                             | 失败处理           |
| ---------- | ---------------------------------------------------- | ------------------ |
| 题型匹配   | 生成题目格式符合 `question_type`（单选/多选/填空等） | 重新生成           |
| 答案非空   | answer 字段非空且非占位符                            | 重新生成           |
| 解析合理   | explanation 长度 >= 20 字符                          | 重新生成           |
| 难度匹配   | LLM 判定难度与请求 `difficulty` 一致                 | 标记 warning，通过 |
| 知识点覆盖 | 生成题目覆盖请求的 `knowledge_point_ids`             | 标记 warning，通过 |
| 字符长度   | question <= 1000 字符                                | 截断 + warning     |
| 格式合规   | 输出可解析为 JSON（如要求 JSON 格式）                | 重新生成           |

### 10.3 LLMJudge 评估维度

| 维度         | 评分标准                   | 权重 |
| ------------ | -------------------------- | ---- |
| 准确性       | 题目本身正确性、答案正确性 | 0.4  |
| 清晰度       | 题目表述清晰、无歧义       | 0.2  |
| 难度匹配     | 实际难度与请求难度匹配     | 0.2  |
| 知识点相关性 | 题目与知识点相关           | 0.1  |
| 解析质量     | 解析能帮助学生理解         | 0.1  |

**评分阈值**：

- `>= 0.85`：优秀，直接通过
- `0.7-0.85`：合格，通过
- `< 0.7`：不合格，重新生成

### 10.4 评估数据收集（RLHF 基础）

每次生成结果记录：

- 生成内容（题目/答案/解析）
- 评估报告（rule_score / judge_score / overall_score）
- 教师反馈（采纳/拒绝/修改，由 BFF 调用 `ConfirmLessonPlan` 时携带 `modifications`）

P6+ 评估发布 `AIFeedbackRecorded` 事件，data-ana 落 ClickHouse 供未来 fine-tune。

## 11. RAG 检索架构演进

### 11.1 P5：复用 content 服务（无独立向量库）

```mermaid
flowchart LR
    Prompt[出题 Prompt] --> Content[content.KnowledgeGraphService<br/>GetPrerequisites]
    Content --> Context[知识点上下文]
    Context --> LLM[LLM 生成]
```

### 11.2 P6+：引入向量库语义检索（评估）

```mermaid
flowchart LR
    Prompt[出题 Prompt] --> Embed[Embedding Provider<br/>text-embedding-3-small]
    Embed --> Vector[(向量库<br/>pgvector/Chroma)]
    Vector --> Retrieve[Top-K 相似题目]
    Retrieve --> Rerank[Reranker<br/>cohere-rerank]
    Rerank --> Context[精排后上下文]
    Context --> LLM[LLM 生成]
```

**演进路径**：

- P5：仅基于 content 知识点查询
- P6+：评估引入向量库（pgvector 复用 MySQL / Chroma 独立部署）+ Embedding Provider 抽象
- P7+：评估 Reranker 提升检索精度

**proto 预留**（ai12 增补，建议 coord 在 ai.proto v2 预留）：

```protobuf
message EmbeddingRequest {
  string text = 1;
  string model = 2;  // text-embedding-3-small / bge-large-zh
}

message EmbeddingResponse {
  repeated float embedding = 1;
  int32 tokens = 2;
}
```

## 12. 多模态支持规划

### 12.1 P5：仅文本

- 出题：仅支持文本题目
- 优化：仅支持文本表达优化
- 聊天：仅支持文本对话

### 12.2 P6+：多模态评估

| 场景       | 模态      | 技术方案                            |
| ---------- | --------- | ----------------------------------- |
| 数学几何题 | 文本+图片 | GPT-4V / Claude 3 Vision 多模态 LLM |
| 英语听力题 | 文本+音频 | TTS 生成音频 + 文本题目             |
| 物理实验题 | 文本+图片 | 多模态 LLM + 实验图理解             |
| 化学反应题 | 文本+图片 | 多模态 LLM + 化学式图片识别         |

### 12.3 proto 预留（ai12 增补）

```protobuf
message MultimodalContent {
  string text = 1;
  optional string image_url = 2;       // 图片 URL
  optional string audio_url = 3;       // 音频 URL
  optional string image_base64 = 4;    // 图片 base64（小图）
}

message ChatRequest {
  repeated ChatMessage messages = 1;
  // ... 其他字段
  optional MultimodalContent multimodal = 10;  // v2 预留
}
```

## 13. LLM Provider 适配器详细设计

### 13.1 LLMProvider 抽象接口

```python
from abc import ABC, abstractmethod
from collections.abc import AsyncGenerator


class LLMProvider(ABC):
    """LLM Provider 抽象接口，所有适配器必须实现."""

    @property
    @abstractmethod
    def name(self) -> str:
        """Provider 名称（openai/anthropic/baichuan/local_ollama）."""

    @abstractmethod
    async def chat(self, messages: list[dict], model: str, temperature: float) -> dict:
        """非流式调用，返回 OpenAI 兼容响应 dict."""

    @abstractmethod
    async def stream_chat(self, messages: list[dict], model: str, temperature: float) -> AsyncGenerator[str, None]:
        """流式调用，yield SSE 格式 chunk."""

    @abstractmethod
    async def embed(self, text: str, model: str) -> list[float]:
        """Embedding 调用（P6+ 评估，P5 可 NotImplementedError）."""
```

### 13.2 适配器实现清单

| Provider              | API 协议         | 认证方式         | 备注                       |
| --------------------- | ---------------- | ---------------- | -------------------------- |
| `OpenAIProvider`      | OpenAI REST      | Bearer token     | 默认 Provider，gpt-4o-mini |
| `AnthropicProvider`   | Anthropic REST   | x-api-key header | 内部转换为 OpenAI 兼容格式 |
| `BaichuanProvider`    | OpenAI 兼容 REST | Bearer token     | 百川大模型，国内访问稳定   |
| `LocalOllamaProvider` | Ollama REST      | 无认证           | 本地部署，私有化场景       |

### 13.3 ProviderFailoverChain 故障切换

```python
class ProviderFailoverChain:
    """多 Provider 故障切换链.

    按优先级顺序尝试 Provider，失败自动切换到下一个。
    熔断器：单 Provider 连续 3 次失败触发熔断（60s 内不再尝试）。
    """

    def __init__(self, providers: list[LLMProvider], circuit_breaker: CircuitBreaker):
        self._providers = providers
        self._circuit_breaker = circuit_breaker

    async def chat(self, messages, model, temperature) -> dict:
        for provider in self._providers:
            if not self._circuit_breaker.is_closed(provider.name):
                continue  # 熔断中，跳过
            try:
                result = await provider.chat(messages, model, temperature)
                self._circuit_breaker.record_success(provider.name)
                return result
            except Exception as exc:
                self._circuit_breaker.record_failure(provider.name)
                logger.warning("provider_failover", from_=provider.name, error=str(exc))
                continue
        raise AllProvidersFailedError()
```

### 13.4 配置化路由

```python
# config.py
class Settings(BaseSettings):
    # Provider 优先级（按顺序 failover）
    llm_provider_priority: list[str] = ["openai", "anthropic", "baichuan", "local_ollama"]
    # 各 Provider 配置
    openai_api_key: str = ""
    openai_base_url: str = "https://api.openai.com/v1"
    anthropic_api_key: str = ""
    anthropic_base_url: str = "https://api.anthropic.com"
    baichuan_api_key: str = ""
    baichuan_base_url: str = "https://api.baichuan-ai.com/v1"
    ollama_base_url: str = ""  # 本地 Ollama，如 http://localhost:11434
    # 默认模型路由（model 名 → Provider）
    llm_model_routing: dict[str, str] = {
        "gpt-4o-mini": "openai",
        "gpt-4o": "openai",
        "claude-3-haiku": "anthropic",
        "baichuan2-13b": "baichuan",
        "qwen2.5-7b": "local_ollama",
    }
```

## 14. 性能与容量规划

### 14.1 SLO 指标

| 指标            | SLO          | 测量方式                       |
| --------------- | ------------ | ------------------------------ |
| 流式首字延迟    | < 2s（P95）  | `ai_llm_first_token_seconds`   |
| 非流式响应延迟  | < 10s（P95） | `ai_llm_call_duration_seconds` |
| 流式 chunk 间隔 | < 100ms      | 客户端测量                     |
| 工作流总耗时    | < 60s（P95） | `ai_workflow_duration_seconds` |
| 评估通过率      | > 80%        | `ai_evaluation_pass_rate`      |
| 服务可用性      | 99.5%        | 30 天滚动窗口                  |

### 14.2 容量规划

| 资源            | 单实例容量          | P5 预估需求         | 扩展策略           |
| --------------- | ------------------- | ------------------- | ------------------ |
| 并发 LLM 调用   | 50（受 httpx 限制） | 200（500 教师）     | 水平扩展（4 实例） |
| 并发流式 RPC    | 30                  | 100                 | 水平扩展（4 实例） |
| Redis 内存      | 100MB               | 500MB（工作流状态） | Redis 集群（P6+）  |
| Kafka 吞吐      | 1000 events/s       | 100 events/s        | 单分区足够         |
| 月度 token 消耗 | —                   | 10M tokens          | 按学校配额控制     |

### 14.3 流式背压处理

- **gRPC 流式 RPC**：默认支持背压（client 慢消费时 server 自动暂停 yield）
- **SSE**：FastAPI StreamingResponse 不支持背压，需手动检测 client 断开（`await request.is_disconnected()`）
- **超时**：流式 RPC 60s 无 chunk 自动断开；非流式 30s 超时

## 15. 测试策略

### 15.1 测试金字塔

| 层级     | 覆盖率目标 | 工具                            | 重点                                                        |
| -------- | ---------- | ------------------------------- | ----------------------------------------------------------- |
| 单元测试 | ≥ 80%      | pytest + pytest-asyncio         | LLMProvider 适配器 / RuleValidator / PIIRedactor / 模板渲染 |
| 集成测试 | 关键路径   | pytest + httpx + testcontainers | HTTP/gRPC 端点 / Redis / Kafka                              |
| 契约测试 | proto 一致 | pact-python                     | ai.proto 与 BFF 契约一致性                                  |
| 评估测试 | 生成质量   | 自研 + LLM-as-judge             | 题目质量评分（人工 + 自动）                                 |

### 15.2 LLM Mock 策略

- 测试环境不调真实 LLM（成本高 + 不稳定）
- `MockLLMProvider` 实现固定响应（按 prompt 模式匹配返回预设响应）
- 评估测试用真实 LLM（独立 CI job，低频运行）

## 16. 实施里程碑（ai12 增补）

### 16.1 M14（第 1 月）：基础架构

**目标**：建立 LLMProvider 抽象 + gRPC server 基础

| 交付物                                                          | 验收标准                 |
| --------------------------------------------------------------- | ------------------------ |
| `LLMProvider` 抽象接口 + OpenAIProvider 实现                    | 单元测试覆盖 ≥ 80%       |
| AnthropicProvider + BaichuanProvider + LocalOllamaProvider 实现 | 4 Provider 切换可用      |
| `ProviderFailoverChain` + CircuitBreaker                        | 故障切换测试通过         |
| gRPC server（Chat + StreamChat）                                | BFF 可调通 gRPC 流式 RPC |
| Redis 多维度限流（user/IP/school）                              | 限流命中准确             |
| 响应信封整改为 ActionState                                      | 004 §11.5 合规           |
| Dockerfile 多阶段构建                                           | 镜像 < 200MB             |

### 16.2 M15（第 2 月）：出题核心

**目标**：Prompt 模板管理 + 出题工作流 + 用量计费

| 交付物                                         | 验收标准              |
| ---------------------------------------------- | --------------------- |
| PromptTemplateService + Jinja2 渲染            | 5+ 模板可渲染         |
| Prompt 模板 CRUD API                           | HTTP/gRPC 均可用      |
| GenerateQuestion + StreamGenerateQuestion      | 题目逐字流式生成      |
| RuleValidator + LLMJudge + QualityGate         | 评估通过率 > 80%      |
| UsageRecorder + KafkaProducer                  | 用量事件落 ClickHouse |
| QuotaEnforcer（学校/教师配额）                 | 配额超限返回 429      |
| PIIRedactor + InputSanitizer + OutputModerator | 安全测试通过          |

### 16.3 M16（第 3 月）：备课工作流

**目标**：备课工作流 4 步编排端到端

| 交付物                                  | 验收标准             |
| --------------------------------------- | -------------------- |
| LessonPreparationWorkflow 4 步编排      | 端到端跑通           |
| WorkflowStateStore（Redis 持久化）      | 24h 内可恢复         |
| 教师审核流程（BFF 编排）                | 教师可审核/修改/拒绝 |
| content.CreateQuestions 入库            | 题目入库成功         |
| gRPC client（content / data-ana / iam） | 下游调用稳定         |
| 集成测试 + 契约测试                     | 关键路径覆盖         |
| 文档完善（README + known-issues）       | 文档同步更新         |

## 17. 与架构标准的对齐清单

### 17.1 通用架构原则对齐

| 原则                   | 对齐情况 | 说明                                                 |
| ---------------------- | -------- | ---------------------------------------------------- |
| DDD 限界上下文         | ✅       | D6.b 生成子域，边界清晰                              |
| CQRS                   | N/A      | ai 无 DB，无读写分离                                 |
| 事件驱动               | ✅       | AIUsageRecorded 事件外发，豁免 Outbox（004 §12.2）   |
| 12-factor              | ✅       | 配置通过环境变量 + pydantic-settings                 |
| SOLID                  | ✅       | LLMProvider 抽象（OCP/ISP）+ Service 单一职责（SRP） |
| Hexagonal architecture | ✅       | LLMProvider / ContentClient / DataAnaClient 均为端口 |

### 17.2 Resilience 模式对齐

| 模式                 | 实现                                   |
| -------------------- | -------------------------------------- |
| Circuit Breaker      | ProviderFailoverChain + CircuitBreaker |
| Retry with backoff   | LLM 调用 3 次重试（1s/2s/4s 指数退避） |
| Timeout              | LLM 30s / gRPC 60s / Redis 1s          |
| Bulkhead             | 单实例 50 并发 LLM 调用上限            |
| Failover             | 多 Provider 故障切换链                 |
| Graceful degradation | LLM 不可用返回骨架 + degraded:true     |

### 17.3 可观测性对齐

| 支柱    | 实现                                  | 与 004 §10 对齐 |
| ------- | ------------------------------------- | --------------- |
| Logs    | structlog + JSONRenderer + request_id | ✅              |
| Metrics | prometheus-client + 20+ 业务指标      | ✅              |
| Traces  | OpenTelemetry + gRPC interceptor      | ✅              |
| Health  | /healthz + /readyz（多维度检查）      | ✅              |

---

## 待 coord 交叉审查项（ai 相关）

| #        | 议题                                                                                 | 涉及文档                      |
| -------- | ------------------------------------------------------------------------------------ | ----------------------------- |
| 2        | 新增 `edu.insight.ai.usage` topic + `AIUsageEvent` proto message                     | 004 §7.2 + events.proto       |
| 4        | ai 实现 gRPC server 决策（含 StreamChat 流式 RPC）                                   | 004 §4.1                      |
| 6        | ai 备课工作流是否引入 Temporal                                                       | 004 §2.3                      |
| 7        | 端口冲突检查：ai 3008 HTTP + 50058 gRPC（ai12 增补：gRPC 端口待补登）                | full-stack-runbook + 004 §1.2 |
| 8        | 错误码前缀检查：`AI_*`（与其他服务不重叠）                                           | —                             |
| 9        | 黄金模板对齐：Python 服务无 NestJS 装饰器，权限校验用 FastAPI Depends 等价物是否认可 | —                             |
| ai12-A1  | ai gRPC 端口 50058 补登 004 §1.2 + infra/port-allocation.md                          | 004 §1.2                      |
| ai12-A2  | ai.proto 待补全（GenerateLessonPlan / StreamGenerateQuestion / 字段扩展）            | ai.proto                      |
| ai12-A3  | events.proto 待补 `AIUsageEvent` message（建议 schema 见 §3.3）                      | events.proto                  |
| ai12-A4  | iam GetEffectiveDataScope proto P4 补全（004 §15.3 #5 已仲裁）                       | iam.proto                     |
| ai12-A5  | 响应信封偏离 ActionState 强制整改（004 §11.5 已约束）                                | known-issues §2.9             |
| ai12-A6  | Prompt 模板存储位置（P5 YAML / P6+ DB 评估）                                         | —                             |
| ai12-A7  | 长运行工作流持久化（P5 Redis 24h / P6+ Temporal 评估）                               | 004 §2.3                      |
| ai12-A8  | 多模态支持规划（P5 文本 / P6+ 多模态评估），proto v2 预留字段                        | ai.proto v2                   |
| ai12-A9  | 评估框架归属（P5/P6 ai 内部 / P7+ 独立评估）                                         | —                             |
| ai12-A10 | RLHF 数据收集 `AIFeedbackRecorded` topic（P6+ 评估）                                 | 004 §7.2                      |

下一步：等待 coord 交叉审查通过后，进入阶段 3（按图实施）。

---

**AI Agent**: ai12 (ai) ← ai06（初稿）
**Branch**: 单仓库并行模式（直接提交 main）
**Coordinator**: coord-ai