# 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 模型加载。