# AI 引擎 v2 架构设计规格

> **日期:** 2026-05-05 | **状态:** Draft | **范围:** erp-ai 模块演进
> **实施周期:** Q2（2-3 个月）| **方案:** 混合 — 结构化核心 + RAG 接口预留

## 1. 背景与动机

### 1.1 当前状态

erp-ai 模块已完成 Phase 1 MVP（6 实体、SSE 流式分析、Claude 单 Provider），具备：

- `AiProvider` trait + `ClaudeProvider` 实现（reqwest 直接调用 Anthropic API）
- SSE 三层流式架构（Provider → AnalysisService → Handler）
- DB 级 SHA-256 缓存复用
- `LocalRulesEngine`（10 条规则，已实现但未集成到路由层）
- 自动定时分析（每 24h 扫描高风险患者）
- 双通道输出解析 + AI 建议生命周期管理
- 透析 KDIGO 风险评分器（14 条专科规则）

### 1.2 核心问题

1. **单点依赖** — 所有分析绑定 Claude，无降级能力，Provider 故障 = 服务不可用
2. **知识注入缺失** — Prompt 无结构化医学知识支撑，分析质量依赖模型通用能力
3. **无配额管控** — 无成本感知，无租户预算，商业化前提缺失
4. **管线断裂** — 事件驱动触发仅记录日志，无法自动响应体征异常等关键事件
5. **缓存效率低** — 仅 DB 级缓存，高频重复分析仍需查询数据库

### 1.3 设计目标

- **租户级 Provider 选择** — 客户选择本地（Ollama）或云端（Claude/OpenAI）LLM
- **按分析类型可覆盖** — 不同分析类型可使用不同 Provider/模型
- **故障自动降级** — Provider 不可用时回退规则引擎，服务不中断
- **结构化知识库** — KDIGO 规则、药物相互作用、科室指南以结构化数据注入 Prompt
- **RAG 接口预留** — `KnowledgeSource` trait 统一抽象，pgvector 扩展预启用
- **配额 & 成本感知** — 月度 token 预算、每患者日限、成本追踪、预算告警
- **事件驱动管线** — 体征异常/新化验报告/透析完成自动触发分析
- **两级缓存** — Redis TTL + DB 持久化，提升重复分析响应速度

---

## 2. 整体架构

### 2.1 核心数据流

```
                     ┌─────────────────────────┐
                     │      触发来源             │
                     │  SSE手动/定时/事件驱动    │
                     └───────────┬─────────────┘
                                 │
                     ┌───────────▼─────────────┐
                     │    1. 配额检查           │
                     │  QuotaService.check()   │
                     └───────────┬─────────────┘
                                 │ 通过
                     ┌───────────▼─────────────┐
                     │    2. 缓存检查           │
                     │  CacheService.get()     │
                     │  (Redis TTL + DB hash)  │
                     └───┬───────────────┬─────┘
                    命中 │               │ 未命中
                        ▼               ▼
                   直接返回     ┌───────────────────┐
                                │ 3. 路由决策        │
                                │ Router.resolve()  │
                                │ (租户配置→分析类型) │
                                └──┬──────────┬─────┘
                          规则引擎 │          │ LLM
                                  ▼          ▼
                        LocalRules    ProviderRegistry
                        (零成本)      .get_provider()
                                          │
                                 ┌────────▼────────┐
                                 │ 4. 知识上下文注入 │
                                 │ KnowledgeSource  │
                                 │ .get_context()   │
                                 └────────┬────────┘
                                          │
                                 ┌────────▼────────┐
                                 │ 5. 执行分析      │
                                 │ Provider调用     │
                                 │ + SSE流式返回    │
                                 └────────┬────────┘
                                          │
                                 ┌────────▼────────┐
                                 │ 6. 后处理        │
                                 │ 解析+建议+事件   │
                                 │ + 用量记录       │
                                 │ + 缓存写入       │
                                 └─────────────────┘
```

### 2.2 新增文件结构

