aiotagro/jiebanke

Fork 0

Files

aiotagro 98f81840f2 重构认证系统和订单支付功能，新增邮箱验证、密码重置及支付流程

2025-09-22 15:28:18 +08:00

37 KiB

Raw Blame History

管理后台接口设计文档

1. 概述

1.1 项目简介

本文档详细描述了结伴客管理后台系统的所有API接口设计，包括用户管理、旅行管理、动物认领管理、订单管理、系统管理等模块的接口规范。

1.2 接口设计原则

RESTful风格：遵循REST架构风格
统一响应格式：所有接口采用统一的响应格式
版本控制：支持API版本管理
安全认证：JWT Token认证机制
错误处理：统一的错误码和错误信息

1.3 技术规范

协议：HTTPS
数据格式：JSON
字符编码：UTF-8
认证方式：JWT Bearer Token
API版本：v1
基础URL：http://localhost:3000/api/v1

1.4 API模块概览

模块	描述	接口数量	状态
认证授权	管理员登录、权限验证	5	✅
用户管理	用户CRUD、状态管理	8	✅
商户管理	商户信息管理	7	✅
旅行管理	旅行活动管理	8	✅
动物管理	动物认领管理	12	✅
订单管理	订单处理、状态跟踪	15	✅
花卉管理	花卉商品管理	9	✅
促销活动	促销活动和奖励管理	10	✅
系统管理	系统配置、监控	12	✅
仪表板	数据统计、图表	6	✅
权限管理	角色权限管理	8	✅

2. 通用规范

2.1 请求格式

2.1.1 请求头

Content-Type: application/json
Authorization: Bearer <JWT_TOKEN>
Accept: application/json
User-Agent: JieBanKe-Admin/1.0.0

2.1.2 请求参数

路径参数：用于资源标识，如 /api/v1/users/{id}
查询参数：用于过滤、排序、分页等，如 ?page=1&size=20&sort=created_at:desc
请求体：JSON格式的数据

2.2 响应格式

2.2.1 成功响应

{
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}

2.2.2 分页响应

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      // 数据列表
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "pages": 5
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}

2.2.3 错误响应

{
  "code": 400,
  "message": "请求参数错误",
  "error": {
    "type": "VALIDATION_ERROR",
    "details": [
      {
        "field": "email",
        "message": "邮箱格式不正确"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}

2.3 状态码规范

状态码	说明	使用场景
200	成功	请求成功处理
201	创建成功	资源创建成功
204	无内容	删除成功或更新成功无返回内容
400	请求错误	参数错误、格式错误
401	未授权	未登录或token无效
403	禁止访问	权限不足
404	资源不存在	请求的资源不存在
409	冲突	资源冲突，如用户名已存在
422	实体错误	业务逻辑错误
500	服务器错误	内部服务器错误

2.4 分页参数

参数名	类型	默认值	说明
page	integer	1	页码，从1开始
size	integer	20	每页数量，最大100
sort	string	created_at:desc	排序字段和方向

2.5 排序参数格式

单字段排序：sort=created_at:desc
多字段排序：sort=status:asc,created_at:desc
支持的排序方向：asc（升序）、desc（降序）

3. 认证授权接口

3.1 管理员登录

接口信息

接口路径：POST /api/v1/admin/login
接口描述：管理员登录获取访问令牌
是否需要认证：否

请求参数

{
  "username": "admin",
  "password": "password123"
}

参数名	类型	必填	说明
username	string	是	用户名
password	string	是	密码

响应示例

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200,
    "admin": {
      "id": 1,
      "username": "admin",
      "name": "系统管理员",
      "email": "admin@example.com",
      "role": "super_admin",
      "permissions": ["user:read", "user:write", "system:manage"]
    }
  }
}

3.2 刷新令牌

接口信息

接口路径：POST /api/v1/admin/refresh
接口描述：刷新访问令牌
是否需要认证：是

响应示例

{
  "code": 200,
  "message": "令牌刷新成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200
  }
}

3.3 退出登录

接口信息

接口路径：POST /api/v1/admin/logout
接口描述：管理员退出登录
是否需要认证：是

响应示例

{
  "code": 200,
  "message": "退出成功"
}

3.4 获取当前用户信息

接口信息

