aitori-bi-v2/docs/dashboard-api.md

仪表盘 API 文档

基础路径：/v2/dashboard

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

{
  "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

响应示例

{
  "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	执行失败	任务执行后失败

响应示例

[
  {
    "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）

[
  { "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）

响应示例

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

---

5. 进行中任务数

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

请求

GET /v2/dashboard/running-tasks

请求参数：无

响应字段

直接返回 Long 类型数值。

响应示例

{
  "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	进行中任务数	实时监控当前执行中的任务数量