```
crates/erp-ai/src/
├── provider/
│   ├── mod.rs          # AiProvider trait（已有，不变）
│   ├── claude.rs       # ClaudeProvider（已有，不变）
│   ├── openai.rs       # OpenAIProvider（新增）
│   ├── ollama.rs       # OllamaProvider（新增）
│   └── registry.rs     # ProviderRegistry（新增）
├── config.rs           # AiConfig + ProviderConfig（新增）
├── knowledge/
│   ├── mod.rs          # KnowledgeSource trait（新增）
│   ├── structured.rs   # StructuredKnowledgeSource（新增）
│   └── vector.rs       # VectorKnowledgeSource（预留 stub）
├── service/
│   ├── analysis.rs     # 现有（扩展：集成 ProviderRegistry + 知识库上下文）
│   ├── auto_analysis.rs # 现有（改为入队逻辑）
│   ├── local_rules.rs  # 现有（扩展：更多规则 + 与知识库联动）
│   ├── quota.rs        # 配额服务（新增）
│   ├── cache.rs        # 缓存服务（新增）
│   ├── analysis_queue.rs # 分析队列（新增）
│   └── ...             # 其余不变
└── handler/
    ├── mod.rs          # 现有（扩展：配额检查 + 降级逻辑）
    ├── provider_admin_handler.rs  # Provider 管理 API（新增）
    └── quota_handler.rs           # 配额管理 API（新增）
```

### 2.3 核心抽象

```rust
// provider/registry.rs
pub struct ProviderRegistry {
    providers: DashMap<String, ProviderEntry>,
    health_checker: tokio::task::JoinHandle<()>,
}

pub struct ProviderEntry {
    provider: Box<dyn AiProvider>,
    config: ProviderConfig,
    health: Arc<RwLock<ProviderHealth>>,
}

pub enum ProviderHealth {
    Healthy { last_check: DateTime<Utc> },
    Degraded { last_check: DateTime<Utc>, error: String },
    Unavailable { since: DateTime<Utc>, error: String },
}

// config.rs
pub struct AiConfig {
    pub default_provider: String,
    pub providers: HashMap<String, ProviderConfig>,
    pub cache_ttl_seconds: u64,
    pub quota_check_enabled: bool,
}

pub struct ProviderConfig {
    pub provider_type: ProviderType,  // Claude / OpenAI / Ollama / Rules
    pub api_key_env: Option<String>,
    pub base_url: Option<String>,
    pub default_model: String,
    pub max_tokens: u32,
    pub temperature: f32,
    pub is_enabled: bool,
}

// knowledge/mod.rs
#[async_trait]
pub trait KnowledgeSource: Send + Sync {
    async fn get_context(&self, query: &KnowledgeQuery) -> AiResult<KnowledgeContext>;
    fn source_type(&self) -> &str;
    async fn health_check(&self) -> bool;
    async fn entry_count(&self) -> u64;
}
```

---

## 3. 多 Provider 路由引擎

### 3.1 路由决策流程

每次分析请求按以下优先级链解析 Provider：

1. 分析类型覆盖（`ai_tenant_configs.analysis_type_overrides` JSONB）
2. 租户默认 Provider（`ai_tenant_configs.default_provider`）
3. ProviderRegistry 健康检查 → 不可用时走降级链：
   - 配置的 `fallback_provider`
   - 其他可用 Provider（按配置顺序）
   - `LocalRulesEngine`（零成本降级）

### 3.2 租户级 Provider 配置

新增数据库表：

```sql
CREATE TABLE ai_tenant_configs (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v7(),
    tenant_id UUID NOT NULL,  -- 不设外键：tenants 表在 erp-auth，跨模块不直接引用
    default_provider VARCHAR(50) NOT NULL DEFAULT 'claude',
    fallback_provider VARCHAR(50),
    monthly_token_budget BIGINT,
    analysis_type_overrides JSONB,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by UUID NOT NULL,
    updated_by UUID NOT NULL,
    deleted_at TIMESTAMPTZ,
    version INT NOT NULL DEFAULT 1,
    UNIQUE(tenant_id)
);
```

`analysis_type_overrides` 示例：

```json
{
    "lab_report": "claude",
    "trends": "ollama",
    "report_summary": "openai"
}
```

### 3.3 ProviderRegistry 核心方法

