---
url: /docs/api-docs/v1/admin/dashboard.md
---
# dashboard — 仪表盘（5 action）

> 前缀：`/api/v1/admin/dashboard/`
> 权限：全部 `DASHBOARD_READ`（三角色共享）
> 代码：`src/app/admin/interface/api/dashboard_v1.py` + `application/usecase/dashboard_stats.py`

## 3.2.1 overview —— 总览

`GET /api/v1/admin/dashboard/overview?range=day`

**Query 参数**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `range` | string | ⬜ | `day` | `day` | `week` | `month` |

**响应 data**（⚠️ snake\_case 新字段 + camelCase P0 存量字段混合）：

| 字段 | 类型 | 说明 |
|---|---|---|
| `range` | string | 回显口径 |
| `total_users` | int | 全量用户数 |
| `active_users` | int | 活跃用户数 |
| `total_orders` | int | 订单总数 |
| `total_revenue` | float | 累计营收 |
| `anomaly_count` | int | 异常数 |
| `totalAdmins` | int | **P0 存量**：admin 账号总数 |
| `activeAdmins` | int | **P0 存量**：活跃 admin 数 |
| `roleDistribution` | object | **P0 存量**：`{super: n, operator: n, it: n}` |
| `recentLogins24h` | int | **P0 存量**：24h 内登录次数 |
| `pendingAudits` | int | **P0 存量**：待审数 |

**错误码**：`40201001` 非法 range。

> 注：P0 版本 `/overview` 被本 v1 superset 覆盖（同路径，注册顺序优先），存量字段合并返回。

## 3.2.2 user-growth —— 用户增长曲线

`GET /api/v1/admin/dashboard/user-growth?range=day&granularity=day`

**Query 参数**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `range` | string | ⬜ | `day` | 时间范围 |
| `granularity` | string | ⬜ | `day` | `day` | `hour` |

**响应 data**：`{ "range": ..., "granularity": ..., "series": [ {时间点, 新增数…} ] }`

**错误码**：`40201001` 非法 range / granularity。

## 3.2.3 order-stats —— 订单统计

`GET /api/v1/admin/dashboard/order-stats?range=day`

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `range` | string | 回显口径 |
| `total` | int | 订单总数 |
| `paid` | int | 已支付数 |
| `refunded` | int | 已退款数 |
| `closed` | int | 已关闭数 |
| `series` | array | 时间序列 |

**错误码**：`40201001` 非法 range。

## 3.2.4 revenue —— 营收统计

`GET /api/v1/admin/dashboard/revenue?range=day`

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `range` | string | 回显口径 |
| `gross_revenue` | float | 毛营收 |
| `net_revenue` | float | 净营收（扣退款） |
| `refund_amount` | float | 退款总额 |
| `by_channel` | array | 按支付渠道拆分 |

**错误码**：`40201001` 非法 range。

## 3.2.5 anomalies —— 异常清单

`GET /api/v1/admin/dashboard/anomalies?severity=high`

**Query 参数**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `severity` | string | ⬜ | `high` | `low` | `medium` | `high` |

**响应 data**：`{ "severity": ..., "anomalies": [ {severity, …} ] }`

**错误码**：`40201001` 非法 severity。

***

**通用失败**：未登录 → 401 + `40201002`；权限不足 → 403 + `40201004`（三角色均持有 `DASHBOARD_READ`，正常不会触发）。