37d282c0a2
- 添加 pytest 配置和测试依赖到 requirements.txt - 创建测试包结构和 fixtures (conftest.py) - 添加数据库模块的 CRUD 操作测试 (test_database.py) - 添加 Provider 插件系统测试 (test_providers.py) - 添加调度器模块测试 (test_scheduler.py) - 添加 API 路由测试 (test_api.py) - 添加回归测试覆盖边界条件和错误处理 (test_regressions.py) - 添加健康检查端点用于容器监控 - 修复调度器中的日历计算逻辑和任务执行参数处理 - 更新数据库函数以返回操作结果状态
102 lines
3.1 KiB
Markdown
102 lines
3.1 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
多平台 AI Coding Plan 统一管理系统，支持 MiniMax、OpenAI、Google Gemini、智谱、Kimi 等多个 AI 平台的订阅计划管理。提供额度查询、刷新倒计时、API 代理转发、多媒体任务队列和 Web 仪表盘。
|
||
|
||
## 启动命令
|
||
|
||
```bash
|
||
# Docker 部署（推荐）
|
||
docker compose up -d
|
||
|
||
# 本地开发
|
||
pip install -r requirements.txt
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload
|
||
|
||
# 访问 API 文档
|
||
# http://localhost:8080/docs
|
||
```
|
||
|
||
## 核心架构
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
app/
|
||
├── main.py # FastAPI 入口，管理 lifespan
|
||
├── config.py # config.yaml 配置加载
|
||
├── database.py # aiosqlite 数据库层（所有 CRUD 操作）
|
||
├── models.py # Pydantic 数据模型
|
||
├── providers/ # Provider 插件系统（自动发现）
|
||
├── routers/ # API 路由
|
||
└── services/ # 后台服务（调度器、额度、队列）
|
||
```
|
||
|
||
### Provider 插件系统
|
||
|
||
新增平台无需修改核心代码，在 `app/providers/` 下创建文件即可：
|
||
|
||
```python
|
||
from app.providers.base import BaseProvider, Capability
|
||
|
||
class NewPlatformProvider(BaseProvider):
|
||
name = "new_platform"
|
||
display_name = "New Platform"
|
||
capabilities = [Capability.CHAT]
|
||
|
||
async def chat(self, messages, model, plan, stream=True, **kwargs):
|
||
yield "data: ..."
|
||
```
|
||
|
||
`ProviderRegistry` 会在启动时自动扫描并注册所有 `BaseProvider` 子类实例。
|
||
|
||
### 数据库设计
|
||
|
||
使用 SQLite + aiosqlite，所有 CRUD 操作集中在 `database.py` 中：
|
||
|
||
- **plans** - 订阅计划
|
||
- **quota_rules** - 额度规则（一个 Plan 可有多条规则）
|
||
- **model_routes** - 模型路由表（支持 priority fallback）
|
||
- **tasks** - 异步任务队列
|
||
- **quota_snapshots** - 额度历史快照
|
||
|
||
首次启动时，`seed_from_config()` 会从 `config.yaml` 导入种子数据。
|
||
|
||
### 四种刷新策略
|
||
|
||
`QuotaRule.refresh_type` 决定额度刷新方式：
|
||
|
||
| 类型 | 说明 | 关键参数 |
|
||
|---|---|---|
|
||
| `fixed_interval` | 固定间隔刷新 | `interval_hours` |
|
||
| `calendar_cycle` | 自然周期（日/周/月） | `calendar_unit` + `calendar_anchor` |
|
||
| `api_sync` | 调用平台 API 查询真实余额 | 无 |
|
||
| `manual` | 手动重置 | 无 |
|
||
|
||
刷新逻辑在 `app/services/scheduler.py:_refresh_quota_rules()` 中，每 30 秒执行一次。
|
||
|
||
### API 代理路由
|
||
|
||
- `/v1/chat/completions` - OpenAI 兼容格式
|
||
- `/v1/messages` - Anthropic 兼容格式（自动转换请求/响应格式）
|
||
|
||
支持两种路由方式：
|
||
1. 通过 `X-Plan-Id` header 直接指定 Plan
|
||
2. 通过 `model` 参数自动查找 `model_routes` 表（支持 priority fallback）
|
||
|
||
### 任务队列
|
||
|
||
异步任务支持图片、语音、视频生成，由 `scheduler.py:_process_task_queue()` 消费。
|
||
|
||
## 配置
|
||
|
||
主配置文件为 `config.yaml`，包含：
|
||
- `server.proxy_api_key` - API 代理鉴权 Key
|
||
- `database.path` - SQLite 数据库路径
|
||
- `plans` - 订阅计划种子数据
|
||
|
||
配置通过 `app/config.py` 的 Pydantic 模型加载。
|