```rust
impl ProviderRegistry {
    /// 解析最终使用的 Provider，含降级链
    pub async fn resolve(
        &self,
        tenant_config: &AiTenantConfig,
        analysis_type: &AnalysisType,
    ) -> AiResult<ResolvedProvider>;

    /// 注册新 Provider（初始化阶段调用，一次性构建）
    pub fn register(&self, name: String, provider: Box<dyn AiProvider>);

    /// 获取指定 Provider（用于 Admin 测试）
    pub fn get_provider(&self, name: &str) -> Option<&dyn AiProvider>;

    /// 全量健康检查（后台 60s 间隔）
    pub async fn health_check_all(&self) -> HashMap<String, ProviderHealth>;
}
```

### 3.4 后台健康检查

每 60 秒对所有注册 Provider 执行轻量级 health_check：
- Claude: `GET /v1/models`
- OpenAI: `GET /v1/models`
- Ollama: `GET /api/tags`
- 连续 3 次失败标记为 Unavailable
- 恢复后自动标记 Healthy

### 3.5 新增 Provider 实现

#### OpenAIProvider

```rust
pub struct OpenAiProvider {
    client: reqwest::Client,
    api_key: String,
    base_url: String,  // 默认 https://api.openai.com
}
```

- OpenAI Chat Completions API（`/v1/chat/completions`）
- SSE 流式解析 `data: [DONE]` 边界
- token 用量从 `usage` 字段提取

#### OllamaProvider

```rust
pub struct OllamaProvider {
    client: reqwest::Client,
    base_url: String,  // 默认 http://localhost:11434
}
```

- Ollama API（`/api/chat`），`stream: true`
- 无 API Key，无 token 计费（成本为零）
- 适合私有化部署客户

### 3.6 Provider 管理 API

```
GET  /api/v1/ai/providers          — 列出所有 Provider 及健康状态
GET  /api/v1/ai/providers/:name    — 单个 Provider 详情
POST /api/v1/ai/providers/:name/test — 连通性测试
PUT  /api/v1/ai/tenant-config      — 更新租户 Provider 配置
GET  /api/v1/ai/tenant-config      — 获取租户配置
```

权限码：`ai.provider.manage`（全局 Provider 操作）、`ai.analysis.manage`（租户配置）

### 3.7 AnalysisService 重构

当前 `AnalysisService` 持有 `provider: Box<dyn AiProvider>`（单实例硬绑定）。重构为：

```rust
// 重构前（service/analysis.rs）
pub struct AnalysisService {
    provider: Box<dyn AiProvider>,  // 硬编码 Claude
    // ...
}

// 重构后
pub struct AnalysisService {
    registry: Arc<ProviderRegistry>,  // 替换为 Registry
    quota: Arc<QuotaService>,
    cache: Arc<CacheService>,
    knowledge: Arc<dyn KnowledgeSource>,
    // ...
}
```

`AiState` 构造变更：

```rust
// state.rs 重构
pub struct AiState {
    db: DatabaseConnection,
    event_bus: Arc<EventBus>,
    analysis: AnalysisService,
    prompt: PromptService,
    usage: UsageService,
    suggestion: SuggestionService,
    health_provider: Arc<dyn HealthDataProvider>,
    // 新增字段由 AnalysisService 内部持有
}
```

迁移策略：Phase 1 先保留 `AnalysisService` 接口不变，内部将 `provider` 替换为 `registry`，对外透明。

---

## 4. 知识库 & RAG 架构

### 4.1 三层知识模型

| 层级 | 范围 | 内容 | 存储 |
|------|------|------|------|
| L1 核心规则层 | 系统级 | KDIGO 分期规则、危急值阈值、药物相互作用规则 | `ai_knowledge_rules` 表 |
| L2 常识层 | 平台级 | ICD-10 映射、药物数据库、检验参考范围、通用健康建议 | `ai_knowledge_references` 表 |
| L3 本地化层 | 租户级 | 机构自定义指南、科室特色方案、本地化患者教育内容 | `ai_knowledge_guides` 表 |

### 4.2 知识查询接口

```rust
pub struct KnowledgeQuery {
    pub analysis_type: AnalysisType,
    pub patient_context: PatientSummary,  // 脱敏后的患者概况
    pub query_text: Option<String>,
    pub tenant_id: Uuid,
}

// PatientSummary 获取方式：通过 raw SQL 查询（避免跨 crate 依赖 erp-health）
// 与现有 handler/mod.rs 中 HealthDataProvider 的 raw SQL 模式一致
// 查询 patients 表基础信息（年龄/性别/标签），不查询 PII 字段

pub struct KnowledgeContext {
    pub source: String,
    pub context_text: String,
    pub references: Vec<Reference>,
    pub confidence: f32,
}
```

