# LLM Gateway 实施计划

## 概述

基于已批准的设计文档 `docs/plans/2026-05-01-llm-gateway-design.md`，本计划将实现分为 6 个批次，每批次包含多个可验证的任务。

---

## 批次 1：项目基础架构

### 任务 1.1：初始化项目结构
- **目标**：创建项目目录结构和基础文件
- **涉及文件**：
  ```
  llm-gateway/
  ├── app/
  │   ├── __init__.py
  │   ├── main.py
  │   └── config.py
  ├── tests/
  │   └── __init__.py
  ├── requirements.txt
  ├── .gitignore
  └── README.md
  ```
- **验证方式**：目录结构正确，Python 可导入 app 模块
- **完成判定**：`python -c "import app"` 无报错

### 任务 1.2：配置管理模块
- **目标**：实现 Pydantic Settings 配置管理
- **涉及文件**：
  - `app/config.py`
  - `app/.env.example`
- **验证方式**：配置类可正确读取环境变量
- **完成判定**：单元测试通过

### 任务 1.3：数据库连接与 Schema
- **目标**：初始化 SQLite 数据库和表结构
- **涉及文件**：
  - `app/db/database.py`
  - `app/db/schema.sql`
- **验证方式**：数据库文件创建成功，表结构正确
- **完成判定**：`sqlite3 data/gateway.db ".tables"` 显示所有表

### 任务 1.4：日志配置
- **目标**：配置结构化日志
- **涉及文件**：
  - `app/utils/logging.py`
- **验证方式**：日志输出格式正确
- **完成判定**：单元测试验证日志格式

---

## 批次 2：数据模型与 Admin API

### 任务 2.1：数据模型定义
- **目标**：定义 SQLAlchemy ORM 模型
- **涉及文件**：
  - `app/models/provider.py`
  - `app/models/api_key.py`
  - `app/models/project.py`
  - `app/models/model_alias.py`
  - `app/models/usage.py`
  - `app/models/__init__.py`
- **验证方式**：模型可正确映射到数据库表
- **完成判定**：单元测试通过

### 任务 2.2：加密工具
- **目标**：实现 API Key 哈希和 Provider Key 加密
- **涉及文件**：
  - `app/utils/crypto.py`
- **验证方式**：
  - bcrypt 哈希验证
  - AES-256 加密解密验证
- **完成判定**：单元测试通过

### 任务 2.3：Provider 管理 API
- **目标**：实现 Provider CRUD 接口
- **涉及文件**：
  - `app/api/admin/providers.py`
  - `app/api/admin/__init__.py`
- **验证方式**：
  - POST /admin/providers 创建 Provider
  - GET /admin/providers 列表查询
  - PUT /admin/providers/{id} 更新
  - DELETE /admin/providers/{id} 删除
- **完成判定**：集成测试通过

### 任务 2.4：Project 管理 API
- **目标**：实现 Project CRUD 接口
- **涉及文件**：
  - `app/api/admin/projects.py`
- **验证方式**：CRUD 接口可用
- **完成判定**：集成测试通过

### 任务 2.5：API Key 管理 API
- **目标**：实现 API Key CRUD 接口
- **涉及文件**：
  - `app/api/admin/keys.py`
- **验证方式**：
  - 创建 Key 返回明文 key（仅一次）
  - 验证 key_hash 存储正确
- **完成判定**：集成测试通过

### 任务 2.6：Model Alias 管理 API
- **目标**：实现 Model Alias CRUD 接口
- **涉及文件**：
  - `app/api/admin/models.py`
- **验证方式**：CRUD 接口可用
- **完成判定**：集成测试通过

---

## 批次 3：核心服务层

### 任务 3.1：Request Transformer 基础
- **目标**：实现请求格式转换基础框架
- **涉及文件**：
  - `app/core/transformer.py`
  - `app/schemas/openai.py`
  - `app/schemas/anthropic.py`
- **验证方式**：
  - OpenAI → Anthropic 转换测试
  - Anthropic → OpenAI 转换测试
- **完成判定**：单元测试通过

### 任务 3.2：Router 实现
- **目标**：实现模型别名解析和路由逻辑
- **涉及文件**：
  - `app/core/router.py`
