# Provider 系统开发文档

## 当前版本功能 (v0.2.0)

### 已完成功能

1. **CQTAI nano 图像适配器** (`app/services/adapters/image/cqtai.py`)
   - 异步生成 + 轮询获取结果
   - 支持 nano-banana / nano-banana-pro 模型
   - 支持多种分辨率和画面比例
   - 支持图生图 (filesUrl)

2. **密钥加密存储** (`app/services/secret_service.py`)
   - Fernet 对称加密，密钥从 SECRET_KEY 派生
   - Provider API Key 自动加密存储
   - 密钥管理 API (CRUD)

3. **指标收集系统** (`app/services/provider_metrics.py`)
   - 调用成功率、延迟、成本统计
   - 时间窗口聚合查询
   - 已集成到 provider_router

4. **熔断器功能** (`app/services/provider_metrics.py`)
   - 连续失败 3 次触发熔断
   - 60 秒后自动恢复尝试
   - 健康状态持久化到数据库

5. **管理后台前端** (`app/admin_app.py`)
   - 独立端口部署 (8001)
   - Vue 3 + Tailwind CSS 单页应用
   - Provider CRUD 管理
   - 密钥管理界面
   - Basic Auth 认证

### 配置说明

```bash
# 启动主应用
uvicorn app.main:app --port 8000

# 启动管理后台 (独立端口)
uvicorn app.admin_app:app --port 8001
```

环境变量:
```
CQTAI_API_KEY=your-cqtai-api-key
ENABLE_ADMIN_CONSOLE=true
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-secure-password
```

---

## 下一版本优化计划 (v0.3.0)

### 高优先级

#### 1. 智能负载分流 (方案 B)
**目标**: 主渠道压力大时自动分流到后备渠道

**实现方案**:
- 监控指标: 并发数、响应延迟、错误率
- 分流阈值配置:
  ```python
  class LoadBalanceConfig:
      max_concurrent: int = 10  # 并发超过此值时分流
      max_latency_ms: int = 5000  # 延迟超过此值时分流
      max_error_rate: float = 0.1  # 错误率超过 10% 时分流
  ```
- 分流策略: 加权轮询，根据健康度动态调整权重

**涉及文件**:
- `app/services/provider_router.py` - 添加负载均衡逻辑
- `app/services/provider_metrics.py` - 添加并发计数器
- `app/db/admin_models.py` - 添加 LoadBalanceConfig 模型

#### 2. Storybook 适配器
**目标**: 生成可翻页的分页故事书

**实现方案**:
- 参考 Gemini AI Story Generator 格式
- 输出结构:
  ```python
  class StorybookPage:
      page_number: int
      text: str
      image_prompt: str
      image_url: str | None

  class Storybook:
      title: str
      pages: list[StorybookPage]
      cover_url: str | None
  ```
- 集成文本 + 图像生成流水线

**涉及文件**:
- `app/services/adapters/storybook/` - 新建目录
- `app/api/stories.py` - 添加 storybook 生成端点

### 中优先级

#### 3. 成本追踪系统
**目标**: 记录实际消费，支持预算控制

**实现方案**:
- 成本记录表:
  ```python
  class CostRecord:
      user_id: str
      provider_id: str
      capability: str  # text/image/tts
      estimated_cost: Decimal
      actual_cost: Decimal | None
      timestamp: datetime
  ```
- 预算配置:
  ```python
  class BudgetConfig:
      user_id: str
      daily_limit: Decimal
      monthly_limit: Decimal
      alert_threshold: float = 0.8  # 80% 时告警
  ```
- 超预算处理: 拒绝请求 / 降级到低成本 provider

**涉及文件**:
- `app/db/admin_models.py` - 添加 CostRecord, BudgetConfig
- `app/services/cost_tracker.py` - 新建
- `app/api/admin_providers.py` - 添加成本查询 API

#### 4. 指标可视化
**目标**: 管理后台展示供应商指标图表

**实现方案**:
- 添加指标查询 API:
  - GET /admin/metrics/summary - 汇总统计
  - GET /admin/metrics/timeline - 时间线数据
  - GET /admin/metrics/providers/{id} - 单个供应商详情
- 前端使用 Chart.js 或 ECharts 展示

### 低优先级

#### 5. 多租户 Provider 配置
**目标**: 每个租户可配置独立 provider 列表和 API Key

**实现方案**:
- 租户配置表:
  ```python
  class TenantProviderConfig:
      tenant_id: str
      provider_type: str
      provider_ids: list[str]  # 按优先级排序
      api_key_override: str | None  # 加密存储
  ```
- 路由时优先使用租户配置，回退到全局配置

#### 6. Provider 健康检查调度器
**目标**: 定期主动检查 provider 健康状态

**实现方案**:
- Celery Beat 定时任务
- 每 5 分钟检查一次所有启用的 provider
- 更新 ProviderHealth 表

#### 7. 适配器热加载
**目标**: 支持运行时动态加载新适配器

**实现方案**:
- 适配器插件目录: `app/services/adapters/plugins/`
- 启动时扫描并注册
- 提供 API 触发重新扫描

---

## API 变更记录

### v0.2.0 新增

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/admin/secrets` | 列出所有密钥名称 |
| POST | `/admin/secrets` | 创建/更新密钥 |
| DELETE | `/admin/secrets/{name}` | 删除密钥 |
| GET | `/admin/secrets/{name}/verify` | 验证密钥有效性 |

### 计划中 (v0.3.0)

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/admin/metrics/summary` | 指标汇总 |
| GET | `/admin/metrics/timeline` | 时间线数据 |
| POST | `/api/storybook/generate` | 生成分页故事书 |
| GET | `/admin/costs` | 成本统计 |
| POST | `/admin/budgets` | 设置预算 |

---

## 适配器开发指南

### 添加新适配器

1. 创建适配器文件:
```python
# app/services/adapters/image/new_provider.py
from app.services.adapters.base import AdapterConfig, BaseAdapter
from app.services.adapters.registry import AdapterRegistry

@AdapterRegistry.register("image", "new_provider")
class NewProviderAdapter(BaseAdapter[str]):
    adapter_type = "image"
    adapter_name = "new_provider"

    async def execute(self, prompt: str, **kwargs) -> str:
        # 实现生成逻辑
        pass

    async def health_check(self) -> bool:
        # 实现健康检查
        pass

    @property
    def estimated_cost(self) -> float:
        return 0.01  # USD
```

2. 在 `__init__.py` 中导入:
```python
# app/services/adapters/__init__.py
from app.services.adapters.image import new_provider as _new_provider  # noqa: F401
```

3. 添加配置:
```python
# app/core/config.py
new_provider_api_key: str = ""

# app/services/provider_router.py
API_KEY_MAP["new_provider"] = "new_provider_api_key"
```

4. 更新 `.env.example`:
```
NEW_PROVIDER_API_KEY=
```