### 4.3 结构化知识源（Phase 1 实现）

```rust
pub struct StructuredKnowledgeSource {
    db: DatabaseConnection,
    rules_engine: LocalRulesEngine,
}

impl StructuredKnowledgeSource {
    /// 查询流程：
    /// 1. 匹配 L1 规则（conditions JSONB 匹配分析类型和患者状态）
    /// 2. 查询 L2 参考（category + tags 匹配）
    /// 3. 查询 L3 指南（tenant_id + department 匹配）
    /// 4. 合并为 context_text，按优先级排序
    async fn query_structured(&self, query: &KnowledgeQuery) -> AiResult<Vec<KnowledgeEntry>>;
}
```

### 4.4 知识数据库表

```sql
-- 知识规则表
CREATE TABLE ai_knowledge_rules (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v7(),
    tenant_id UUID,
    category VARCHAR(100) NOT NULL,
    rule_name VARCHAR(200) NOT NULL,
    conditions JSONB NOT NULL,
    conclusion TEXT NOT NULL,
    priority INT NOT NULL DEFAULT 0,
    is_active BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by UUID NOT NULL,
    updated_by UUID NOT NULL,
    deleted_at TIMESTAMPTZ,
    version INT NOT NULL DEFAULT 1
);

-- 知识参考表
CREATE TABLE ai_knowledge_references (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v7(),
    tenant_id UUID,
    title VARCHAR(500) NOT NULL,
    category VARCHAR(100) NOT NULL,
    content TEXT NOT NULL,
    source VARCHAR(200),
    tags TEXT[],
    is_active BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by UUID NOT NULL,
    updated_by UUID NOT NULL,
    deleted_at TIMESTAMPTZ,
    version INT NOT NULL DEFAULT 1
);

-- 知识指南表（租户级）
CREATE TABLE ai_knowledge_guides (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v7(),
    tenant_id UUID NOT NULL,
    title VARCHAR(500) NOT NULL,
    department VARCHAR(100),
    content TEXT NOT NULL,
    applies_to TEXT[],
    is_active BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by UUID NOT NULL,
    updated_by UUID NOT NULL,
    deleted_at TIMESTAMPTZ,
    version INT NOT NULL DEFAULT 1
);
```

### 4.5 知识上下文注入

通过 Prompt 模板变量注入：

```
基于以下知识库信息：
{{knowledge_context}}

分析以下患者数据：
{{sanitized_data}}
```

`KnowledgeSource.get_context()` 的返回值填入 `knowledge_context`。

### 4.6 向量知识源（Phase 2 预留）

Phase 1 启用 pgvector 扩展：

```sql
CREATE EXTENSION IF NOT EXISTS vector;
```

预留 `VectorKnowledgeSource` stub，Phase 2 实现嵌入管道：

```sql
-- Phase 2 使用
-- CREATE TABLE ai_knowledge_embeddings (
--     id UUID PRIMARY KEY DEFAULT uuid_generate_v7(),
--     source_id UUID NOT NULL,
--     source_type VARCHAR(50) NOT NULL,
--     chunk_text TEXT NOT NULL,
--     embedding vector(1536),
--     metadata JSONB
-- );
```

### 4.7 知识库管理 API

```
GET    /api/v1/ai/knowledge/rules          — 规则列表
POST   /api/v1/ai/knowledge/rules          — 创建规则
PUT    /api/v1/ai/knowledge/rules/:id      — 更新规则
DELETE /api/v1/ai/knowledge/rules/:id      — 软删除

GET    /api/v1/ai/knowledge/references     — 参考列表
POST   /api/v1/ai/knowledge/references     — 新增参考
PUT    /api/v1/ai/knowledge/references/:id — 更新
DELETE /api/v1/ai/knowledge/references/:id — 软删除

GET    /api/v1/ai/knowledge/guides         — 指南列表
POST   /api/v1/ai/knowledge/guides         — 新增指南
PUT    /api/v1/ai/knowledge/guides/:id     — 更新
DELETE /api/v1/ai/knowledge/guides/:id     — 软删除
```