- **验证方式**：
  - 简单别名解析
  - 路由组加权选择
  - Fallback 链解析
- **完成判定**：单元测试通过

### 任务 3.3：Rate Limiter 实现
- **目标**：实现 RPM/TPM 限流
- **涉及文件**：
  - `app/core/rate_limiter.py`
- **验证方式**：
  - 超过限制返回 429
  - 响应头正确
  - 窗口重置正确
- **完成判定**：单元测试通过

### 任务 3.4：Budget Controller 实现
- **目标**：实现 Key/Project 级预算控制
- **涉及文件**：
  - `app/core/budget.py`
- **验证方式**：
  - 超过 hard_limit 返回 402
  - soft_limit 告警日志
- **完成判定**：单元测试通过

### 任务 3.5：Circuit Breaker 实现
- **目标**：实现熔断器
- **涉及文件**：
  - `app/core/circuit_breaker.py`
- **验证方式**：
  - CLOSED → OPEN → HALF_OPEN → CLOSED 状态转换
- **完成判定**：单元测试通过

### 任务 3.6：Fallback/Retry 实现
- **目标**：实现重试和降级逻辑
- **涉及文件**：
  - `app/core/fallback.py`
- **验证方式**：
  - 指数退避重试
  - Fallback 到备用 Provider
- **完成判定**：单元测试通过

---

## 批次 4：Provider Adapters

### 任务 4.1：Adapter 基类与接口
- **目标**：定义 Provider Adapter 抽象接口
- **涉及文件**：
  - `app/adapters/base.py`
  - `app/adapters/__init__.py`
- **验证方式**：接口定义完整
- **完成判定**：代码审查通过

### 任务 4.2：OpenAI Adapter
- **目标**：实现 OpenAI Provider 适配器
- **涉及文件**：
  - `app/adapters/openai.py`
- **验证方式**：
  - 非流式请求测试
  - 流式请求测试
  - Token 计数测试
- **完成判定**：集成测试通过（使用 Mock 或真实 API）

### 任务 4.3：Anthropic Adapter
- **目标**：实现 Anthropic Provider 适配器
- **涉及文件**：
  - `app/adapters/anthropic.py`
- **验证方式**：
  - Messages API 格式请求
  - 流式响应处理
- **完成判定**：集成测试通过

### 任务 4.4：Azure OpenAI Adapter
- **目标**：实现 Azure OpenAI Provider 适配器
- **涉及文件**：
  - `app/adapters/azure.py`
- **验证方式**：
  - deployment_name 配置正确
  - api_base 路径正确
- **完成判定**：集成测试通过

### 任务 4.5：Google Gemini Adapter
- **目标**：实现 Google Gemini Provider 适配器
- **涉及文件**：
  - `app/adapters/gemini.py`
- **验证方式**：
  - Gemini API 格式转换
  - safety settings 处理
- **完成判定**：集成测试通过

### 任务 4.6：AWS Bedrock Adapter
- **目标**：实现 AWS Bedrock Provider 适配器
- **涉及文件**：
  - `app/adapters/bedrock.py`
- **验证方式**：
  - AWS 认证正确
  - model_id 格式正确
- **完成判定**：集成测试通过

---

## 批次 5：API 端点与集成

### 任务 5.1：Load Balancer 实现
- **目标**：实现负载均衡逻辑
- **涉及文件**：
  - `app/core/load_balancer.py`
- **验证方式**：
  - 加权轮询正确
  - 健康检查集成
- **完成判定**：单元测试通过

### 任务 5.2：Health Check 实现
- **目标**：实现 Provider 健康检查
- **涉及文件**：
  - `app/core/health_checker.py`
- **验证方式**：
  - 定时检查执行
  - 状态更新正确
- **完成判定**：单元测试通过

### 任务 5.3：/v1/chat/completions 端点
- **目标**：实现 OpenAI-compatible Chat Completions API
- **涉及文件**：
  - `app/api/v1/chat.py`
  - `app/api/v1/__init__.py`
- **验证方式**：
  - 使用 OpenAI SDK 调用成功
  - 流式响应正确
