aiotagro/jiebanke

Fork 0

Files

ylweng 14aca938de 重构动物认领页面和导航菜单，统一使用SVG图标并优化交互体验

2025-09-21 21:12:27 +08:00

48 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

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/auth/login
接口描述：管理员登录获取访问令牌
是否需要认证：否

请求参数

{
  "username": "admin",
  "password": "password123",
  "captcha": "ABCD",
  "captcha_key": "captcha_key_123"
}

参数名	类型	必填	说明
username	string	是	用户名或邮箱
password	string	是	密码
captcha	string	是	验证码
captcha_key	string	是	验证码key

响应示例

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200,
    "token_type": "Bearer",
    "admin_info": {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "real_name": "系统管理员",
      "avatar_url": "https://example.com/avatar.jpg",
      "roles": ["super_admin"],
      "permissions": ["*"]
    }
  }
}

3.2 刷新令牌

接口信息

接口路径：POST /api/v1/auth/refresh
接口描述：使用刷新令牌获取新的访问令牌
是否需要认证：否

请求参数

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应示例

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

3.3 退出登录

接口信息

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

响应示例

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

3.4 获取验证码

接口信息

接口路径：GET /api/v1/auth/captcha
接口描述：获取登录验证码
是否需要认证：否

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "captcha_key": "captcha_key_123",
    "captcha_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expires_in": 300
  }
}

4. 用户管理接口

4.1 获取用户列表

接口信息

接口路径：GET /api/v1/users
接口描述：分页获取用户列表
是否需要认证：是
所需权限：user:read

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
sort	string	否	排序，默认created_at:desc
keyword	string	否	搜索关键词（用户名、邮箱、手机号）
status	integer	否	用户状态：0-禁用，1-正常，2-待验证
user_type	integer	否	用户类型：1-普通用户，2-商家用户
created_start	string	否	创建时间开始（YYYY-MM-DD）
created_end	string	否	创建时间结束（YYYY-MM-DD）

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "uuid": "user_123456",
        "username": "testuser",
        "email": "test@example.com",
        "phone": "13800138000",
        "nickname": "测试用户",
        "avatar_url": "https://example.com/avatar.jpg",
        "gender": 1,
        "birthday": "1990-01-01",
        "location": "北京市",
        "status": 1,
        "user_type": 1,
        "email_verified_at": "2024-01-01T10:00:00Z",
        "phone_verified_at": "2024-01-01T10:00:00Z",
        "last_login_at": "2024-01-15T09:30:00Z",
        "created_at": "2024-01-01T10:00:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "pages": 5
    }
  }
}

4.2 获取用户详情

接口信息

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

路径参数

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

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "uuid": "user_123456",
    "username": "testuser",
    "email": "test@example.com",
    "phone": "13800138000",
    "nickname": "测试用户",
    "avatar_url": "https://example.com/avatar.jpg",
    "gender": 1,
    "birthday": "1990-01-01",
    "location": "北京市",
    "bio": "这是个人简介",
    "status": 1,
    "user_type": 1,
    "email_verified_at": "2024-01-01T10:00:00Z",
    "phone_verified_at": "2024-01-01T10:00:00Z",
    "last_login_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "profile": {
      "real_name": "张三",
      "id_card": "110101199001011234",
      "id_card_verified": 1,
      "occupation": "软件工程师",
      "education": "本科",
      "income_level": 3,
      "travel_experience": "去过很多地方...",
      "interests": ["旅行", "摄影", "美食"],
      "languages": ["中文", "英语"],
      "emergency_contact": {
        "name": "李四",
        "phone": "13900139000",
        "relationship": "朋友"
      }
    },
    "statistics": {
      "travel_count": 5,
      "adoption_count": 2,
      "order_count": 10,
      "total_spent": 5000.00
    }
  }
}

4.3 创建用户

接口信息

接口路径：POST /api/v1/users
接口描述：创建新用户
是否需要认证：是
所需权限：user:create

请求参数

{
  "username": "newuser",
  "email": "newuser@example.com",
  "phone": "13800138001",
  "password": "password123",
  "nickname": "新用户",
  "gender": 1,
  "birthday": "1995-05-15",
  "location": "上海市",
  "user_type": 1,
  "status": 1
}

参数名	类型	必填	说明
username	string	是	用户名，3-20字符
email	string	是	邮箱地址
phone	string	否	手机号码
password	string	是	密码，6-20字符
nickname	string	否	昵称
gender	integer	否	性别：0-未知，1-男，2-女
birthday	string	否	生日，格式：YYYY-MM-DD
location	string	否	所在地
user_type	integer	否	用户类型，默认1
status	integer	否	状态，默认1

响应示例

