# 用户 AI 用量每日统计接口

## 接口信息

- 接口地址：`GET /manager/statistics/get/aiUsageData`
- 用途：查询用户 AI 用量的每日统计列表
- 数据来源：`daily_usage_statistics_record`
- 默认排序：按 `usageDate` 倒序
- 返回类型：分页列表

## 请求参数

该接口使用 Bean Searcher 查询参数，支持分页和按返回字段筛选。

### 分页参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `start` | number | 否 | `1` | 页码，从 1 开始 |
| `limit` | number | 否 | `10` | 每页条数 |

### 常用筛选参数

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `type` | string | 否 | AI 类型 |
| `usageDate` | string | 否 | 使用日期，精确匹配 |
| `usageDate-op` | string | 否 | `usageDate` 的查询操作符，例如 `bt` 表示区间查询 |
| `usageDate-0` | string | 否 | 区间开始日期，配合 `usageDate-op=bt` 使用 |
| `usageDate-1` | string | 否 | 区间结束日期，配合 `usageDate-op=bt` 使用 |

可筛选字段与返回记录字段一致：`id`、`createdTime`、`updateTime`、`type`、`usageDate`、`userCount`、`dailyLimitTotal`、`usageUserCount`、`usedUsd`、`requestCount`。

## 请求示例

```http
GET /manager/statistics/get/aiUsageData?start=1&limit=10&type=codex
```

按日期区间查询：

```http
GET /manager/statistics/get/aiUsageData?start=1&limit=10&usageDate-op=bt&usageDate-0=2026-05-01&usageDate-1=2026-05-13
```

## 响应字段

### 外层结构

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `code` | number | 状态码 |
| `msg` | string | 状态描述 |
| `flag` | boolean | 是否成功 |
| `data` | object | 查询结果 |

### `data`

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `totalCount` | number | 总记录数 |
| `dataList` | array | 当前页数据 |
| `summaries` | array | 汇总数据；当前接口未配置汇总时通常为空数组 |

### `data.dataList[]`

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `id` | number | 记录 ID |
| `createdTime` | string | 创建时间 |
| `updateTime` | string | 更新时间 |
| `type` | string | AI 类型 |
| `usageDate` | string | 统计日期 |
| `userCount` | number | 用户总数 |
| `dailyLimitTotal` | number | 当日可用额度合计 |
| `usageUserCount` | number | 当日使用用户数 |
| `usedUsd` | number | 当日用量，单位 USD |
| `requestCount` | number | 请求次数 |

## 响应示例

```json
{
  "code": 200,
  "msg": "success",
  "flag": true,
  "data": {
    "totalCount": 1,
    "dataList": [
      {
        "id": 1,
        "createdTime": "2026-05-13 00:00:00",
        "updateTime": "2026-05-13 00:00:00",
        "type": "codex",
        "usageDate": "2026-05-13 00:00:00",
        "userCount": 100,
        "dailyLimitTotal": 500.00,
        "usageUserCount": 80,
        "usedUsd": 123.45,
        "requestCount": 300
      }
    ],
    "summaries": []
  }
}
```

## 前端对接备注

- 列表默认已按 `usageDate` 倒序，前端不传排序参数即可。
- `start` 是页码，不是偏移量。
- 金额/用量字段建议按数字处理，展示时再格式化小数位。
- 日期字段由后端 `Date` 序列化输出，实际格式以当前项目 Jackson 配置为准。