接口路径：GET /api/v1/admin/profile
接口描述：获取当前登录管理员信息
是否需要认证：是

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "admin",
    "name": "系统管理员",
    "email": "admin@example.com",
    "role": "super_admin",
    "permissions": ["user:read", "user:write", "system:manage"],
    "last_login": "2024-01-15T10:30:00Z"
  }
}

3.5 修改密码

接口信息

接口路径：PUT /api/v1/admin/password
接口描述：修改管理员密码
是否需要认证：是

请求参数

{
  "old_password": "oldpassword123",
  "new_password": "newpassword123"
}

4. 用户管理接口

4.1 获取用户列表

接口信息

接口路径：GET /api/v1/users
接口描述：获取用户列表，支持分页和筛选
是否需要认证：是

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
keyword	string	否	搜索关键词（用户名、昵称、手机号）
status	string	否	用户状态：active, inactive, banned
gender	string	否	性别：male, female, other
age_min	integer	否	最小年龄
age_max	integer	否	最大年龄
created_start	string	否	注册开始时间
created_end	string	否	注册结束时间
sort	string	否	排序字段

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "username": "user001",
        "nickname": "小明",
        "avatar": "https://example.com/avatar/1.jpg",
        "phone": "13800138000",
        "email": "user001@example.com",
        "gender": "male",
        "age": 25,
        "status": "active",
        "created_at": "2024-01-01T00:00:00Z",
        "last_login": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "pages": 5
    }
  }
}

4.2 获取用户详情

接口信息

接口路径：GET /api/v1/users/{id}
接口描述：获取指定用户的详细信息
是否需要认证：是

路径参数

参数名	类型	必填	说明
id	integer	是	用户ID

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "user001",
    "nickname": "小明",
    "avatar": "https://example.com/avatar/1.jpg",
    "phone": "13800138000",
    "email": "user001@example.com",
    "gender": "male",
    "age": 25,
    "birthday": "1999-01-01",
    "location": "北京市朝阳区",
    "bio": "热爱旅行的90后",
    "status": "active",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "last_login": "2024-01-15T10:30:00Z",
    "stats": {
      "travel_count": 5,
      "animal_adoption_count": 2,
      "order_count": 10,
      "total_spent": 1500.00
    }
  }
}

4.3 创建用户

接口信息

接口路径：POST /api/v1/users
接口描述：创建新用户
是否需要认证：是

请求参数

{
  "username": "user002",
  "nickname": "小红",
  "phone": "13800138001",
  "email": "user002@example.com",
  "password": "password123",
  "gender": "female",
  "age": 23,
  "location": "上海市浦东新区"
}

4.4 更新用户信息

接口信息

接口路径：PUT /api/v1/users/{id}
接口描述：更新用户信息
是否需要认证：是

4.5 删除用户

接口信息

接口路径：DELETE /api/v1/users/{id}
接口描述：删除用户（软删除）
是否需要认证：是

4.6 更新用户状态

接口信息

接口路径：PUT /api/v1/users/{id}/status
接口描述：更新用户状态（激活/禁用/封禁）
是否需要认证：是

请求参数

{
  "status": "banned",
  "reason": "违规行为"
}

4.7 重置用户密码

接口信息

接口路径：PUT /api/v1/users/{id}/password
接口描述：重置用户密码
是否需要认证：是

4.8 获取用户统计

接口信息

接口路径：GET /api/v1/users/stats
接口描述：获取用户统计数据
是否需要认证：是

5. 商户管理接口

5.1 获取商户列表

接口信息

接口路径：GET /api/v1/merchants
接口描述：获取商户列表，支持分页和筛选
是否需要认证：是

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
keyword	string	否	搜索关键词（商户名称、联系人）
status	string	否	商户状态：active, inactive, pending
category	string	否	商户类别
city	string	否	所在城市

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "阳光旅行社",
        "logo": "https://example.com/logo/1.jpg",
        "category": "travel",
        "contact_person": "张经理",
        "phone": "400-123-4567",
        "email": "contact@sunshine-travel.com",
        "address": "北京市朝阳区xxx街道xxx号",
        "city": "北京",
        "status": "active",
        "rating": 4.8,
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 50,
      "pages": 3
    }
  }
}

5.2 获取商户详情

接口信息

接口路径：GET /api/v1/merchants/{id}
接口描述：获取指定商户的详细信息
是否需要认证：是

5.3 创建商户

接口信息

接口路径：POST /api/v1/merchants
接口描述：创建新商户
是否需要认证：是

5.4 更新商户信息

接口信息