{
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 101,
    "uuid": "user_654321",
    "username": "newuser",
    "email": "newuser@example.com",
    "phone": "13800138001",
    "nickname": "新用户",
    "status": 1,
    "user_type": 1,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

4.4 更新用户信息

接口信息

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

请求参数

{
  "nickname": "更新的昵称",
  "gender": 2,
  "birthday": "1995-05-15",
  "location": "深圳市",
  "bio": "更新的个人简介",
  "status": 1
}

响应示例

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "uuid": "user_123456",
    "username": "testuser",
    "nickname": "更新的昵称",
    "gender": 2,
    "location": "深圳市",
    "updated_at": "2024-01-15T10:35:00Z"
  }
}

4.5 删除用户

接口信息

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

响应示例

{
  "code": 200,
  "message": "删除成功"
}

4.6 批量操作用户

接口信息

接口路径：POST /api/v1/users/batch
接口描述：批量操作用户（启用、禁用、删除）
是否需要认证：是
所需权限：user:batch

请求参数

{
  "action": "disable",
  "user_ids": [1, 2, 3, 4, 5],
  "reason": "违规操作"
}

参数名	类型	必填	说明
action	string	是	操作类型：enable-启用，disable-禁用，delete-删除
user_ids	array	是	用户ID列表
reason	string	否	操作原因

响应示例

{
  "code": 200,
  "message": "批量操作成功",
  "data": {
    "success_count": 4,
    "failed_count": 1,
    "failed_items": [
      {
        "user_id": 3,
        "reason": "用户不存在"
      }
    ]
  }
}

5. 旅行管理接口

5.1 获取旅行列表

接口信息

接口路径：GET /api/v1/travels
接口描述：分页获取旅行活动列表
是否需要认证：是
所需权限：travel:read

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
sort	string	否	排序，默认created_at:desc
keyword	string	否	搜索关键词（标题、目的地）
status	integer	否	状态：0-草稿，1-发布，2-进行中，3-已完成，4-已取消
travel_type	string	否	旅行类型
creator_id	integer	否	创建者ID
destination	string	否	目的地
start_date	string	否	开始日期（YYYY-MM-DD）
end_date	string	否	结束日期（YYYY-MM-DD）

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "uuid": "travel_123456",
        "title": "云南大理古城深度游",
        "description": "探索大理古城的历史文化...",
        "destination": "云南大理",
        "start_date": "2024-03-01",
        "end_date": "2024-03-05",
        "duration_days": 5,
        "max_participants": 8,
        "current_participants": 3,
        "budget_min": 2000.00,
        "budget_max": 3000.00,
        "travel_type": "cultural",
        "status": 1,
        "is_featured": 0,
        "view_count": 156,
        "like_count": 23,
        "comment_count": 8,
        "creator": {
          "id": 1,
          "username": "traveler001",
          "nickname": "旅行达人",
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "images": [
          "https://example.com/image1.jpg",
          "https://example.com/image2.jpg"
        ],
        "created_at": "2024-01-15T10:00:00Z",
        "updated_at": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 50,
      "pages": 3
    }
  }
}

5.2 获取旅行详情

接口信息

接口路径：GET /api/v1/travels/{id}
接口描述：获取旅行活动详细信息
是否需要认证：是
所需权限：travel:read

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "uuid": "travel_123456",
    "title": "云南大理古城深度游",
    "description": "探索大理古城的历史文化，体验白族风情...",
    "destination": "云南大理",
    "destination_detail": {
      "province": "云南省",
      "city": "大理市",
      "district": "大理古城",
      "address": "大理古城南门",
      "latitude": 25.6916,
      "longitude": 100.1669
    },
    "start_date": "2024-03-01",
    "end_date": "2024-03-05",
    "duration_days": 5,
    "max_participants": 8,
    "current_participants": 3,
    "min_age": 18,
    "max_age": 60,
    "gender_limit": 0,
    "budget_min": 2000.00,
    "budget_max": 3000.00,
    "travel_type": "cultural",
    "transportation": "高铁+包车",
    "accommodation": "客栈",
    "itinerary": [
      {
        "day": 1,
        "title": "抵达大理",
        "activities": ["接机", "入住客栈", "古城夜游"],
        "meals": ["晚餐"]
      },
      {
        "day": 2,
        "title": "大理古城游览",
        "activities": ["洱海骑行", "三塔寺参观", "古城购物"],
        "meals": ["早餐", "午餐", "晚餐"]
      }
    ],
    "requirements": "身体健康，有一定体力",
    "contact_info": {
      "wechat": "traveler001",
      "phone": "13800138000"
    },
    "images": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg"
    ],
    "tags": ["文化", "古城", "摄影"],
    "status": 1,
    "is_featured": 0,
    "view_count": 156,
    "like_count": 23,
    "comment_count": 8,
    "share_count": 5,
    "creator": {
      "id": 1,
      "username": "traveler001",
      "nickname": "旅行达人",
      "avatar_url": "https://example.com/avatar.jpg",
      "travel_count": 15,
      "rating": 4.8
    },
    "participants": [
      {
        "id": 1,
        "user_id": 2,
        "username": "user002",
        "nickname": "小明",
        "avatar_url": "https://example.com/avatar2.jpg",
        "status": 1,
        "applied_at": "2024-01-10T15:30:00Z",
        "approved_at": "2024-01-11T09:00:00Z"
      }
    ],
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