权限码：`ai.knowledge.list` / `ai.knowledge.manage`

---

## 5. 缓存 & 事件驱动管线

### 5.1 两级缓存

```
请求 → L1 Redis 缓存 (TTL=1h)
         │ 命中 → 直接返回
         │ 未命中 ↓
         → L2 DB 缓存 (SHA-256 hash 复用，已有)
         │ 命中 → 回填 Redis + 返回
         │ 未命中 ↓
         → 执行完整分析 → 写入 Redis + DB
```

### 5.2 CacheService

```rust
pub struct CacheService {
    redis: RedisConnection,
    db: DatabaseConnection,
    default_ttl: Duration,
}

// 缓存键格式: ai:cache:{tenant_id}:{analysis_type}:{input_hash}:{prompt_version}
impl CacheService {
    pub async fn get(&self, key: &CacheKey) -> AiResult<Option<CachedAnalysis>>;
    pub async fn set(&self, key: &CacheKey, value: &CachedAnalysis) -> AiResult<()>;
    pub async fn invalidate_tenant(&self, tenant_id: Uuid) -> AiResult<()>;
}
```

缓存失效触发条件：
- Provider 切换 → `invalidate_tenant`
- Prompt 更新 → `invalidate_tenant`（新 prompt_version 自动失效旧缓存）
- 知识库更新 → `invalidate_tenant`（知识变化影响分析结果）

Redis 接入方式：
- Redis 连接池从 `AppState` 共享获取（与 erp-core 其他模块共用同一 Redis 实例）
- `erp-ai` 的 `Cargo.toml` 新增 `redis` + `deadpool-redis` 依赖
- Redis 不可用时自动降级为仅 DB 缓存：`CacheService::get()` 先查 Redis，Redis 报错则静默降级查 DB，不阻塞分析流程

### 5.3 事件驱动触发

扩展 `module.rs on_startup` 订阅：

| 事件 | 触发条件 | 分析类型 | 优先级 |
|------|----------|---------|--------|
| `health_data.critical_alert` | 体征超出参考范围（erp-health 已发布） | 趋势分析 | 高 |
| `lab_report.uploaded` | 新化验报告上传（erp-health 已发布） | 化验单解读 | 中 |
| `appointment.confirmed` | 预约确认/完成（erp-health 已发布） | 报告摘要 | 低 |
| `dialysis.record.created` | 透析记录创建（erp-health 已发布） | KDIGO 风险评估 | 高 |
| `ai.reanalysis.requested` | 建议执行后 7/14/30 天（erp-ai 已发布） | 再分析 | 中 |

### 5.4 分析队列

```rust
pub struct AnalysisQueue {
    db: DatabaseConnection,
    max_concurrent: usize,  // 默认 3
}

impl AnalysisQueue {
    pub async fn enqueue(&self, job: AnalysisJob) -> AiResult<Uuid>;
    pub async fn run_worker(&self, registry: &ProviderRegistry, cache: &CacheService);
    pub async fn queue_status(&self, tenant_id: Uuid) -> AiResult<QueueStatus>;
}
```

新增数据库表：

```sql
CREATE TABLE ai_analysis_queue (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v7(),
    tenant_id UUID NOT NULL,
    patient_id UUID NOT NULL,
    analysis_type VARCHAR(50) NOT NULL,
    priority INT NOT NULL DEFAULT 0,
    -- 状态: pending → running → completed/failed/cancelled
    -- 重试: failed 且 retry_count < max_retries → pending
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    source_event VARCHAR(100),
    scheduled_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    started_at TIMESTAMPTZ,
    completed_at TIMESTAMPTZ,
    result_analysis_id UUID REFERENCES ai_analyses(id),
    error_message TEXT,
    retry_count INT NOT NULL DEFAULT 0,
    max_retries INT NOT NULL DEFAULT 2,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by UUID NOT NULL,
    updated_by UUID NOT NULL,
    deleted_at TIMESTAMPTZ,
    version INT NOT NULL DEFAULT 1
);
```

### 5.5 与现有 auto_analysis 合并

