# 仪表盘 API 文档

基础路径：`/v2/dashboard`

所有接口响应均由全局 `R<T>` 包装，实际返回格式为：

```json
{
  "code": 200,
  "message": "success",
  "data": { ... },
  "success": true,
  "timestamp": 1710230400000
}
```

以下文档中 **响应示例** 均为 `data` 字段内的内容。

---

## 1. 今日数据总览

获取今日核心运营指标，每项指标包含今日值、昨日值及环比变化率。

**请求**

```
GET /v2/dashboard/today-overview
```

**请求参数**：无

**响应字段**

| 字段 | 类型 | 说明 |
|---|---|---|
| `newUsers` | `MetricItemVO` | 今日新增用户 |
| `rechargePoints` | `MetricItemVO` | 今日充值积分（新增积分总量） |
| `consumedPoints` | `MetricItemVO` | 今日消耗积分（用户使用消耗） |
| `newVipCount` | `MetricItemVO` | 今日新增 VIP 人数 |

**MetricItemVO 结构**

| 字段 | 类型 | 说明 |
|---|---|---|
| `today` | `Long` | 今日数值 |
| `yesterday` | `Long` | 昨日数值 |
| `changeRate` | `BigDecimal` | 环比变化率（%），正数增长，负数下降；昨日为 0 时：今日 > 0 则为 100，否则为 null |

**响应示例**

```json
{
  "newUsers": {
    "today": 128,
    "yesterday": 95,
    "changeRate": 34.74
  },
  "rechargePoints": {
    "today": 56000,
    "yesterday": 42000,
    "changeRate": 33.33
  },
  "consumedPoints": {
    "today": 38500,
    "yesterday": 41000,
    "changeRate": -6.10
  },
  "newVipCount": {
    "today": 12,
    "yesterday": 8,
    "changeRate": 50.00
  }
}
```

---

## 2. 任务状态概览

获取当前系统内所有订单任务按状态分组的数量统计。

**请求**

```
GET /v2/dashboard/task-overview
```

**请求参数**：无

**响应字段**（数组）

| 字段 | 类型 | 说明 |
|---|---|---|
| `taskStatus` | `Integer` | 任务状态值，`null` 表示待处理 |
| `statusLabel` | `String` | 状态中文描述 |
| `count` | `Long` | 该状态的任务数量 |

**任务状态枚举**

| taskStatus | statusLabel | 说明 |
|---|---|---|
| `null` | 待处理 | 尚未开始处理的订单 |
| `0` | 异常失败 | 任务异常中断 |
| `1` | 任务执行中 | 正在处理中 |
| `2` | 执行完成 | 任务成功完成 |
| `3` | 执行失败 | 任务执行后失败 |

**响应示例**

```json
[
  {
    "taskStatus": null,
    "statusLabel": "待处理",
    "count": 15
  },
  {
    "taskStatus": 0,
    "statusLabel": "异常失败",
    "count": 3
  },
  {
    "taskStatus": 1,
    "statusLabel": "任务执行中",
    "count": 28
  },
  {
    "taskStatus": 2,
    "statusLabel": "执行完成",
    "count": 1520
  },
  {
    "taskStatus": 3,
    "statusLabel": "执行失败",
    "count": 12
  }
]
```

---

## 3. 趋势数据

按周（近 7 天）或月（近 30 天）维度获取每日新增用户和新增 VIP 数据，适配折线图 / 柱状图展示。无数据的日期自动补 0。

**请求**

```
GET /v2/dashboard/trend?type=week
```

**请求参数**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `type` | `String` | 否 | `week` | 时间维度：`week`（近 7 天）/ `month`（近 30 天） |

**响应字段**（数组）

| 字段 | 类型 | 说明 |
|---|---|---|
| `date` | `String` | 日期，格式 `yyyy-MM-dd` |
| `newUsers` | `Long` | 当日新增用户数 |
| `newVipCount` | `Long` | 当日新增 VIP 人数 |

**响应示例**（`type=week`）

```json
[
  { "date": "2026-03-06", "newUsers": 82,  "newVipCount": 5  },
  { "date": "2026-03-07", "newUsers": 95,  "newVipCount": 7  },
  { "date": "2026-03-08", "newUsers": 110, "newVipCount": 4  },
  { "date": "2026-03-09", "newUsers": 78,  "newVipCount": 6  },
  { "date": "2026-03-10", "newUsers": 130, "newVipCount": 11 },
  { "date": "2026-03-11", "newUsers": 105, "newVipCount": 8  },
  { "date": "2026-03-12", "newUsers": 42,  "newVipCount": 3  }
]
```

---

## 4. 系统数据概览

获取系统整体累计数据，包括总用户、总模版、任务完成情况及会员用户数。

**请求**

```
GET /v2/dashboard/system-overview
```

**请求参数**：无

**响应字段**

| 字段 | 类型 | 说明 |
|---|---|---|
| `totalUsers` | `Long` | 总用户数 |
| `totalTemplates` | `Long` | 总模版数（未删除） |
| `completedTasks` | `Long` | 已完成任务数（task_status = 2） |
| `failedTasks` | `Long` | 失败任务数（task_status = 0 或 3） |
| `vipUsers` | `Long` | 当前会员用户数（is_vip = 1） |

**响应示例**

```json
{
  "totalUsers": 25680,
  "totalTemplates": 134,
  "completedTasks": 189432,
  "failedTasks": 1256,
  "vipUsers": 3842
}
```

---

## 5. 进行中任务数

获取当前系统中正在执行的任务数量（task_status = 1），可用于实时监控任务队列。

**请求**

```
GET /v2/dashboard/running-tasks
```

**请求参数**：无

**响应字段**

直接返回 `Long` 类型数值。

**响应示例**

```json
{
  "code": 200,
  "message": "success",
  "data": 28,
  "success": true,
  "timestamp": 1710230400000
}
```

---

## 接口总览

| # | 方法 | 路径 | 说明 | 用途 |
|---|---|---|---|---|
| 1 | GET | `/v2/dashboard/today-overview` | 今日数据总览 | 仪表盘顶部统计卡片，展示今日与昨日对比 |
| 2 | GET | `/v2/dashboard/task-overview` | 任务状态概览 | 饼图 / 环形图，展示各状态任务分布 |
| 3 | GET | `/v2/dashboard/trend?type=week\|month` | 趋势数据 | 折线图 / 柱状图，展示用户和 VIP 增长趋势 |
| 4 | GET | `/v2/dashboard/system-overview` | 系统数据概览 | 仪表盘底部统计卡片，展示系统累计数据 |
| 5 | GET | `/v2/dashboard/running-tasks` | 进行中任务数 | 实时监控当前执行中的任务数量 |