5.3 审核旅行活动

接口信息

接口路径：POST /api/v1/travels/{id}/review
接口描述：审核旅行活动
是否需要认证：是
所需权限：travel:review

请求参数

{
  "action": "approve",
  "reason": "内容符合规范，通过审核",
  "is_featured": 1
}

参数名	类型	必填	说明
action	string	是	审核动作：approve-通过，reject-拒绝
reason	string	是	审核理由
is_featured	integer	否	是否设为精选：0-否，1-是

响应示例

{
  "code": 200,
  "message": "审核成功",
  "data": {
    "id": 1,
    "status": 1,
    "is_featured": 1,
    "reviewed_at": "2024-01-15T10:30:00Z",
    "review_reason": "内容符合规范，通过审核"
  }
}

5.4 获取旅行参与者

接口信息

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

查询参数

参数名	类型	必填	说明
status	integer	否	参与状态：0-申请中，1-已通过，2-已拒绝，3-已退出

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "user_id": 2,
        "user": {
          "id": 2,
          "username": "user002",
          "nickname": "小明",
          "avatar_url": "https://example.com/avatar2.jpg",
          "gender": 1,
          "age": 28,
          "location": "北京市"
        },
        "status": 1,
        "join_reason": "对大理文化很感兴趣，希望能参加这次旅行",
        "contact_info": {
          "wechat": "xiaoming123",
          "phone": "13900139000"
        },
        "emergency_contact": {
          "name": "李四",
          "phone": "13800138000",
          "relationship": "朋友"
        },
        "special_requirements": "素食主义者",
        "applied_at": "2024-01-10T15:30:00Z",
        "approved_at": "2024-01-11T09:00:00Z"
      }
    ]
  }
}

6. 动物认领管理接口

6.1 获取动物列表

接口信息

接口路径：GET /api/v1/animals
接口描述：分页获取动物列表
是否需要认证：是
所需权限：animal:read

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
sort	string	否	排序，默认created_at:desc
keyword	string	否	搜索关键词（动物名称）
species	string	否	物种
breed	string	否	品种
status	integer	否	状态：0-不可认领，1-可认领，2-已认领，3-暂停认领
location	string	否	所在地
farm_id	integer	否	农场ID

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "uuid": "animal_123456",
        "name": "小花",
        "species": "猫",
        "breed": "英国短毛猫",
        "gender": 2,
        "age": 24,
        "weight": 4.5,
        "color": "银渐层",
        "description": "性格温顺，喜欢晒太阳",
        "health_status": "健康",
        "location": "北京市朝阳区",
        "adoption_fee": 500.00,
        "monthly_cost": 200.00,
        "status": 1,
        "is_featured": 1,
        "view_count": 89,
        "like_count": 15,
        "adoption_count": 0,
        "images": [
          "https://example.com/cat1.jpg",
          "https://example.com/cat2.jpg"
        ],
        "farm": {
          "id": 1,
          "name": "爱心动物农场",
          "location": "北京市朝阳区"
        },
        "created_at": "2024-01-10T10:00:00Z",
        "updated_at": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 30,
      "pages": 2
    }
  }
}

6.2 获取动物详情

接口信息