- **完成判定**：端到端测试通过

### 任务 5.4：/v1/messages 端点
- **目标**：实现 Anthropic Messages API
- **涉及文件**：
  - `app/api/v1/messages.py`
- **验证方式**：
  - 使用 Anthropic SDK 调用成功
- **完成判定**：端到端测试通过

### 任务 5.5：/v1/responses 端点
- **目标**：实现 OpenAI Responses API
- **涉及文件**：
  - `app/api/v1/responses.py`
- **验证方式**：
  - Responses API 格式正确处理
- **完成判定**：端到端测试通过

### 任务 5.6：认证中间件
- **目标**：实现 Virtual Key 认证
- **涉及文件**：
  - `app/middleware/auth.py`
- **验证方式**：
  - 有效 Key 通过
  - 无效 Key 返回 401
- **完成判定**：集成测试通过

### 任务 5.7：请求日志中间件
- **目标**：实现请求日志记录
- **涉及文件**：
  - `app/middleware/logging.py`
- **验证方式**：
  - 日志写入数据库
  - 包含所有必要字段
- **完成判定**：集成测试通过

---

## 批次 6：管理功能与部署

### 任务 6.1：Usage Dashboard API
- **目标**：实现使用统计查询接口
- **涉及文件**：
  - `app/api/admin/usage.py`
- **验证方式**：
  - GET /admin/usage/stats 返回正确统计
  - 按时间/模型/Provider 分组
- **完成判定**：集成测试通过

### 任务 6.2：审计日志
- **目标**：实现审计日志记录
- **涉及文件**：
  - `app/middleware/audit.py`
- **验证方式**：
  - 管理操作记录审计日志
- **完成判定**：集成测试通过

### 任务 6.3：Provider Health Check API
- **目标**：实现健康检查接口
- **涉及文件**：
  - `app/api/admin/health.py`
- **验证方式**：
  - GET /health 返回服务状态
  - GET /admin/providers/{id}/health 返回 Provider 状态
- **完成判定**：集成测试通过

### 任务 6.4：Docker 配置
- **目标**：创建 Docker 和 Docker Compose 配置
- **涉及文件**：
  - `Dockerfile`
  - `docker-compose.yml`
- **验证方式**：
  - docker build 成功
  - docker-compose up 服务正常
- **完成判定**：容器启动并可访问 API

### 任务 6.5：文档与示例
- **目标**：完善 README 和 API 文档
- **涉及文件**：
  - `README.md`
  - `docs/api.md`
  - `docs/deployment.md`
- **验证方式**：文档完整可读
- **完成判定**：代码审查通过

---

## 验证命令

### 单元测试
```bash
pytest tests/unit -v
```

### 集成测试
```bash
pytest tests/integration -v
```

### 全部测试
```bash
pytest -v --cov=app
```

### 类型检查
```bash
mypy app
```

### 代码风格
```bash
ruff check app
```

### 启动服务
```bash
uvicorn app.main:app --reload
```

---

## 风险与待确认项

1. **Provider API Key 获取**：需要各 Provider 的 API Key 用于测试
2. **AWS 凭证**：Bedrock 需要 AWS 凭证配置
3. **并发写入性能**：SQLite 高并发写入可能成为瓶颈，需测试验证
4. **Token 计数准确性**：不同 Provider 的 Token 计数方式可能不同

---

## 时间估算

| 批次 | 任务数 | 预计时间 |
|------|--------|----------|
| 批次 1 | 4 | 2-3 小时 |
| 批次 2 | 6 | 3-4 小时 |
| 批次 3 | 6 | 4-5 小时 |
| 批次 4 | 6 | 4-5 小时 |
| 批次 5 | 7 | 4-5 小时 |
| 批次 6 | 5 | 2-3 小时 |
| **总计** | **34** | **19-25 小时** |

---

## 依赖关系

```
批次 1 (基础架构)
    ↓
批次 2 (数据模型与 Admin API)
    ↓
批次 3 (核心服务层) ←─┐
    ↓                 │
批次 4 (Provider Adapters)
    ↓
批次 5 (API 端点与集成)
    ↓
批次 6 (管理功能与部署)
```