重构后端API和配置，新增仪表板数据接口并优化本地开发环境配置
This commit is contained in:
ylweng
248
docs/仪表板接口文档.md
Normal file
248
docs/仪表板接口文档.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# 仪表板接口文档
|
||||
|
||||
## 接口概述
|
||||
本文档描述了管理后台仪表板数据获取接口的详细信息。
|
||||
|
||||
## 接口详情
|
||||
|
||||
### 获取仪表板数据
|
||||
|
||||
**接口地址：** `GET /api/v1/admin/dashboard`
|
||||
|
||||
**接口描述：** 获取管理后台仪表板的统计数据、最近活动和系统信息
|
||||
|
||||
**请求方式：** GET
|
||||
|
||||
**认证方式：** Bearer Token
|
||||
|
||||
#### 请求头
|
||||
```
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
#### 请求参数
|
||||
无
|
||||
|
||||
#### 响应格式
|
||||
|
||||
**成功响应 (200)**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"message": "获取成功",
|
||||
"data": {
|
||||
"statistics": {
|
||||
"totalUsers": 0,
|
||||
"totalAnimals": 0,
|
||||
"totalTravels": 0,
|
||||
"totalClaims": 0,
|
||||
"todayNewUsers": 0,
|
||||
"todayNewAnimals": 0,
|
||||
"todayNewTravels": 0,
|
||||
"todayNewClaims": 0
|
||||
},
|
||||
"recentActivities": [],
|
||||
"systemInfo": {
|
||||
"serverTime": "2025-09-21T14:58:00.554Z",
|
||||
"uptime": "0小时0分钟",
|
||||
"version": "1.0.0",
|
||||
"environment": "development"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应 (401)**
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"code": 401,
|
||||
"message": "无效的认证token"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应字段说明
|
||||
|
||||
##### statistics 统计数据
|
||||
| 字段名 | 类型 | 描述 |
|
||||
|--------|------|------|
|
||||
| totalUsers | number | 用户总数 |
|
||||
| totalAnimals | number | 动物总数 |
|
||||
| totalTravels | number | 旅行总数 |
|
||||
| totalClaims | number | 认领总数 |
|
||||
| todayNewUsers | number | 今日新增用户数 |
|
||||
| todayNewAnimals | number | 今日新增动物数 |
|
||||
| todayNewTravels | number | 今日新增旅行数 |
|
||||
| todayNewClaims | number | 今日新增认领数 |
|
||||
|
||||
##### recentActivities 最近活动
|
||||
| 字段名 | 类型 | 描述 |
|
||||
|--------|------|------|
|
||||
| id | number | 活动ID |
|
||||
| type | string | 活动类型 |
|
||||
| description | string | 活动描述 |
|
||||
| user | object | 相关用户信息 |
|
||||
| timestamp | string | 活动时间 |
|
||||
|
||||
##### systemInfo 系统信息
|
||||
| 字段名 | 类型 | 描述 |
|
||||
|--------|------|------|
|
||||
| serverTime | string | 服务器当前时间 |
|
||||
| uptime | string | 服务器运行时间 |
|
||||
| version | string | 系统版本 |
|
||||
| environment | string | 运行环境 |
|
||||
|
||||
#### 错误码说明
|
||||
| 错误码 | 描述 |
|
||||
|--------|------|
|
||||
| 401 | 未授权，token无效或已过期 |
|
||||
| 403 | 权限不足 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
## OpenAPI 3.0 规范
|
||||
|
||||
```yaml
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: 仪表板接口
|
||||
version: 1.0.0
|
||||
description: 管理后台仪表板数据接口
|
||||
|
||||
paths:
|
||||
/api/v1/admin/dashboard:
|
||||
get:
|
||||
summary: 获取仪表板数据
|
||||
tags:
|
||||
- Admin Dashboard
|
||||
security:
|
||||
- bearerAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: 获取成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
example: true
|
||||
code:
|
||||
type: integer
|
||||
example: 200
|
||||
message:
|
||||
type: string
|
||||
example: "获取成功"
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
statistics:
|
||||
type: object
|
||||
properties:
|
||||
totalUsers:
|
||||
type: integer
|
||||
description: 用户总数
|
||||
totalAnimals:
|
||||
type: integer
|
||||
description: 动物总数
|
||||
totalTravels:
|
||||
type: integer
|
||||
description: 旅行总数
|
||||
totalClaims:
|
||||
type: integer
|
||||
description: 认领总数
|
||||
todayNewUsers:
|
||||
type: integer
|
||||
description: 今日新增用户数
|
||||
todayNewAnimals:
|
||||
type: integer
|
||||
description: 今日新增动物数
|
||||
todayNewTravels:
|
||||
type: integer
|
||||
description: 今日新增旅行数
|
||||
todayNewClaims:
|
||||
type: integer
|
||||
description: 今日新增认领数
|
||||
recentActivities:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
type:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
user:
|
||||
type: object
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
systemInfo:
|
||||
type: object
|
||||
properties:
|
||||
serverTime:
|
||||
type: string
|
||||
format: date-time
|
||||
uptime:
|
||||
type: string
|
||||
version:
|
||||
type: string
|
||||
environment:
|
||||
type: string
|
||||
'401':
|
||||
description: 未授权
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
example: false
|
||||
code:
|
||||
type: integer
|
||||
example: 401
|
||||
message:
|
||||
type: string
|
||||
example: "无效的认证token"
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
```
|
||||
|
||||
## 测试示例
|
||||
|
||||
### 使用 curl 测试
|
||||
|
||||
1. 首先登录获取token：
|
||||
```bash
|
||||
curl -X POST http://localhost:3200/api/v1/admin/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin123"}'
|
||||
```
|
||||
|
||||
2. 使用token访问仪表板接口：
|
||||
```bash
|
||||
curl -X GET http://localhost:3200/api/v1/admin/dashboard \
|
||||
-H "Authorization: Bearer {your_token_here}"
|
||||
```
|
||||
|
||||
### 默认管理员账户
|
||||
- 用户名：admin
|
||||
- 密码：admin123
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. 所有请求必须携带有效的JWT token
|
||||
2. token有效期为24小时
|
||||
3. 统计数据实时计算，可能会有轻微延迟
|
||||
4. 最近活动默认显示最新的10条记录
|
||||
5. 系统信息包含服务器运行状态和环境信息
|
||||
Reference in New Issue
Block a user