接口路径：GET /api/v1/animals/{id}
接口描述：获取动物详细信息
是否需要认证：是
所需权限：animal:read

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "uuid": "animal_123456",
    "name": "小花",
    "species": "猫",
    "breed": "英国短毛猫",
    "gender": 2,
    "age": 24,
    "weight": 4.5,
    "color": "银渐层",
    "description": "小花是一只非常温顺的英国短毛猫，喜欢晒太阳和玩毛线球...",
    "personality": "温顺、亲人、活泼",
    "health_status": "健康",
    "vaccination_status": {
      "rabies": {
        "vaccinated": true,
        "date": "2023-12-01",
        "next_due": "2024-12-01"
      },
      "feline_distemper": {
        "vaccinated": true,
        "date": "2023-12-01",
        "next_due": "2024-12-01"
      }
    },
    "medical_history": "2023年11月进行了绝育手术，恢复良好",
    "location": "北京市朝阳区",
    "adoption_fee": 500.00,
    "monthly_cost": 200.00,
    "status": 1,
    "is_featured": 1,
    "view_count": 89,
    "like_count": 15,
    "adoption_count": 0,
    "images": [
      "https://example.com/cat1.jpg",
      "https://example.com/cat2.jpg"
    ],
    "videos": [
      "https://example.com/cat_video1.mp4"
    ],
    "farm": {
      "id": 1,
      "name": "爱心动物农场",
      "location": "北京市朝阳区",
      "contact_phone": "13800138000",
      "description": "专业的动物救助机构"
    },
    "caretaker": {
      "id": 1,
      "name": "张三",
      "phone": "13900139000",
      "experience": "5年动物护理经验"
    },
    "adoptions": [
      {
        "id": 1,
        "user_id": 2,
        "user": {
          "nickname": "爱心用户",
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "adoption_type": 1,
        "start_date": "2024-02-01",
        "status": 1,
        "created_at": "2024-01-15T10:00:00Z"
      }
    ],
    "created_at": "2024-01-10T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

6.3 创建动物信息

接口信息

接口路径：POST /api/v1/animals
接口描述：创建新的动物信息
是否需要认证：是
所需权限：animal:create

请求参数

{
  "name": "小白",
  "species": "狗",
  "breed": "金毛寻回犬",
  "gender": 1,
  "age": 36,
  "weight": 25.5,
  "color": "金黄色",
  "description": "性格活泼，喜欢运动",
  "personality": "活泼、友善、聪明",
  "health_status": "健康",
  "location": "上海市浦东新区",
  "farm_id": 2,
  "caretaker_id": 3,
  "adoption_fee": 800.00,
  "monthly_cost": 300.00,
  "images": [
    "https://example.com/dog1.jpg",
    "https://example.com/dog2.jpg"
  ],
  "status": 1
}

响应示例

{
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 101,
    "uuid": "animal_654321",
    "name": "小白",
    "species": "狗",
    "breed": "金毛寻回犬",
    "status": 1,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

6.4 获取认领申请列表

接口信息

接口路径：GET /api/v1/adoptions
接口描述：分页获取动物认领申请列表
是否需要认证：是
所需权限：adoption:read

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
sort	string	否	排序，默认created_at:desc
status	integer	否	状态：0-申请中，1-已通过，2-已拒绝，3-进行中，4-已完成，5-已取消
animal_id	integer	否	动物ID
user_id	integer	否	用户ID
adoption_type	integer	否	认领类型：1-长期认领，2-短期认领，3-共同认领

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "uuid": "adoption_123456",
        "animal": {
          "id": 1,
          "name": "小花",
          "species": "猫",
          "breed": "英国短毛猫",
          "images": ["https://example.com/cat1.jpg"]
        },
        "user": {
          "id": 2,
          "username": "user002",
          "nickname": "爱心用户",
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "adoption_type": 1,
        "duration_months": 12,
        "start_date": "2024-02-01",
        "end_date": "2025-02-01",
        "monthly_fee": 200.00,
        "total_fee": 2400.00,
        "payment_status": 1,
        "status": 1,
        "special_requirements": "希望能定期收到小花的照片和视频",
        "approved_at": "2024-01-16T09:00:00Z",
        "created_at": "2024-01-15T15:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 15,
      "pages": 1
    }
  }
}

6.5 审核认领申请

接口信息

接口路径：POST /api/v1/adoptions/{id}/review
接口描述：审核动物认领申请
是否需要认证：是
所需权限：adoption:review

请求参数

{
  "action": "approve",
  "reason": "申请人条件符合要求，同意认领"
}

参数名	类型	必填	说明
action	string	是	审核动作：approve-通过，reject-拒绝
reason	string	是	审核理由

响应示例

{
  "code": 200,
  "message": "审核成功",
  "data": {
    "id": 1,
    "status": 1,
    "approved_at": "2024-01-16T09:00:00Z",
    "review_reason": "申请人条件符合要求，同意认领"
  }
}

7. 订单管理接口

7.1 获取订单列表

接口信息