接口路径：PUT /api/v1/merchants/{id}
接口描述：更新商户信息
是否需要认证：是

5.5 删除商户

接口信息

接口路径：DELETE /api/v1/merchants/{id}
接口描述：删除商户
是否需要认证：是

5.6 更新商户状态

接口信息

接口路径：PUT /api/v1/merchants/{id}/status
接口描述：更新商户状态
是否需要认证：是

5.7 获取商户统计

接口信息

接口路径：GET /api/v1/merchants/stats
接口描述：获取商户统计数据
是否需要认证：是

6. 旅行管理接口

6.1 获取旅行列表

接口信息

接口路径：GET /api/v1/travels
接口描述：获取旅行活动列表，支持分页和筛选
是否需要认证：是

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
keyword	string	否	搜索关键词（标题、目的地）
status	string	否	状态：draft, published, cancelled, completed
category	string	否	旅行类别
destination	string	否	目的地
price_min	number	否	最低价格
price_max	number	否	最高价格
start_date	string	否	开始日期
end_date	string	否	结束日期

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "title": "云南大理古城三日游",
        "description": "探索古城文化，体验白族风情",
        "images": ["https://example.com/travel/1/1.jpg"],
        "destination": "云南大理",
        "category": "cultural",
        "price": 1299.00,
        "max_participants": 20,
        "current_participants": 8,
        "start_date": "2024-03-01",
        "end_date": "2024-03-03",
        "status": "published",
        "organizer": {
          "id": 1,
          "name": "阳光旅行社"
        },
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 80,
      "pages": 4
    }
  }
}

6.2 获取旅行详情

接口信息

接口路径：GET /api/v1/travels/{id}
接口描述：获取指定旅行活动的详细信息
是否需要认证：是

6.3 创建旅行活动

接口信息

接口路径：POST /api/v1/travels
接口描述：创建新的旅行活动
是否需要认证：是

6.4 更新旅行活动

接口信息

接口路径：PUT /api/v1/travels/{id}
接口描述：更新旅行活动信息
是否需要认证：是

6.5 删除旅行活动

接口信息

接口路径：DELETE /api/v1/travels/{id}
接口描述：删除旅行活动
是否需要认证：是

6.6 更新旅行状态

接口信息

接口路径：PUT /api/v1/travels/{id}/status
接口描述：更新旅行活动状态
是否需要认证：是

6.7 获取旅行参与者

接口信息

接口路径：GET /api/v1/travels/{id}/participants
接口描述：获取旅行活动参与者列表
是否需要认证：是

6.8 获取旅行统计

接口信息

接口路径：GET /api/v1/travels/stats
接口描述：获取旅行活动统计数据
是否需要认证：是

7. 动物管理接口

7.1 获取动物列表

接口信息

接口路径：GET /api/v1/animals
接口描述：获取动物列表，支持分页和筛选
是否需要认证：是

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
keyword	string	否	搜索关键词（动物名称、品种）
species	string	否	物种：dog, cat, bird, other
status	string	否	状态：available, adopted, reserved
age_min	integer	否	最小年龄（月）
age_max	integer	否	最大年龄（月）
gender	string	否	性别：male, female
location	string	否	所在地区

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "小白",
        "species": "dog",
        "breed": "金毛",
        "age": 24,
        "gender": "male",
        "color": "金黄色",
        "weight": 25.5,
        "images": ["https://example.com/animal/1/1.jpg"],
        "description": "性格温顺，喜欢和人玩耍",
        "health_status": "healthy",
        "vaccination_status": "completed",
        "sterilization_status": "completed",
        "location": "北京市朝阳区",
        "status": "available",
        "rescue_date": "2024-01-01",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 120,
      "pages": 6
    }
  }
}

7.2 获取动物详情

接口信息

接口路径：GET /api/v1/animals/{id}
接口描述：获取指定动物的详细信息
是否需要认证：是

7.3 创建动物信息

接口信息

接口路径：POST /api/v1/animals
接口描述：添加新的动物信息
是否需要认证：是

7.4 更新动物信息

接口信息

接口路径：PUT /api/v1/animals/{id}
接口描述：更新动物信息
是否需要认证：是

7.5 删除动物信息

接口信息

接口路径：DELETE /api/v1/animals/{id}
接口描述：删除动物信息
是否需要认证：是

7.6 更新动物状态

接口信息

