|
|
@@ -0,0 +1,831 @@
|
|
|
+# Claude Relay Service API 完整文档 (v2.0)
|
|
|
+
|
|
|
+## 概述
|
|
|
+Claude Relay Service 是一个高性能的 Claude API 转发服务，提供用户管理、API Key 管理、积分系统等功能。采用统一的AdminController架构，提供完整的管理功能。
|
|
|
+
|
|
|
+## 架构特点
|
|
|
+- **统一管理控制器**: 所有管理API现在使用统一的 `AdminController` 实例
|
|
|
+- **模块化设计**: 按功能分组的清晰架构（用户套餐、API Key、缓存、系统管理）
|
|
|
+- **响应格式优化**: 统一的成功/错误响应格式
|
|
|
+- **高性能转发**: 三级缓存机制，支持流式和非流式请求
|
|
|
+
|
|
|
+## 认证方式
|
|
|
+- **Claude API Routes**: 使用 FastAPIKeyAuth 中间件进行 API Key 认证
|
|
|
+ - Header: `Authorization: Bearer {api_key}`
|
|
|
+- **Management API Routes**: 使用 AdminAPIAuth 中间件进行管理员 API Key 认证
|
|
|
+ - Header: `Authorization: Bearer {admin_api_key}`
|
|
|
+- **Health Routes**: 无需认证
|
|
|
+
|
|
|
+## 通用响应格式
|
|
|
+所有管理API接口遵循统一的响应格式：
|
|
|
+
|
|
|
+**成功响应**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {}
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**分页响应**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": [],
|
|
|
+ "pagination": {
|
|
|
+ "page": 1,
|
|
|
+ "limit": 20,
|
|
|
+ "total": 100
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**错误响应**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": false,
|
|
|
+ "message": "错误信息"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 1. Claude API 标准路由组 `/v1`
|
|
|
+
|
|
|
+### 1.1 发送消息
|
|
|
+- **路径**: `POST /v1/messages`
|
|
|
+- **描述**: Claude API 核心转发接口，与官方 API 完全兼容
|
|
|
+- **认证**: 需要 API Key
|
|
|
+- **控制器**: `controller.RelayMessages`
|
|
|
+
|
|
|
+**请求参数**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "model": "claude-3-sonnet-20240229",
|
|
|
+ "max_tokens": 1024,
|
|
|
+ "messages": [
|
|
|
+ {
|
|
|
+ "role": "user",
|
|
|
+ "content": "Hello, Claude!"
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "stream": false,
|
|
|
+ "temperature": 0.7
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**响应格式** (非流式):
|
|
|
+```json
|
|
|
+{
|
|
|
+ "id": "msg_01234567890abcdef",
|
|
|
+ "type": "message",
|
|
|
+ "role": "assistant",
|
|
|
+ "content": [
|
|
|
+ {
|
|
|
+ "type": "text",
|
|
|
+ "text": "Hello! How can I help you today?"
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "model": "claude-3-sonnet-20240229",
|
|
|
+ "stop_reason": "end_turn",
|
|
|
+ "stop_sequence": null,
|
|
|
+ "usage": {
|
|
|
+ "input_tokens": 12,
|
|
|
+ "output_tokens": 25
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**错误响应**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "error": {
|
|
|
+ "type": "authentication_error|invalid_request_error|api_error",
|
|
|
+ "message": "错误描述信息"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 1.2 获取模型列表
|
|
|
+- **路径**: `GET /v1/models`
|
|
|
+- **描述**: 获取可用的 Claude 模型列表
|
|
|
+- **认证**: 需要 API Key
|
|
|
+- **控制器**: `controller.GetModels`
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "object": "list",
|
|
|
+ "data": [
|
|
|
+ {
|
|
|
+ "id": "claude-3-sonnet-20240229",
|
|
|
+ "object": "model",
|
|
|
+ "created": 1677610602,
|
|
|
+ "owned_by": "anthropic"
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "id": "claude-3-opus-20240229",
|
|
|
+ "object": "model",
|
|
|
+ "created": 1677610602,
|
|
|
+ "owned_by": "anthropic"
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "id": "claude-3-haiku-20240307",
|
|
|
+ "object": "model",
|
|
|
+ "created": 1677610602,
|
|
|
+ "owned_by": "anthropic"
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 2. 管理API路由组 `/api` (AdminController)
|
|
|
+
|
|
|
+所有管理API现在使用统一的AdminController，提供更好的代码组织和维护性。
|
|
|
+
|
|
|
+### 2.1 🔑 用户套餐管理
|
|
|
+
|
|
|
+#### 2.1.1 创建或更新用户套餐
|
|
|
+- **路径**: `PUT /api/users/{userId}/plan`
|
|
|
+- **描述**: 为指定用户创建或更新套餐信息
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.CreateOrUpdateUserPlan`
|
|
|
+
|
|
|
+**请求参数**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "plan_name": "高级套餐",
|
|
|
+ "credit_limit": 100000,
|
|
|
+ "credit_recovery": 1000,
|
|
|
+ "duration_days": 30
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**字段说明**:
|
|
|
+- `plan_name` (string, required): 套餐名称，1-100字符
|
|
|
+- `credit_limit` (int64, required): 积分上限，不能为负
|
|
|
+- `credit_recovery` (int64, optional): 每日积分恢复数量，不能为负
|
|
|
+- `duration_days` (int, required): 有效期天数，1-3650天
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "user_id": 123,
|
|
|
+ "plan_name": "高级套餐",
|
|
|
+ "credit_limit": 100000,
|
|
|
+ "used_credits": 0,
|
|
|
+ "available_credits": 100000,
|
|
|
+ "credit_recovery": 1000,
|
|
|
+ "start_date": "2024-01-01T00:00:00Z",
|
|
|
+ "end_date": "2024-01-31T00:00:00Z",
|
|
|
+ "status": "active",
|
|
|
+ "operation": "created"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 2.1.2 查询用户套餐信息
|
|
|
+- **路径**: `GET /api/users/{userId}/plan`
|
|
|
+- **描述**: 获取指定用户的套餐详细信息
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.GetUserPlan`
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "user_id": 123,
|
|
|
+ "plan_name": "高级套餐",
|
|
|
+ "credit_limit": 100000,
|
|
|
+ "used_credits": 15000,
|
|
|
+ "available_credits": 85000,
|
|
|
+ "credit_recovery": 1000,
|
|
|
+ "last_recharge_at": "2025-08-07T09:00:01Z",
|
|
|
+ "status": "active",
|
|
|
+ "start_date": "2024-01-01T00:00:00Z",
|
|
|
+ "end_date": "2024-01-31T00:00:00Z",
|
|
|
+ "recovery_enabled": true
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 2.1.3 调整用户积分
|
|
|
+- **路径**: `POST /api/users/{userId}/credits/adjust`
|
|
|
+- **描述**: 调整指定用户的积分余额
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.AdjustUserCredits`
|
|
|
+
|
|
|
+**请求参数**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "amount": 5000,
|
|
|
+ "description": "充值",
|
|
|
+ "type": "refund"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**字段说明**:
|
|
|
+- `amount` (int64, required): 调整金额，正数为充值，负数为扣减
|
|
|
+- `description` (string, required): 调整描述，1-500字符
|
|
|
+- `type` (string, required): 调整类型，可选值：consume(消费), refund(退款), adjustment(调整)
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "user_id": 123,
|
|
|
+ "adjustment_amount": 5000,
|
|
|
+ "new_balance": 90000,
|
|
|
+ "type": "refund",
|
|
|
+ "description": "充值"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 2.2 🔐 API Key 管理
|
|
|
+
|
|
|
+#### 2.2.1 为用户创建 API Key
|
|
|
+- **路径**: `POST /api/users/{userId}/keys`
|
|
|
+- **描述**: 为指定用户生成新的 API Key
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.CreateAPIKey`
|
|
|
+
|
|
|
+**请求参数**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "name": "My API Key",
|
|
|
+ "expires_days": 30
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**字段说明**:
|
|
|
+- `name` (string, required): API Key名称，1-100字符
|
|
|
+- `expires_days` (int, optional): 过期天数，1-3650天，不提供则永不过期
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "id": 456,
|
|
|
+ "user_id": 123,
|
|
|
+ "name": "My API Key",
|
|
|
+ "key_value": "sk-ant-sid01-abc123...",
|
|
|
+ "prefix": "sk-ant-sid01",
|
|
|
+ "status": "active",
|
|
|
+ "expires_at": "2024-01-31T00:00:00Z",
|
|
|
+ "created_at": "2024-01-01T00:00:00Z"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**重要**: `key_value` 字段只在创建时返回一次，请妥善保存
|
|
|
+
|
|
|
+#### 2.2.2 查询用户 API Keys
|
|
|
+- **路径**: `GET /api/users/{userId}/keys`
|
|
|
+- **描述**: 获取指定用户的所有 API Key 列表
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.GetUserAPIKeys`
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": [
|
|
|
+ {
|
|
|
+ "id": 456,
|
|
|
+ "name": "My API Key",
|
|
|
+ "prefix": "sk-ant-sid01",
|
|
|
+ "status": "active",
|
|
|
+ "last_used_at": "2024-01-15T10:30:00Z",
|
|
|
+ "last_used_ip": "192.168.1.100",
|
|
|
+ "expires_at": "2024-01-31T00:00:00Z",
|
|
|
+ "created_at": "2024-01-01T00:00:00Z"
|
|
|
+ }
|
|
|
+ ]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**注意**: 出于安全考虑，不返回完整的 `key_value`
|
|
|
+
|
|
|
+#### 2.2.3 更新 API Key 状态
|
|
|
+- **路径**: `PUT /api/keys/{keyId}/status`
|
|
|
+- **描述**: 更新指定 API Key 的状态（启用/禁用）
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.UpdateAPIKeyStatus`
|
|
|
+
|
|
|
+**请求参数**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "status": "active"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**字段说明**:
|
|
|
+- `status` (string, required): 状态，可选值：active(活跃), inactive(禁用), revoked(已撤销)
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "key_id": 456,
|
|
|
+ "new_status": "active",
|
|
|
+ "updated_at": "2024-01-15T10:30:00Z"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 2.2.4 删除 API Key
|
|
|
+- **路径**: `DELETE /api/keys/{keyId}`
|
|
|
+- **描述**: 删除指定的 API Key
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.DeleteAPIKey`
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "key_id": 456,
|
|
|
+ "deleted": true,
|
|
|
+ "deleted_at": "2024-01-15T10:30:00Z"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 2.3 📊 积分历史和统计
|
|
|
+
|
|
|
+#### 2.3.1 用户积分明细
|
|
|
+- **路径**: `GET /api/users/{userId}/credits/history`
|
|
|
+- **描述**: 获取指定用户的积分使用历史记录
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.GetCreditsHistory`
|
|
|
+
|
|
|
+**查询参数**:
|
|
|
+- `page` (int, optional): 页码，默认1
|
|
|
+- `limit` (int, optional): 每页数量，默认20，最大100
|
|
|
+- `type` (string, optional): 积分类型过滤
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": [
|
|
|
+ {
|
|
|
+ "id": 789,
|
|
|
+ "type": "consume",
|
|
|
+ "amount": -150,
|
|
|
+ "balance_after": 84850,
|
|
|
+ "description": "API调用 - claude-3-sonnet-20240229",
|
|
|
+ "reference_type": "api_usage",
|
|
|
+ "reference_id": "101",
|
|
|
+ "created_at": "2024-01-15T10:30:00Z"
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "pagination": {
|
|
|
+ "page": 1,
|
|
|
+ "limit": 20,
|
|
|
+ "total": 50
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 2.3.2 用户使用统计
|
|
|
+- **路径**: `GET /api/users/{userId}/usage/stats`
|
|
|
+- **描述**: 获取指定用户的API使用统计信息
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.GetUsageStats`
|
|
|
+
|
|
|
+**查询参数**:
|
|
|
+- `days` (int, optional): 统计天数，默认30，最大365
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "total_requests": 150,
|
|
|
+ "total_tokens": 75000,
|
|
|
+ "total_credits_cost": 15000,
|
|
|
+ "average_request_time": 850,
|
|
|
+ "model_usage": {
|
|
|
+ "claude-3-sonnet-20240229": 100,
|
|
|
+ "claude-3-haiku-20240307": 50
|
|
|
+ },
|
|
|
+ "daily_stats": [
|
|
|
+ {
|
|
|
+ "date": "2024-01-15",
|
|
|
+ "requests": 25,
|
|
|
+ "tokens": 12500,
|
|
|
+ "credits_cost": 2500
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 2.4 📈 新增：仪表盘/余额/图表联动接口
|
|
|
+
|
|
|
+#### 2.4.1 仪表盘聚合
|
|
|
+- **路径**: `GET /api/users/{userId}/dashboard`
|
|
|
+- **描述**: 返回“当前订阅/余额卡片 + 今日汇总 + 今日请求列表”
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.GetUserDashboard`
|
|
|
+
|
|
|
+**响应示例**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "subscription": {
|
|
|
+ "user_id": 123,
|
|
|
+ "plan_name": "基础月付",
|
|
|
+ "credit_limit": 5400,
|
|
|
+ "used_credits": 2160,
|
|
|
+ "available_credits": 3240,
|
|
|
+ "credit_recovery_per_hour": 100,
|
|
|
+ "status": "active",
|
|
|
+ "start_date": "2025-08-01T00:00:00Z",
|
|
|
+ "end_date": "2025-09-10T00:00:00Z",
|
|
|
+ "recovery_enabled": true,
|
|
|
+ "last_recharge_at": "2025-08-07T09:00:01Z"
|
|
|
+ },
|
|
|
+ "today_summary": {
|
|
|
+ "requests": 300,
|
|
|
+ "credits_consumed": 4040,
|
|
|
+ "credits_recharged": 800,
|
|
|
+ "since": "2025-08-07T00:00:00+08:00",
|
|
|
+ "until": "2025-08-07T16:30:00+08:00"
|
|
|
+ },
|
|
|
+ "today_requests": [
|
|
|
+ {
|
|
|
+ "id": 10001,
|
|
|
+ "time": "2025-08-07T16:00:00+08:00",
|
|
|
+ "model": "claude-sonnet-4-20250514",
|
|
|
+ "credits_cost": 10,
|
|
|
+ "status": "success",
|
|
|
+ "api_key_id": 555
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**说明**:
|
|
|
+- 今日按自然日统计（`created_at >= CURDATE()`）
|
|
|
+- `last_recharge_at` 来自 `user_credits` 最近 `amount>0` 记录
|
|
|
+
|
|
|
+#### 2.4.2 余额卡片
|
|
|
+- **路径**: `GET /api/users/{userId}/balance`
|
|
|
+- **描述**: 单独返回余额卡片数据
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.GetUserBalance`
|
|
|
+
|
|
|
+**响应示例**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "user_id": 123,
|
|
|
+ "plan_name": "基础月付",
|
|
|
+ "credit_limit": 5400,
|
|
|
+ "used_credits": 2160,
|
|
|
+ "available_credits": 3240,
|
|
|
+ "credit_recovery_per_hour": 100,
|
|
|
+ "status": "active",
|
|
|
+ "start_date": "2025-08-01T00:00:00Z",
|
|
|
+ "end_date": "2025-09-10T00:00:00Z",
|
|
|
+ "last_recharge_at": "2025-08-07T09:00:01Z"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 2.4.3 图表 + 明细联动（每小时聚合）
|
|
|
+- **路径**: `GET /api/users/{userId}/credits/analytics`
|
|
|
+- **描述**: 在时间区间内返回每小时的“使用/补充/净变化”以及同一区间的积分明细（分页）
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.GetCreditsAnalytics`
|
|
|
+
|
|
|
+**查询参数**:
|
|
|
+- `start` (string, required): `YYYY-MM-DD HH:MM:SS`，例如 `2025-08-08 12:00:00`
|
|
|
+- `end` (string, required): `YYYY-MM-DD HH:MM:SS`，需大于 `start`
|
|
|
+- `tz` (string, optional): 时区，默认 `Asia/Shanghai`
|
|
|
+- `page` (int, optional): 明细页码，默认 1
|
|
|
+- `limit` (int, optional): 明细每页数量，默认 20，最大 100
|
|
|
+- `order` (string, optional): `asc|desc`，默认 `desc`
|
|
|
+- `type` (string, optional): 明细类型过滤，`consume|purchase|recovery|refund|reward|adjustment|all`，默认 `all`
|
|
|
+
|
|
|
+**成功返回**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "meta": {
|
|
|
+ "start": "2025-08-08T12:00:00+08:00",
|
|
|
+ "end": "2025-08-09T11:00:00+08:00",
|
|
|
+ "interval": "hour",
|
|
|
+ "timezone": "Asia/Shanghai",
|
|
|
+ "bucket_count": 23
|
|
|
+ },
|
|
|
+ "summary": {
|
|
|
+ "consumed": 1720,
|
|
|
+ "recharged": 1820,
|
|
|
+ "net_change": 100
|
|
|
+ },
|
|
|
+ "series": [
|
|
|
+ {
|
|
|
+ "ts": "2025-08-08T12:00:00+08:00",
|
|
|
+ "consumed": 12,
|
|
|
+ "recharged": 0,
|
|
|
+ "net_change": -12
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "history": {
|
|
|
+ "page": 1,
|
|
|
+ "limit": 20,
|
|
|
+ "total": 73,
|
|
|
+ "records": [
|
|
|
+ {
|
|
|
+ "id": 98765,
|
|
|
+ "time": "2025-08-08T13:12:39+08:00",
|
|
|
+ "type": "consume",
|
|
|
+ "amount": -2,
|
|
|
+ "balance_after": 5398,
|
|
|
+ "description": "使用了2积分 - Model: claude-sonnet-4-20250514 ...",
|
|
|
+ "reference_type": "api_usage",
|
|
|
+ "reference_id": 555
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**图表口径**:
|
|
|
+- 区间 `[start, end)`，按 `tz` 对齐到整点；每小时一个桶，空桶补 0
|
|
|
+- `consumed = SUM(-amount WHERE amount < 0)`
|
|
|
+- `recharged = SUM(amount WHERE amount > 0)`
|
|
|
+- `net_change = recharged - consumed`
|
|
|
+
|
|
|
+**明细口径**:
|
|
|
+- 过滤：`user_id = ? AND created_at >= start AND created_at < end`
|
|
|
+- `type != all` 时，对明细增加 `WHERE type = ?`（不影响图表）
|
|
|
+- 排序/分页：`order` + `page/limit`
|
|
|
+
|
|
|
+**错误码与边界**:
|
|
|
+- 400：缺少 `start/end`、时间格式错误、`end <= start`、跨度超过 90 天
|
|
|
+- 200 且 `series` 全 0：区间内无记录
|
|
|
+- 200 且 `history.total = 0`：区间无明细
|
|
|
+
|
|
|
+**性能与缓存**:
|
|
|
+- 图表聚合启用 Redis 缓存：`analytics:{userId}:{start_unix}:{end_unix}:{tz}`，TTL 60s
|
|
|
+- 明细不缓存（受分页与类型影响），依赖索引 `(user_id, created_at)`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 2.4 🔄 批量查询接口
|
|
|
+
|
|
|
+#### 2.4.1 批量查询用户状态
|
|
|
+- **路径**: `POST /api/users/batch-status`
|
|
|
+- **描述**: 批量查询多个用户的状态信息，专为Java系统优化
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.BatchUserStatus`
|
|
|
+
|
|
|
+**请求参数**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "user_ids": [123, 456, 789]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**字段说明**:
|
|
|
+- `user_ids` (array[int64], required): 用户ID列表，最多100个
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": [
|
|
|
+ {
|
|
|
+ "user_id": 123,
|
|
|
+ "plan_status": "active",
|
|
|
+ "credit_limit": 100000,
|
|
|
+ "used_credits": 15000,
|
|
|
+ "available_credits": 85000,
|
|
|
+ "api_keys_count": 2,
|
|
|
+ "last_activity": "2024-01-15T10:30:00Z"
|
|
|
+ }
|
|
|
+ ]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 2.5 🔥 缓存管理接口
|
|
|
+
|
|
|
+#### 2.5.1 用户缓存失效
|
|
|
+- **路径**: `POST /api/cache/invalidate/user/{userId}`
|
|
|
+- **描述**: 使指定用户的缓存失效，Java系统调用
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.InvalidateUserCache`
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "user_id": 123,
|
|
|
+ "cleared": ["auth_cache", "credit_cache"],
|
|
|
+ "message": "用户缓存清理成功"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 2.5.2 API Key缓存失效
|
|
|
+- **路径**: `POST /api/cache/invalidate/apikey`
|
|
|
+- **描述**: 使API Key相关缓存失效
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.InvalidateAPIKeyCache`
|
|
|
+
|
|
|
+**请求参数**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "api_key": "sk-ant-sid01-abc123..."
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**字段说明**:
|
|
|
+- `api_key` (string, required): 需要清理缓存的API Key，32-128字符
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "api_key_prefix": "sk-ant-sid01-abc1...",
|
|
|
+ "message": "API Key缓存清理成功"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 2.5.3 缓存统计信息
|
|
|
+- **路径**: `GET /api/cache/stats`
|
|
|
+- **描述**: 获取系统缓存的统计信息
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.GetCacheStats`
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "cache_type": "multi_level",
|
|
|
+ "l1_cache": "memory_auth_cache",
|
|
|
+ "l2_cache": "redis_credit_cache",
|
|
|
+ "features": [
|
|
|
+ "redis_pubsub_invalidation",
|
|
|
+ "auto_expiration",
|
|
|
+ "cache_penetration_protection"
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 2.6 🖥️ 系统管理接口
|
|
|
+
|
|
|
+#### 2.6.1 积分恢复状态
|
|
|
+- **路径**: `GET /api/system/recovery/status`
|
|
|
+- **描述**: 查询系统积分恢复的状态信息（内部调用）
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.GetSystemRecoveryStatus`
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "pending_recovery_users": 10,
|
|
|
+ "last_recovery_at": "2024-01-15T00:00:00Z",
|
|
|
+ "next_recovery_at": "2024-01-16T00:00:00Z",
|
|
|
+ "system_status": "healthy"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 2.6.2 手动触发积分恢复 🆕
|
|
|
+- **路径**: `POST /api/system/recovery/trigger`
|
|
|
+- **描述**: 手动触发积分恢复任务（管理员接口）
|
|
|
+- **认证**: 需要管理员 API Key
|
|
|
+- **控制器**: `AdminController.TriggerCreditRecovery`
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "data": {
|
|
|
+ "message": "积分恢复执行成功",
|
|
|
+ "recovered_users": 5,
|
|
|
+ "trigger_by": "admin"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**功能说明**:
|
|
|
+- 立即执行积分恢复任务，无需等待定时任务
|
|
|
+- 返回实际恢复的用户数量
|
|
|
+- 适用于紧急情况或测试场景
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 3. 健康检查路由
|
|
|
+
|
|
|
+### 3.1 健康检查
|
|
|
+- **路径**: `GET /health`
|
|
|
+- **描述**: 系统健康检查端点，用于监控服务状态
|
|
|
+- **认证**: 无需认证
|
|
|
+- **控制器**: `controller.Health`
|
|
|
+
|
|
|
+**响应格式**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "message": "服务正常运行",
|
|
|
+ "data": {
|
|
|
+ "status": "healthy",
|
|
|
+ "timestamp": "2024-01-15 10:30:00"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 错误码说明
|
|
|
+
|
|
|
+### HTTP状态码
|
|
|
+- `200` - 请求成功
|
|
|
+- `400` - 请求参数错误
|
|
|
+- `401` - 认证失败
|
|
|
+- `403` - 权限不足
|
|
|
+- `404` - 资源不存在
|
|
|
+- `500` - 服务器内部错误
|
|
|
+
|
|
|
+### 业务错误类型
|
|
|
+- `authentication_error` - 认证错误
|
|
|
+- `invalid_request_error` - 请求参数错误
|
|
|
+- `api_error` - API调用错误
|
|
|
+- `insufficient_credits` - 积分不足
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 中间件说明
|
|
|
+
|
|
|
+1. **PanicRecover**: Panic恢复中间件，确保服务稳定性
|
|
|
+2. **CORS**: 跨域资源共享中间件
|
|
|
+3. **RequestLogger**: 请求日志记录中间件
|
|
|
+4. **ErrorHandler**: 统一错误处理中间件
|
|
|
+5. **FastAPIKeyAuth**: 高性能API Key认证（用于Claude API路由）
|
|
|
+6. **AdminAPIAuth**: 管理员API Key认证（用于管理API路由）
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 技术栈与特性
|
|
|
+
|
|
|
+### 核心技术
|
|
|
+- **框架**: GoFrame (gf/v2)
|
|
|
+- **路由**: ghttp.Server
|
|
|
+- **架构**: 分层架构（Controller-Service-DAO）
|
|
|
+- **缓存**: Redis + 内存双级缓存
|
|
|
+- **数据库**: MySQL/PostgreSQL
|
|
|
+
|
|
|
+### 主要特性
|
|
|
+- **高性能转发**: 三级缓存机制，毫秒级响应
|
|
|
+- **积分管理系统**: 自动积分恢复，精确计费
|
|
|
+- **统一管理架构**: AdminController统一管理所有管理功能
|
|
|
+- **安全认证**: 双重API Key认证机制
|
|
|
+- **实时监控**: 完整的使用统计和健康检查
|
|
|
+- **批量操作**: 优化的批量查询接口
|
|
|
+
|
|
|
+### 性能优化
|
|
|
+- **缓存策略**: 多级缓存避免数据库压力
|
|
|
+- **异步处理**: 计费和统计异步处理
|
|
|
+- **连接池**: 数据库连接池优化
|
|
|
+- **流式支持**: 支持Claude API流式响应
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 更新日志
|
|
|
+
|
|
|
+### v2.0 主要更新
|
|
|
+1. **统一控制器架构**: 采用AdminController统一管理所有管理API
|
|
|
+2. **新增接口**: 手动触发积分恢复功能 (`POST /api/system/recovery/trigger`)
|
|
|
+3. **响应格式优化**: 统一的分页和错误响应格式
|
|
|
+4. **代码结构重构**: 更清晰的模块化设计和注释
|
|
|
+5. **功能增强**: 积分恢复系统初始化优化
|
zoujiajian