接口路径：GET /api/v1/orders
接口描述：分页获取订单列表
是否需要认证：是
所需权限：order:read

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
sort	string	否	排序，默认created_at:desc
order_no	string	否	订单号
user_id	integer	否	用户ID
order_type	string	否	订单类型：travel,adoption,service
status	integer	否	订单状态：0-待支付，1-已支付，2-已完成，3-已取消，4-已退款
payment_status	integer	否	支付状态：0-未支付，1-支付中，2-支付成功，3-支付失败
created_start	string	否	创建时间开始（YYYY-MM-DD）
created_end	string	否	创建时间结束（YYYY-MM-DD）
amount_min	number	否	金额下限
amount_max	number	否	金额上限

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "order_no": "ORD202401150001",
        "user": {
          "id": 2,
          "username": "user002",
          "nickname": "小明",
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "order_type": "adoption",
        "related_id": 1,
        "title": "认领小花（英国短毛猫）",
        "description": "12个月长期认领",
        "amount": 2400.00,
        "discount_amount": 0.00,
        "final_amount": 2400.00,
        "currency": "CNY",
        "status": 2,
        "payment_method": "wechat",
        "payment_status": 2,
        "paid_at": "2024-01-15T16:30:00Z",
        "completed_at": "2024-01-15T16:35:00Z",
        "created_at": "2024-01-15T16:00:00Z",
        "updated_at": "2024-01-15T16:35:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "pages": 5
    }
  }
}

7.2 获取订单详情

接口信息

接口路径：GET /api/v1/orders/{id}
接口描述：获取订单详细信息
是否需要认证：是
所需权限：order:read

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "order_no": "ORD202401150001",
    "user": {
      "id": 2,
      "username": "user002",
      "nickname": "小明",
      "avatar_url": "https://example.com/avatar.jpg",
      "phone": "13900139000"
    },
    "order_type": "adoption",
    "related_id": 1,
    "related_info": {
      "animal": {
        "id": 1,
        "name": "小花",
        "species": "猫",
        "breed": "英国短毛猫",
        "images": ["https://example.com/cat1.jpg"]
      },
      "adoption": {
        "id": 1,
        "adoption_type": 1,
        "duration_months": 12,
        "start_date": "2024-02-01",
        "end_date": "2025-02-01"
      }
    },
    "title": "认领小花（英国短毛猫）",
    "description": "12个月长期认领，包含日常照料、医疗保健等服务",
    "amount": 2400.00,
    "discount_amount": 0.00,
    "final_amount": 2400.00,
    "currency": "CNY",
    "status": 2,
    "payment_method": "wechat",
    "payment_status": 2,
    "paid_at": "2024-01-15T16:30:00Z",
    "completed_at": "2024-01-15T16:35:00Z",
    "metadata": {
      "promotion_code": null,
      "source": "miniprogram"
    },
    "payments": [
      {
        "id": 1,
        "payment_no": "PAY202401150001",
        "payment_method": "wechat",
        "amount": 2400.00,
        "status": 2,
        "third_party_no": "wx_transaction_123456",
        "paid_at": "2024-01-15T16:30:00Z"
      }
    ],
    "created_at": "2024-01-15T16:00:00Z",
    "updated_at": "2024-01-15T16:35:00Z"
  }
}

7.3 订单退款

接口信息

接口路径：POST /api/v1/orders/{id}/refund
接口描述：处理订单退款
是否需要认证：是
所需权限：order:refund

请求参数

{
  "refund_amount": 2400.00,
  "refund_reason": "用户申请退款",
  "refund_type": "full"
}

参数名	类型	必填	说明
refund_amount	number	是	退款金额
refund_reason	string	是	退款原因
refund_type	string	是	退款类型：full-全额退款，partial-部分退款

响应示例

{
  "code": 200,
  "message": "退款处理成功",
  "data": {
    "order_id": 1,
    "refund_amount": 2400.00,
    "refund_status": "processing",
    "refund_no": "REF202401150001",
    "estimated_arrival": "2024-01-18T16:30:00Z"
  }
}

8. 系统管理接口

8.1 获取管理员列表

接口信息

接口路径：GET /api/v1/admins
接口描述：分页获取管理员列表
是否需要认证：是
所需权限：admin:read

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
sort	string	否	排序，默认created_at:desc
keyword	string	否	搜索关键词（用户名、邮箱、真实姓名）
status	integer	否	状态：0-禁用，1-正常

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com",
        "real_name": "系统管理员",
        "avatar_url": "https://example.com/admin_avatar.jpg",
        "phone": "13800138000",
        "status": 1,
        "roles": [
          {
            "id": 1,
            "name": "超级管理员",
            "code": "super_admin"
          }
        ],
        "last_login_at": "2024-01-15T09:30:00Z",
        "created_at": "2024-01-01T10:00:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 5,
      "pages": 1
    }
  }
}

8.2 创建管理员

接口信息

接口路径：POST /api/v1/admins
接口描述：创建新管理员
是否需要认证：是
所需权限：admin:create

请求参数

{
  "username": "newadmin",
  "email": "newadmin@example.com",
  "password": "password123",
  "real_name": "新管理员",
  "phone": "13900139000",
  "role_ids": [2, 3],
  "status": 1
}

响应示例