接口路径：PUT /api/v1/animals/{id}/status
接口描述：更新动物状态（可领养/已预约/已领养）
是否需要认证：是

7.7 获取动物认领记录

接口信息

接口路径：GET /api/v1/animals/{id}/adoptions
接口描述：获取动物的认领记录
是否需要认证：是

7.8 创建认领申请

接口信息

接口路径：POST /api/v1/animals/{id}/adoptions
接口描述：创建动物认领申请
是否需要认证：是

7.9 处理认领申请

接口信息

接口路径：PUT /api/v1/adoptions/{id}/status
接口描述：处理认领申请（批准/拒绝）
是否需要认证：是

7.10 获取认领申请列表

接口信息

接口路径：GET /api/v1/adoptions
接口描述：获取认领申请列表
是否需要认证：是

7.11 获取动物统计

接口信息

接口路径：GET /api/v1/animals/stats
接口描述：获取动物统计数据
是否需要认证：是

7.12 批量更新动物状态

接口信息

接口路径：PUT /api/v1/animals/batch/status
接口描述：批量更新动物状态
是否需要认证：是

8. 订单管理接口

8.1 获取订单列表

接口信息

接口路径：GET /api/v1/orders
接口描述：获取订单列表，支持分页和筛选
是否需要认证：是

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
keyword	string	否	搜索关键词（订单号、用户名）
status	string	否	订单状态
payment_status	string	否	支付状态
payment_method	string	否	支付方式
amount_min	number	否	最小金额
amount_max	number	否	最大金额
created_start	string	否	创建开始时间
created_end	string	否	创建结束时间

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "order_no": "ORD202401150001",
        "user": {
          "id": 1,
          "username": "user001",
          "nickname": "小明"
        },
        "type": "travel",
        "title": "云南大理古城三日游",
        "amount": 1299.00,
        "status": "completed",
        "payment_status": "paid",
        "payment_method": "wechat",
        "created_at": "2024-01-15T10:00:00Z",
        "paid_at": "2024-01-15T10:05:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 200,
      "pages": 10
    }
  }
}

8.2 获取订单详情

接口信息

接口路径：GET /api/v1/orders/{id}
接口描述：获取指定订单的详细信息
是否需要认证：是

8.3 更新订单信息

接口信息

接口路径：PUT /api/v1/orders/{id}
接口描述：更新订单信息
是否需要认证：是

8.4 删除订单

接口信息

接口路径：DELETE /api/v1/orders/{id}
接口描述：删除订单
是否需要认证：是

8.5 更新订单状态

接口信息

接口路径：PUT /api/v1/orders/{id}/status
接口描述：更新订单状态
是否需要认证：是

8.6 订单发货

接口信息

接口路径：PUT /api/v1/orders/{id}/ship
接口描述：订单发货
是否需要认证：是

8.7 订单完成

接口信息

接口路径：PUT /api/v1/orders/{id}/complete
接口描述：订单完成
是否需要认证：是

8.8 订单取消

接口信息

接口路径：PUT /api/v1/orders/{id}/cancel
接口描述：取消订单
是否需要认证：是

8.9 订单退款

接口信息

接口路径：PUT /api/v1/orders/{id}/refund
接口描述：订单退款
是否需要认证：是

8.10 获取订单统计

接口信息

接口路径：GET /api/v1/orders/stats
接口描述：获取订单统计数据
是否需要认证：是

8.11 导出订单数据

接口信息

接口路径：GET /api/v1/orders/export
接口描述：导出订单数据
是否需要认证：是

8.12 获取订单日统计

接口信息

接口路径：GET /api/v1/orders/daily-stats
接口描述：获取订单日统计数据
是否需要认证：是

8.13 获取订单月统计

接口信息

接口路径：GET /api/v1/orders/monthly-stats
接口描述：获取订单月统计数据
是否需要认证：是

8.14 批量处理订单

接口信息

接口路径：PUT /api/v1/orders/batch
接口描述：批量处理订单
是否需要认证：是

8.15 获取支付统计

接口信息

接口路径：GET /api/v1/orders/payment-stats
接口描述：获取支付统计数据
是否需要认证：是

9. 花卉管理接口

9.1 获取花卉列表

接口信息

