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

仪表板接口文档

接口概述

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

接口详情

获取仪表板数据

接口地址： GET /api/v1/admin/dashboard

接口描述： 获取管理后台仪表板的统计数据、最近活动和系统信息

请求方式： GET

认证方式： Bearer Token

请求头

Authorization: Bearer {token}
Content-Type: application/json

请求参数

无

响应格式

成功响应 (200)

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

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

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：

curl -X POST http://localhost:3200/api/v1/admin/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

2. 使用token访问仪表板接口：

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. 系统信息包含服务器运行状态和环境信息