{
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 6,
    "username": "newadmin",
    "email": "newadmin@example.com",
    "real_name": "新管理员",
    "status": 1,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

8.3 获取角色列表

接口信息

接口路径：GET /api/v1/roles
接口描述：获取所有角色列表
是否需要认证：是
所需权限：role:read

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "超级管理员",
        "code": "super_admin",
        "description": "拥有所有权限的超级管理员",
        "status": 1,
        "permissions": [
          {
            "id": 1,
            "name": "用户管理",
            "code": "user:*",
            "type": "menu"
          }
        ],
        "created_at": "2024-01-01T10:00:00Z"
      }
    ]
  }
}

8.4 获取权限列表

接口信息

接口路径：GET /api/v1/permissions
接口描述：获取权限树形结构
是否需要认证：是
所需权限：permission:read

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "系统管理",
        "code": "system",
        "type": "menu",
        "parent_id": null,
        "sort_order": 1,
        "children": [
          {
            "id": 2,
            "name": "用户管理",
            "code": "user",
            "type": "menu",
            "parent_id": 1,
            "sort_order": 1,
            "children": [
              {
                "id": 3,
                "name": "查看用户",
                "code": "user:read",
                "type": "button",
                "parent_id": 2,
                "sort_order": 1
              },
              {
                "id": 4,
                "name": "创建用户",
                "code": "user:create",
                "type": "button",
                "parent_id": 2,
                "sort_order": 2
              }
            ]
          }
        ]
      }
    ]
  }
}

9. 统计分析接口

9.1 获取仪表板统计

接口信息

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

查询参数

参数名	类型	必填	说明
period	string	否	统计周期：today,week,month,year，默认today

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "overview": {
      "total_users": 1250,
      "new_users_today": 15,
      "total_travels": 89,
      "active_travels": 23,
      "total_animals": 156,
      "adopted_animals": 67,
      "total_orders": 445,
      "total_revenue": 125600.00
    },
    "trends": {
      "user_growth": [
        {"date": "2024-01-08", "count": 8},
        {"date": "2024-01-09", "count": 12},
        {"date": "2024-01-10", "count": 15},
        {"date": "2024-01-11", "count": 10},
        {"date": "2024-01-12", "count": 18},
        {"date": "2024-01-13", "count": 22},
        {"date": "2024-01-14", "count": 15}
      ],
      "order_trends": [
        {"date": "2024-01-08", "count": 5, "amount": 2500.00},
        {"date": "2024-01-09", "count": 8, "amount": 4200.00},
        {"date": "2024-01-10", "count": 12, "amount": 6800.00},
        {"date": "2024-01-11", "count": 6, "amount": 3200.00},
        {"date": "2024-01-12", "count": 15, "amount": 8500.00},
        {"date": "2024-01-13", "count": 18, "amount": 9200.00},
        {"date": "2024-01-14", "count": 10, "amount": 5500.00}
      ]
    },
    "distributions": {
      "user_types": [
        {"type": "普通用户", "count": 1100, "percentage": 88.0},
        {"type": "商家用户", "count": 150, "percentage": 12.0}
      ],
      "travel_types": [
        {"type": "文化旅行", "count": 25, "percentage": 28.1},
        {"type": "休闲旅行", "count": 32, "percentage": 36.0},
        {"type": "探险旅行", "count": 18, "percentage": 20.2},
        {"type": "商务旅行", "count": 14, "percentage": 15.7}
      ],
      "animal_species": [
        {"species": "猫", "count": 78, "percentage": 50.0},
        {"species": "狗", "count": 45, "percentage": 28.8},
        {"species": "兔子", "count": 20, "percentage": 12.8},
        {"species": "其他", "count": 13, "percentage": 8.3}
      ]
    }
  }
}

9.2 获取用户统计

接口信息

接口路径：GET /api/v1/statistics/users
接口描述：获取用户相关统计数据
是否需要认证：是
所需权限：statistics:read

查询参数

参数名	类型	必填	说明
start_date	string	否	开始日期（YYYY-MM-DD）
end_date	string	否	结束日期（YYYY-MM-DD）
group_by	string	否	分组方式：day,week,month，默认day

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "summary": {
      "total_users": 1250,
      "active_users": 890,
      "new_users": 156,
      "retention_rate": 71.2
    },
    "registration_trends": [
      {"date": "2024-01-01", "count": 12},
      {"date": "2024-01-02", "count": 15},
      {"date": "2024-01-03", "count": 8}
    ],
    "activity_trends": [
      {"date": "2024-01-01", "active_count": 245},
      {"date": "2024-01-02", "active_count": 289},
      {"date": "2024-01-03", "active_count": 267}
    ],
    "demographics": {
      "age_groups": [
        {"range": "18-25", "count": 320, "percentage": 25.6},
        {"range": "26-35", "count": 450, "percentage": 36.0},
        {"range": "36-45", "count": 280, "percentage": 22.4},
        {"range": "46+", "count": 200, "percentage": 16.0}
      ],
      "gender_distribution": [
        {"gender": "男", "count": 580, "percentage": 46.4},
        {"gender": "女", "count": 620, "percentage": 49.6},
        {"gender": "未知", "count": 50, "percentage": 4.0}
      ],
      "location_distribution": [
        {"province": "北京", "count": 180, "percentage": 14.4},
        {"province": "上海", "count": 165, "percentage": 13.2},
        {"province": "广东", "count": 220, "percentage": 17.6},
        {"province": "浙江", "count": 145, "percentage": 11.6},
        {"province": "其他", "count": 540, "percentage": 43.2}
      ]
    }
  }
}