接口路径：GET /api/v1/flowers
接口描述：获取花卉商品列表，支持分页和筛选
是否需要认证：是

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
keyword	string	否	搜索关键词（花卉名称、品种）
category	string	否	花卉类别
status	string	否	状态：active, inactive
price_min	number	否	最低价格
price_max	number	否	最高价格
merchant_id	integer	否	商户ID

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "玫瑰花束",
        "category": "rose",
        "variety": "红玫瑰",
        "price": 99.00,
        "stock": 50,
        "images": ["https://example.com/flower/1/1.jpg"],
        "description": "新鲜红玫瑰，适合表达爱意",
        "care_instructions": "保持水分，避免阳光直射",
        "merchant": {
          "id": 1,
          "name": "花语花店"
        },
        "status": "active",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 60,
      "pages": 3
    }
  }
}

9.2 获取花卉详情

接口信息

接口路径：GET /api/v1/flowers/{id}
接口描述：获取指定花卉的详细信息
是否需要认证：是

9.3 创建花卉商品

接口信息

接口路径：POST /api/v1/flowers
接口描述：创建新的花卉商品
是否需要认证：是

9.4 更新花卉信息

接口信息

接口路径：PUT /api/v1/flowers/{id}
接口描述：更新花卉信息
是否需要认证：是

9.5 删除花卉商品

接口信息

接口路径：DELETE /api/v1/flowers/{id}
接口描述：删除花卉商品
是否需要认证：是

9.6 获取花卉销售记录

接口信息

接口路径：GET /api/v1/flowers/{id}/sales
接口描述：获取花卉销售记录
是否需要认证：是

9.7 获取花卉统计

接口信息

接口路径：GET /api/v1/flowers/stats
接口描述：获取花卉统计数据
是否需要认证：是

9.8 获取花卉商户列表

接口信息

接口路径：GET /api/v1/flowers/merchants
接口描述：获取花卉商户列表
是否需要认证：是

9.9 批量更新花卉状态

接口信息

接口路径：PUT /api/v1/flowers/batch/status
接口描述：批量更新花卉状态
是否需要认证：是

10. 促销活动接口

10.1 获取促销活动列表

接口信息

接口路径：GET /api/v1/promotions
接口描述：获取促销活动列表，支持分页和筛选
是否需要认证：是

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
keyword	string	否	搜索关键词（活动名称）
type	string	否	活动类型：discount, coupon, gift
status	string	否	状态：active, inactive, expired
start_date	string	否	开始日期
end_date	string	否	结束日期

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "title": "春节特惠活动",
        "description": "全场商品8折优惠",
        "type": "discount",
        "discount_rate": 0.8,
        "min_amount": 100.00,
        "max_discount": 200.00,
        "start_date": "2024-02-01",
        "end_date": "2024-02-15",
        "status": "active",
        "usage_count": 150,
        "usage_limit": 1000,
        "created_at": "2024-01-15T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 30,
      "pages": 2
    }
  }
}

10.2 获取促销活动详情

接口信息

接口路径：GET /api/v1/promotions/{id}
接口描述：获取指定促销活动的详细信息
是否需要认证：是

10.3 创建促销活动

接口信息

接口路径：POST /api/v1/promotions
接口描述：创建新的促销活动
是否需要认证：是

10.4 更新促销活动

接口信息

接口路径：PUT /api/v1/promotions/{id}
接口描述：更新促销活动信息
是否需要认证：是

10.5 删除促销活动

接口信息

接口路径：DELETE /api/v1/promotions/{id}
接口描述：删除促销活动
是否需要认证：是

10.6 获取促销活动统计

接口信息

接口路径：GET /api/v1/promotions/stats
接口描述：获取促销活动统计数据
是否需要认证：是

10.7 获取活动参与记录

接口信息

接口路径：GET /api/v1/promotions/{id}/participants
接口描述：获取活动参与记录
是否需要认证：是

10.8 获取奖励记录

接口信息

接口路径：GET /api/v1/rewards
接口描述：获取奖励记录列表
是否需要认证：是

10.9 创建奖励记录

接口信息

接口路径：POST /api/v1/rewards
接口描述：创建奖励记录
是否需要认证：是

10.10 获取促销活动模板

接口信息

接口路径：GET /api/v1/promotions/templates
接口描述：获取促销活动模板
是否需要认证：是

11. 系统管理接口

11.1 获取系统服务列表

接口信息

