# 计费与资源平面对接文档

> **版本**: v1.0.0  
> **更新时间**: 2026-01-10  
> **适用角色**: 租户用户（user）  
> **说明**: 本文档描述后端提供给前端的计费仪表板数据接口规格

---

## 目录

1. [接口概述](#接口概述)
2. [接口详细说明](#接口详细说明)
3. [数据结构定义](#数据结构定义)
4. [错误码说明](#错误码说明)
5. [调用示例](#调用示例)
6. [FAQ](#faq)

---

## 接口概述

### 业务功能

计费与资源仪表板接口为租户用户提供完整的费用和资源使用情况数据，包括：

- **本月费用统计** - 当前消费金额、EU消费量、平均每日费用、预测月底费用
- **趋势分析** - 与上月对比的消费变化百分比和趋势方向
- **余额查询** - EU余额、现金余额实时数据
- **历史数据** - 最近30天按日期聚合的EU消费时间序列数据
- **费用分类** - 按服务类型（平台Agent、自定义Agent、模型API）分类的费用明细
- **资源使用** - CPU、内存、存储、API调用次数的配额和使用情况

### 数据来源

接口数据来自以下数据库表，后端自动聚合：

| 数据表 | 用途 | 关键字段 |
|--------|------|----------|
| `billing_records` | Agent计费记录 | `tenant_id`, `timestamp`, `cost`, `eu` |
| `model_billing_records` | 模型调用计费记录 | `tenant_id`, `created_at`, `total_cost`, `eu_consumed` |
| `balances` | 用户余额 | `user_id`, `eu_balance`, `cash_balance` |
| `tenant_custom_agent_quotas` | 资源配额 | `tenant_id`, `cpu_quota`, `memory_quota`, `cpu_used`, `memory_used` |

### 技术特性

- **数据一致性**：同时查询多个数据源并聚合，确保数据准确性
- **实时计算**：动态计算平均每日费用、预测值、百分比等派生指标
- **性能优化**：使用数据库聚合函数，减少查询次数
- **缓存建议**：前端可缓存5分钟，减少服务器压力

---

## 接口详细说明

### 接口基本信息

**接口名称**：计费仪表板综合数据查询

**接口路径**：`GET /api/user/dashboard/billing-overview`

**接口说明**：一次性返回用户的所有计费和资源使用相关数据，包括本月/上月消费、历史数据、费用分类、资源配额等

**认证方式**：Bearer Token (JWT)

**权限要求**：租户用户（user角色）

**请求方法**：GET

**内容类型**：application/json

---

### 请求参数

无需请求参数，接口根据JWT token中的用户ID自动查询该用户的数据。

---

### 请求示例

**cURL**

```bash
curl -X GET "http://localhost:8002/api/user/dashboard/billing-overview" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"
```

**HTTPie**

```bash
http GET http://localhost:8002/api/user/dashboard/billing-overview \
  Authorization:"Bearer YOUR_TOKEN_HERE"
```

---

### 响应格式

**成功响应**（HTTP 200）

```json
{
  "success": true,
  "message": "成功获取仪表板数据",
  "data": {
    "currentMonth": {
      "spent": 1250.50,
      "euConsumed": 12505.0,
      "avgDailySpent": 125.05,
      "predictedTotal": 3876.55,
      "daysElapsed": 10,
      "totalDays": 31,
      "currency": "CNY"
    },
    "lastMonth": {
      "spent": 1000.00,
      "euConsumed": 10000.0
    },
    "comparison": {
      "percentage": 25.1,
      "direction": "up"
    },
    "balance": {
      "eu": 50000.0,
      "cash": 5000.00
    },
    "euHistory": [
      {
        "date": "2026-01-01",
        "euConsumed": 1200.5,
        "cost": 120.05,
        "calls": 150
      },
      {
        "date": "2026-01-02",
        "euConsumed": 1350.0,
        "cost": 135.00,
        "calls": 180
      }
    ],
    "costBreakdown": {
      "categories": [
        {
          "category": "platform_agent",
          "name": "平台Agent",
          "cost": 450.50,
          "percentage": 36.0
        },
        {
          "category": "custom_agent",
          "name": "自定义Agent",
          "cost": 350.00,
          "percentage": 28.0
        },
        {
          "category": "model_api",
          "name": "模型API",
          "cost": 400.00,
          "percentage": 32.0
        },
        {
          "category": "other",
          "name": "其他",
          "cost": 50.00,
          "percentage": 4.0
        }
      ],
      "total": 1250.50
    },
    "resourceUsage": {
      "resources": [
        {
          "type": "cpu",
          "name": "CPU",
          "used": 2.5,
          "limit": 10.0,
          "unit": "核",
          "percentage": 25.0
        },
        {
          "type": "memory",
          "name": "内存",
          "used": 5.0,
          "limit": 20.0,
          "unit": "GB",
          "percentage": 25.0
        },
        {
          "type": "storage",
          "name": "存储",
          "used": 100,
          "limit": 1000,
          "unit": "GB",
          "percentage": 10.0
        },
        {
          "type": "api_calls",
          "name": "API调用",
          "used": 15000,
          "limit": 100000,
          "unit": "次",
          "percentage": 15.0
        }
      ]
    },
    "metadata": {
      "timestamp": "2026-01-10T12:30:45.123456",
      "userId": "b00a7b8e-9e8b-463d-9593-a3b4d0006778"
    }
  }
}
**失败响应**（HTTP 4xx/5xx）

```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "未提供有效的认证令牌"
  }
}
```