当前 `auto_analysis.rs`（每 24h 扫描高风险患者）并入 `AnalysisQueue`：
- 定时扫描变为队列的定时入队逻辑
- 队列负责实际执行调度和并发控制
- 保留"24h 扫描高风险患者"逻辑，但通过队列执行

---

## 6. 配额 & 成本管理

### 6.1 配额模型

```
租户配额 (ai_tenant_configs)
    ├── 月度 token 预算 (monthly_token_budget)
    │      └── 80% → 告警事件
    │      └── 100% → 拒绝请求 / 降级到规则引擎
    ├── 每患者每日分析次数 (default: 10)
    └── 分析类型限制 (JSONB)
           e.g. {"lab_report": 5, "trends": 20, "report_summary": 3}
```

### 6.2 QuotaService

```rust
pub struct QuotaService {
    db: DatabaseConnection,
    redis: RedisConnection,
}

pub struct QuotaCheckResult {
    pub allowed: bool,
    pub reason: Option<QuotaDenyReason>,
    pub remaining_budget: Option<u64>,
    pub remaining_daily: Option<u32>,
}

pub enum QuotaDenyReason {
    MonthlyBudgetExhausted,
    DailyLimitReached { limit: u32, current: u32 },
    AnalysisTypeLimitReached { analysis_type: String, limit: u32 },
}
```

配额检查位于数据流第 1 步（路由之前）：
- `allowed=true` → 继续
- `MonthlyBudgetExhausted` → 降级规则引擎
- 其他拒绝原因 → 返回 429 Too Many Requests

配额消耗统计复用已有 `ai_usage` 表：
- 月度 token 预算消耗通过 `SUM(input_tokens + output_tokens) WHERE tenant_id = ? AND created_at BETWEEN ? AND ?` 聚合查询
- 不新建独立的配额追踪表，避免数据冗余
- Redis 缓存当日/当月用量计数器（TTL=24h/31d），减少 DB 查询

### 6.3 成本估算

```rust
struct ModelPricing {
    input_per_million: u32,
    output_per_million: u32,
}

// 默认定价（可配置覆盖）
// Claude Sonnet:   $3/M input, $15/M output
// Claude Haiku:    $0.25/M input, $1.25/M output
// OpenAI GPT-4o:   $2.5/M input, $10/M output
// Ollama (本地):   $0
// LocalRules:      $0
```

### 6.4 预算告警事件

```rust
pub struct BudgetAlertEvent {
    tenant_id: Uuid,
    alert_level: BudgetAlertLevel,  // Warning(80%) / Critical(95%) / Exhausted(100%)
    current_usage_tokens: u64,
    budget_tokens: u64,
    percentage: f32,
}
```

事件名：`ai.budget.alert`（携带 `alert_level` 字段区分 Warning / Critical / Exhausted）
erp-message 模块订阅 → 通知租户管理员

### 6.5 配额管理 API

```
GET  /api/v1/ai/tenant-config           — 获取配额配置
PUT  /api/v1/ai/tenant-config           — 更新配额配置
GET  /api/v1/ai/usage/overview          — 当月用量概览
GET  /api/v1/ai/usage/by-type           — 按分析类型统计
GET  /api/v1/ai/usage/by-day            — 按日统计
GET  /api/v1/ai/usage/by-provider       — 按 Provider 统计
GET  /api/v1/ai/cost/estimate/:type     — 单次分析成本估算
```

---

## 7. 分阶段实施

### 7.1 Phase 1（Week 1-3）：路由引擎 + 配额基础

| 任务 | 涉及文件 | 产出 |
|------|---------|------|
| `AiConfig` + `ProviderConfig` | `config.rs` (新) | TOML 配置解析 |
| `ProviderRegistry` + 健康检查 | `provider/registry.rs` (新) | Provider 注册/解析/降级 |
| `OpenAIProvider` | `provider/openai.rs` (新) | OpenAI 兼容 API |
| `OllamaProvider` | `provider/ollama.rs` (新) | 本地模型 |
| `ai_tenant_configs` 表 | migration + entity (新) | 租户配置 |
| `QuotaService` 基础版 | `service/quota.rs` (新) | 配额检查 + 用量记录 |
| Provider Admin API | `handler/provider_admin_handler.rs` (新) | 管理接口 |
| 集成到 AnalysisService | `service/analysis.rs` (改) | 路由决策替换硬编码 |