10. 文件管理接口

10.1 上传文件

接口信息

接口路径：POST /api/v1/files/upload
接口描述：上传文件（图片、视频、文档等）
是否需要认证：是
所需权限：file:upload

请求参数

Content-Type：multipart/form-data

参数名	类型	必填	说明
file	file	是	上传的文件
type	string	否	文件类型：image,video,document，默认auto
category	string	否	文件分类：avatar,travel,animal,other

响应示例

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "id": 1,
    "filename": "image_20240115_103000.jpg",
    "original_name": "beautiful_scenery.jpg",
    "file_path": "/uploads/images/2024/01/15/image_20240115_103000.jpg",
    "file_url": "https://cdn.example.com/uploads/images/2024/01/15/image_20240115_103000.jpg",
    "file_size": 1024000,
    "mime_type": "image/jpeg",
    "file_type": "image",
    "category": "travel",
    "uploaded_at": "2024-01-15T10:30:00Z"
  }
}

10.2 批量上传文件

接口信息

接口路径：POST /api/v1/files/batch-upload
接口描述：批量上传多个文件
是否需要认证：是
所需权限：file:upload

请求参数

Content-Type：multipart/form-data

参数名	类型	必填	说明
files[]	file[]	是	上传的文件数组
category	string	否	文件分类

响应示例

{
  "code": 200,
  "message": "批量上传完成",
  "data": {
    "success_count": 3,
    "failed_count": 1,
    "success_files": [
      {
        "id": 1,
        "filename": "image1.jpg",
        "file_url": "https://cdn.example.com/uploads/images/image1.jpg"
      },
      {
        "id": 2,
        "filename": "image2.jpg",
        "file_url": "https://cdn.example.com/uploads/images/image2.jpg"
      }
    ],
    "failed_files": [
      {
        "filename": "large_file.jpg",
        "error": "文件大小超过限制"
      }
    ]
  }
}

10.3 获取文件列表

接口信息

接口路径：GET /api/v1/files
接口描述：分页获取文件列表
是否需要认证：是
所需权限：file:read

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
file_type	string	否	文件类型：image,video,document
category	string	否	文件分类
keyword	string	否	搜索关键词（文件名）

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "filename": "image_20240115_103000.jpg",
        "original_name": "beautiful_scenery.jpg",
        "file_url": "https://cdn.example.com/uploads/images/2024/01/15/image_20240115_103000.jpg",
        "file_size": 1024000,
        "mime_type": "image/jpeg",
        "file_type": "image",
        "category": "travel",
        "uploaded_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "pages": 5
    }
  }
}

11. 消息通知接口

11.1 获取通知列表

接口信息

接口路径：GET /api/v1/notifications
接口描述：分页获取系统通知列表
是否需要认证：是
所需权限：notification:read

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20
type	string	否	通知类型：system,order,travel,adoption
status	integer	否	状态：0-未读，1-已读
user_id	integer	否	用户ID

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "type": "order",
        "title": "订单支付成功",
        "content": "您的订单 ORD202401150001 支付成功，感谢您的支持！",
        "user_id": 2,
        "related_type": "order",
        "related_id": 1,
        "status": 0,
        "created_at": "2024-01-15T16:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 50,
      "pages": 3
    }
  }
}

11.2 发送通知

接口信息

接口路径：POST /api/v1/notifications
接口描述：发送系统通知
是否需要认证：是
所需权限：notification:send

请求参数

{
  "type": "system",
  "title": "系统维护通知",
  "content": "系统将于今晚22:00-24:00进行维护，期间可能影响正常使用，敬请谅解。",
  "target_type": "all",
  "user_ids": [],
  "send_immediately": true
}

参数名	类型	必填	说明
type	string	是	通知类型：system,order,travel,adoption
title	string	是	通知标题
content	string	是	通知内容
target_type	string	是	目标类型：all-所有用户，specific-指定用户
user_ids	array	否	用户ID列表（target_type为specific时必填）
send_immediately	boolean	否	是否立即发送，默认true

