Files

congsh 37d282c0a2 test: 添加测试框架和全面的单元测试

- 添加 pytest 配置和测试依赖到 requirements.txt
- 创建测试包结构和 fixtures (conftest.py)
- 添加数据库模块的 CRUD 操作测试 (test_database.py)
- 添加 Provider 插件系统测试 (test_providers.py)
- 添加调度器模块测试 (test_scheduler.py)
- 添加 API 路由测试 (test_api.py)
- 添加回归测试覆盖边界条件和错误处理 (test_regressions.py)
- 添加健康检查端点用于容器监控
- 修复调度器中的日历计算逻辑和任务执行参数处理
- 更新数据库函数以返回操作结果状态

2026-03-31 22:36:18 +08:00

3.1 KiB

Raw Blame History

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 仪表盘。

启动命令

# 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/ 下创建文件即可：

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 兼容格式（自动转换请求/响应格式）

支持两种路由方式：

通过 X-Plan-Id header 直接指定 Plan
通过 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 模型加载。

3.1 KiB Raw Blame History Unescape Escape