验收：租户可配置 Provider，降级链工作，超配额请求被拒绝或降级。

### 7.2 Phase 2（Week 4-5）：缓存 + 事件驱动

| 任务 | 涉及文件 | 产出 |
|------|---------|------|
| `CacheService` Redis 缓存 | `service/cache.rs` (新) | 两级缓存 |
| `AnalysisQueue` | `service/analysis_queue.rs` (新) | 异步分析调度 |
| `ai_analysis_queue` 表 | migration + entity (新) | 队列持久化 |
| 事件订阅扩展 | `module.rs` (改) | 4 个新事件触发 |
| 合并 auto_analysis | `service/auto_analysis.rs` (改) | 入队逻辑 |

验收：缓存命中率 > 30%（重复分析），体征异常自动入队分析。

### 7.3 Phase 3（Week 6-8）：知识库 + 成本管理 + Admin UI

| 任务 | 涉及文件 | 产出 |
|------|---------|------|
| `KnowledgeSource` trait | `knowledge/mod.rs` (新) | 统一抽象 |
| `StructuredKnowledgeSource` | `knowledge/structured.rs` (新) | 结构化查询 |
| 知识库表 (3 张) + pgvector | migration + entity (新) | 知识 CRUD + 向量预留 |
| 成本估算 + 预算告警 | `service/quota.rs` (扩展) | 成本追踪 |
| 用量统计 API | `handler/quota_handler.rs` (新) | 统计接口 |
| Web Admin UI | 前端 (新) | Provider/配额/知识库管理页 |

验收：结构化知识注入 Prompt 工作，单次分析成本可查，管理页面可用。

---

## 8. 新增权限码

| 权限码 | 说明 | 角色 | 状态 |
|--------|------|------|------|
| `ai.provider.manage` | Provider 级管理 | 超级管理员 | 已有（module.rs 已声明） |
| `ai.knowledge.list` | 知识库查看 | 医护/管理员 | 新增 |
| `ai.knowledge.manage` | 知识库管理 | 管理员 | 新增 |
| `ai.quota.manage` | 配额管理 | 管理员 | 新增 |

已有权限码（无需新增）：`ai.analysis.list/manage`、`ai.prompt.list/manage`、`ai.usage.list`、`ai.suggestion.list/manage`、`ai.provider.manage`

---

## 9. 新增事件类型

| 事件名 | 发布方 | 消费方 | 说明 |
|--------|--------|--------|------|
| `ai.budget.alert` | QuotaService | erp-message | 预算告警（level 字段区分 Warning/Critical/Exhausted） |
| `ai.analysis.queued` | AnalysisQueue | 日志 | 分析任务入队 |

---

## 10. 新增数据库表汇总

| 表名 | 用途 | Phase |
|------|------|-------|
| `ai_tenant_configs` | 租户 AI 配置 | Phase 1 |
| `ai_analysis_queue` | 分析任务队列 | Phase 2 |
| `ai_knowledge_rules` | 知识规则 | Phase 3 |
| `ai_knowledge_references` | 知识参考 | Phase 3 |
| `ai_knowledge_guides` | 知识指南 | Phase 3 |
| `ai_knowledge_embeddings` | 向量嵌入（预留） | Phase 4 |

所有表遵循项目规范：`id`（UUIDv7）、`tenant_id`、`created_at`、`updated_at`、`version`、`deleted_at`（软删除）。

---

## 11. 风险与缓解

| 风险 | 概率 | 影响 | 缓解 |
|------|------|------|------|
| Ollama 本地模型质量不足 | 中 | 分析质量下降 | 保留 Claude 降级路径，本地模型仅用于基础分析 |
| Redis 不可用导致缓存失效 | 低 | 性能回退到 DB 查询 | CacheService 降级到仅 DB 缓存 |
| 知识库数据录入工作量 | 高 | Phase 3 延期 | 提供批量导入 API + 预置核心规则种子数据 |
| 多 Provider token 计量不一致 | 中 | 成本追踪偏差 | 统一从 Provider 响应的 usage 字段提取，不估算 |
| pgvector 扩展运维复杂度 | 低 | 数据库升级需求 | Docker 镜像预包含 pgvector，无需额外编译 |