接口路径：GET /api/v1/system/services
接口描述：获取系统服务状态列表
是否需要认证：是

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "数据库服务",
      "type": "database",
      "status": "running",
      "health": "healthy",
      "cpu_usage": 15.5,
      "memory_usage": 45.2,
      "last_check": "2024-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "name": "Redis缓存",
      "type": "cache",
      "status": "running",
      "health": "healthy",
      "cpu_usage": 5.2,
      "memory_usage": 25.8,
      "last_check": "2024-01-15T10:30:00Z"
    }
  ]
}

11.2 更新服务状态

接口信息

接口路径：PUT /api/v1/system/services/{id}/status
接口描述：更新系统服务状态
是否需要认证：是

11.3 获取系统统计

接口信息

接口路径：GET /api/v1/system/stats
接口描述：获取系统统计信息
是否需要认证：是

11.4 获取系统日志

接口信息

接口路径：GET /api/v1/system/logs
接口描述：获取系统日志
是否需要认证：是

11.5 清理系统日志

接口信息

接口路径：DELETE /api/v1/system/logs
接口描述：清理系统日志
是否需要认证：是

11.6 获取系统配置

接口信息

接口路径：GET /api/v1/system/config
接口描述：获取系统配置
是否需要认证：是

11.7 更新系统配置

接口信息

接口路径：PUT /api/v1/system/config
接口描述：更新系统配置
是否需要认证：是

11.8 系统备份

接口信息

接口路径：POST /api/v1/system/backup
接口描述：创建系统备份
是否需要认证：是

11.9 系统恢复

接口信息

接口路径：POST /api/v1/system/restore
接口描述：系统恢复
是否需要认证：是

11.10 获取监控数据

接口信息

接口路径：GET /api/v1/system/monitoring
接口描述：获取系统监控数据
是否需要认证：是

11.11 获取性能指标

接口信息

接口路径：GET /api/v1/system/metrics
接口描述：获取系统性能指标
是否需要认证：是

11.12 系统健康检查

接口信息

接口路径：GET /api/v1/system/health
接口描述：系统健康检查
是否需要认证：否

12. 仪表板接口

12.1 获取仪表板数据

接口信息

接口路径：GET /api/v1/dashboard
接口描述：获取仪表板统计数据
是否需要认证：是

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "overview": {
      "total_users": 1250,
      "total_orders": 3580,
      "total_revenue": 125000.00,
      "active_travels": 45
    },
    "recent_stats": {
      "new_users_today": 12,
      "orders_today": 28,
      "revenue_today": 3500.00
    },
    "growth_rate": {
      "users": 15.5,
      "orders": 22.3,
      "revenue": 18.7
    }
  }
}

12.2 获取用户增长数据

接口信息

接口路径：GET /api/v1/dashboard/user-growth
接口描述：获取用户增长趋势数据
是否需要认证：是

12.3 获取订单趋势数据

接口信息

接口路径：GET /api/v1/dashboard/order-trends
接口描述：获取订单趋势数据
是否需要认证：是

12.4 获取收入统计

接口信息

接口路径：GET /api/v1/dashboard/revenue-stats
接口描述：获取收入统计数据
是否需要认证：是

12.5 获取热门商品

接口信息

接口路径：GET /api/v1/dashboard/popular-items
接口描述：获取热门商品数据
是否需要认证：是

12.6 获取实时数据

接口信息

接口路径：GET /api/v1/dashboard/realtime
接口描述：获取实时统计数据
是否需要认证：是

13. 权限管理接口

13.1 获取权限列表

接口信息

接口路径：GET /api/v1/permissions
接口描述：获取权限列表，支持分页和筛选
是否需要认证：是

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
keyword	string	否	搜索关键词（权限名称、描述）
module	string	否	权限模块
type	string	否	权限类型：read, write, delete, manage

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "user:read",
        "display_name": "查看用户",
        "description": "查看用户信息的权限",
        "module": "user",
        "type": "read",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 50,
      "pages": 3
    }
  }
}

13.2 获取权限详情

接口信息

接口路径：GET /api/v1/permissions/{id}
接口描述：获取指定权限的详细信息
是否需要认证：是

13.3 创建权限

接口信息

接口路径：POST /api/v1/permissions
接口描述：创建新权限
是否需要认证：是

13.4 更新权限

接口信息

接口路径：PUT /api/v1/permissions/{id}
接口描述：更新权限信息
是否需要认证：是

13.5 删除权限

接口信息

接口路径：DELETE /api/v1/permissions/{id}
接口描述：删除权限
是否需要认证：是

