jiebanke/docs/仪表板接口文档.md

# 仪表板接口文档

## 接口概述
本文档描述了管理后台仪表板数据获取接口的详细信息。

## 接口详情

### 获取仪表板数据

**接口地址：** `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. 系统信息包含服务器运行状态和环境信息