响应示例

{
  "code": 200,
  "message": "通知发送成功",
  "data": {
    "notification_id": 101,
    "target_count": 1250,
    "sent_count": 1250,
    "failed_count": 0
  }
}

12. 系统配置接口

12.1 获取系统配置

接口信息

接口路径：GET /api/v1/system/config
接口描述：获取系统配置信息
是否需要认证：是
所需权限：system:config:read

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "site": {
      "name": "解班客",
      "description": "专业的旅行结伴和动物认领平台",
      "logo_url": "https://example.com/logo.png",
      "favicon_url": "https://example.com/favicon.ico",
      "keywords": "旅行,结伴,动物认领,宠物",
      "icp_number": "京ICP备12345678号"
    },
    "upload": {
      "max_file_size": 10485760,
      "allowed_image_types": ["jpg", "jpeg", "png", "gif", "webp"],
      "allowed_video_types": ["mp4", "avi", "mov"],
      "allowed_document_types": ["pdf", "doc", "docx", "xls", "xlsx"]
    },
    "payment": {
      "wechat_enabled": true,
      "alipay_enabled": true,
      "min_amount": 0.01,
      "max_amount": 50000.00
    },
    "notification": {
      "email_enabled": true,
      "sms_enabled": true,
      "push_enabled": true
    }
  }
}

12.2 更新系统配置

接口信息

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

请求参数

{
  "site": {
    "name": "解班客",
    "description": "专业的旅行结伴和动物认领平台"
  },
  "upload": {
    "max_file_size": 20971520
  }
}

响应示例

{
  "code": 200,
  "message": "配置更新成功",
  "data": {
    "updated_keys": ["site.name", "site.description", "upload.max_file_size"],
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

13. 错误码说明

13.1 通用错误码

错误码	HTTP状态码	说明
200	200	请求成功
400	400	请求参数错误
401	401	未授权，需要登录
403	403	权限不足
404	404	资源不存在
409	409	资源冲突
422	422	业务逻辑错误
429	429	请求频率限制
500	500	服务器内部错误

13.2 业务错误码

错误码	说明
10001	用户名已存在
10002	邮箱已存在
10003	手机号已存在
10004	用户不存在
10005	密码错误
10006	验证码错误
10007	验证码已过期
20001	旅行活动不存在
20002	旅行活动已满员
20003	旅行活动已结束
20004	已参加该旅行活动
30001	动物不存在
30002	动物不可认领
30003	动物已被认领
30004	已认领该动物
40001	订单不存在
40002	订单状态错误
40003	支付失败
40004	退款失败
50001	文件上传失败
50002	文件类型不支持
50003	文件大小超限

14. 接口测试

14.1 测试环境

测试地址：https://api-test.jiebanke.com
测试账号：
- 用户名：test_admin
- 密码：test123456

14.2 Postman集合

提供完整的Postman测试集合，包含所有接口的测试用例和环境变量配置。

14.3 接口文档

在线文档：https://docs.jiebanke.com/api
Swagger UI：https://api-test.jiebanke.com/docs

15. 总结

本文档详细描述了解班客管理后台系统的所有API接口规范，包括：

完整的接口定义：涵盖认证、用户管理、旅行管理、动物认领、订单管理等所有核心功能
统一的规范标准：采用RESTful风格，统一的请求响应格式和错误处理机制
详细的参数说明：每个接口都包含完整的请求参数、响应示例和错误码说明
安全认证机制：基于JWT的认证体系和细粒度的权限控制
扩展性设计：支持API版本管理和功能扩展

该接口设计文档为前端开发、测试和运维提供了完整的技术规范，确保系统各模块间的高效协作和数据一致性。

48 KiB Raw Blame History Unescape Escape

管理后台接口设计文档

1. 概述

1.1 项目简介

1.2 接口设计原则

1.3 技术规范

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 获取验证码

接口信息

响应示例

4. 用户管理接口

4.1 获取用户列表

接口信息

查询参数

响应示例

4.2 获取用户详情

接口信息

路径参数

响应示例

4.3 创建用户

接口信息

请求参数

响应示例

4.4 更新用户信息

接口信息

请求参数

响应示例

4.5 删除用户

接口信息

响应示例

4.6 批量操作用户

接口信息

请求参数

响应示例

5. 旅行管理接口

5.1 获取旅行列表

接口信息

查询参数

响应示例

5.2 获取旅行详情

接口信息

响应示例

5.3 审核旅行活动

接口信息

请求参数

响应示例

5.4 获取旅行参与者

接口信息

查询参数

响应示例

6. 动物认领管理接口

6.1 获取动物列表

接口信息

查询参数

响应示例

6.2 获取动物详情

接口信息

响应示例

48 KiB

Raw Blame History