13.6 获取角色列表

接口信息

接口路径：GET /api/v1/roles
接口描述：获取角色列表
是否需要认证：是

13.7 创建角色

接口信息

接口路径：POST /api/v1/roles
接口描述：创建新角色
是否需要认证：是

13.8 分配权限给角色

接口信息

接口路径：PUT /api/v1/roles/{id}/permissions
接口描述：为角色分配权限
是否需要认证：是

14. 错误码说明

14.1 通用错误码

错误码	HTTP状态码	说明
10000	200	操作成功
10001	400	请求参数错误
10002	401	未授权访问
10003	403	权限不足
10004	404	资源不存在
10005	409	资源冲突
10006	422	业务逻辑错误
10007	500	内部服务器错误

14.2 业务错误码

错误码	说明
20001	用户名或密码错误
20002	用户不存在
20003	用户已被禁用
20004	用户名已存在
20005	邮箱已存在
20006	手机号已存在
30001	商户不存在
30002	商户已被禁用
40001	旅行活动不存在
40002	旅行活动已满员
40003	旅行活动已结束
50001	动物不存在
50002	动物已被认领
50003	认领申请不存在
60001	订单不存在
60002	订单状态错误
60003	订单已支付
60004	订单已取消

15. 接口测试

15.1 测试环境

测试地址：https://api-test.jiebanke.com
测试账号：admin / admin123
API文档：https://api-test.jiebanke.com/docs

15.2 测试工具推荐

Postman：用于API接口测试
Swagger UI：在线API文档和测试
curl：命令行测试工具

15.3 测试示例

登录测试

curl -X POST "https://api-test.jiebanke.com/api/v1/admin/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

获取用户列表测试

curl -X GET "https://api-test.jiebanke.com/api/v1/users?page=1&size=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

16. 版本更新记录

v1.0.0 (2024-01-15)

初始版本发布
完成所有核心模块API设计
支持用户管理、旅行管理、动物认领等功能

v1.1.0 (2024-01-20)

新增花卉管理模块
新增促销活动模块
优化权限管理功能

v1.2.0 (2024-01-25)

新增仪表板统计接口
新增系统监控功能
优化错误处理机制

17. 总结

本文档详细描述了结伴客管理后台系统的所有API接口设计，涵盖了用户管理、商户管理、旅行管理、动物认领、订单管理、花卉管理、促销活动、系统管理、仪表板统计和权限管理等11个核心模块，共计100+个API接口。

所有接口均遵循RESTful设计原则，采用统一的请求响应格式，支持JWT认证和权限控制。文档提供了详细的接口说明、参数定义、响应示例和错误码说明，为前端开发和接口对接提供了完整的技术规范。

随着业务的发展，本文档将持续更新和完善，确保API设计的准确性和实用性。

37 KiB Raw Blame History Unescape Escape

管理后台接口设计文档

1. 概述

1.1 项目简介

1.2 接口设计原则

1.3 技术规范

1.4 API模块概览

2. 通用规范

2.1 请求格式

2.1.1 请求头

2.1.2 请求参数

2.2 响应格式

2.2.1 成功响应

2.2.2 分页响应

2.2.3 错误响应

2.3 状态码规范

2.4 分页参数

2.5 排序参数格式

3. 认证授权接口

3.1 管理员登录

接口信息

请求参数

响应示例

3.2 刷新令牌

接口信息

响应示例

3.3 退出登录

接口信息

响应示例

3.4 获取当前用户信息

接口信息

响应示例

3.5 修改密码

接口信息

请求参数

4. 用户管理接口

4.1 获取用户列表

接口信息

查询参数

响应示例

4.2 获取用户详情

接口信息

路径参数

响应示例

4.3 创建用户

接口信息

请求参数

4.4 更新用户信息

接口信息

4.5 删除用户

接口信息

4.6 更新用户状态

接口信息

请求参数

4.7 重置用户密码

接口信息

4.8 获取用户统计

接口信息

5. 商户管理接口

5.1 获取商户列表

接口信息

查询参数

响应示例

5.2 获取商户详情

接口信息

5.3 创建商户

接口信息

5.4 更新商户信息

接口信息

5.5 删除商户

接口信息

5.6 更新商户状态

接口信息

5.7 获取商户统计

接口信息

6. 旅行管理接口

6.1 获取旅行列表

接口信息

查询参数

响应示例

37 KiB

Raw Blame History