aiotagro/jiebanke

Fork 0

Files

ylweng 47c816270d 重构动物模型和路由系统，优化查询逻辑并新增商户和促销活动功能

2025-09-22 02:04:07 +08:00

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

请求参数

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

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

响应示例

{
  "success": true,
  "code": 200,
  "message": "登录成功",
  "data": {
    "admin": {
      "id": 1,
      "username": "admin",
      "role": "super_admin",
      "created_at": "2024-01-01T10:00:00Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

3.2 获取管理员信息

接口信息

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

响应示例

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "admin",
    "role": "super_admin",
    "created_at": "2024-01-01T10:00:00Z",
    "last_login_at": "2024-01-15T09:30:00Z"
  }
}

3.3 获取仪表板数据

接口信息

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

响应示例

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "statistics": {
      "totalUsers": 1000,
      "totalAnimals": 300,
      "totalTravels": 200,
      "totalOrders": 1500
    },
    "recentActivities": [
      {
        "type": "user_register",
        "message": "新用户注册",
        "time": "2024-01-15T10:30:00Z"
      }
    ],
    "systemInfo": {
      "nodeVersion": "v18.17.0",
      "platform": "linux",
      "uptime": 86400
    }
  }
}

4. 用户管理接口

4.1 获取用户列表

接口信息

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

查询参数

参数名	类型	必填	默认值	说明
page	integer	否	1	页码
pageSize	integer	否	10	每页数量
keyword	string	否	-	搜索关键词（昵称、手机号、邮箱）
userType	string	否	-	用户类型
status	string	否	-	用户状态（active/inactive/banned）
startDate	string	否	-	开始日期
endDate	string	否	-	结束日期
sortField	string	否	created_at	排序字段
sortOrder	string	否	desc	排序方向（asc/desc）

响应示例

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "users": [
      {
        "id": 1,
        "openid": "wx_openid_123456",
        "unionid": "wx_unionid_789012",
        "nickname": "张三",
        "avatar": "https://example.com/avatar.jpg",
        "phone": "13800138000",
        "email": "zhangsan@example.com",
        "gender": 1,
        "birthday": "1990-01-01",
        "location": "北京市朝阳区",
        "bio": "热爱旅行和小动物",
        "user_type": "regular",
        "status": "active",
        "interests": ["旅行", "摄影"],
        "occupation": "软件工程师",
        "real_name": "张三",
        "id_card": "110101199001011234",
        "real_name_verified": true,
        "phone_verified": true,
        "email_verified": false,
        "balance": 1500.00,
        "points": 1200,
        "level": 3,
        "travel_count": 5,
        "animal_claim_count": 2,
        "last_login_at": "2024-01-15T10:30:00Z",
        "created_at": "2024-01-01T10:00:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 100,
      "totalPages": 10
    }
  }
}

4.2 获取用户详情

接口信息

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

路径参数

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

响应示例

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "user": {
      "id": 1,
      "openid": "wx_openid_123456",
      "unionid": "wx_unionid_789012",
      "nickname": "张三",
      "avatar": "https://example.com/avatar.jpg",
      "phone": "13800138000",
      "email": "zhangsan@example.com",
      "gender": 1,
      "birthday": "1990-01-01",
      "location": "北京市朝阳区",
      "bio": "热爱旅行和小动物",
      "user_type": "regular",
      "status": "active",
      "interests": ["旅行", "摄影"],
      "occupation": "软件工程师",
      "real_name": "张三",
      "id_card": "110101199001011234",
      "real_name_verified": true,
      "phone_verified": true,
      "email_verified": false,
      "balance": 1500.00,
      "points": 1200,
      "level": 3,
      "travel_count": 5,
      "animal_claim_count": 2,
      "recentTravels": [
        {
          "id": 1,
          "title": "北京三日游",
          "destination": "北京",
          "start_date": "2024-01-10",
          "end_date": "2024-01-12",
          "status": "completed",
          "created_at": "2024-01-05T10:00:00Z"
        }
      ],
      "recentClaims": [
        {
          "id": 1,
          "animal_name": "小白",
          "status": "approved",
          "created_at": "2024-01-08T10:00:00Z"
        }
      ],
      "last_login_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  }
}

4.3 更新用户状态

接口信息

接口路径：PUT /api/v1/admin/users/{userId}/status
接口描述：更新用户状态
是否需要认证：是

路径参数

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

请求参数

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

参数名	类型	必填	说明
status	string	是	用户状态（active/inactive/banned）
reason	string	否	操作原因

响应示例

{
  "success": true,
  "code": 200,
  "message": "状态更新成功"
}

4.4 批量更新用户状态

接口信息

接口路径：PUT /api/v1/admin/users/batch-status
接口描述：批量更新用户状态
是否需要认证：是

请求参数

{
  "userIds": [1, 2, 3],
  "status": "inactive",
  "reason": "批量操作"
}

参数名	类型	必填	说明
userIds	array	是	用户ID数组
status	string	是	用户状态（active/inactive/banned）
reason	string	否	操作原因

响应示例

{
  "success": true,
  "code": 200,
  "message": "批量更新成功",
  "data": {
    "successCount": 3,
    "failedCount": 0
  }
}

4.5 获取用户统计数据

接口信息

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

查询参数

参数名	类型	必填	默认值	说明
period	string	否	30d	统计周期（7d/30d/90d/1y）

响应示例

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "totalUsers": 1000,
    "activeUsers": 800,
    "newUsersToday": 10,
    "newUsersThisWeek": 50,
    "newUsersThisMonth": 200,
    "userGrowthChart": [
      {
        "date": "2024-01-01",
        "count": 10
      }
    ],
    "statusDistribution": {
      "active": 800,
      "inactive": 150,
      "banned": 50
    },
    "levelDistribution": {
      "1": 400,
      "2": 300,
      "3": 200,
      "4": 80,
      "5": 20
    }
  }
}

4.6 导出用户数据

接口信息

接口路径：GET /api/v1/admin/users/export
接口描述：导出用户数据为Excel文件
是否需要认证：是

查询参数

参数名	类型	必填	说明
format	string	否	导出格式（excel/csv），默认excel
keyword	string	否	搜索关键词
status	string	否	用户状态筛选
startDate	string	否	开始日期
endDate	string	否	结束日期

响应

成功时返回文件流
失败时返回JSON错误信息

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,
        "price_per_person": 2500.00,
        "includes": "住宿、早餐、门票、导游",
        "excludes": "午餐、晚餐、个人消费",
        "itinerary": [
          {
            "day": 1,
            "title": "抵达大理",
            "activities": ["机场接机", "入住酒店", "古城漫步"]
          }
        ],
        "requirements": "身体健康，有一定体力",
        "travel_type": "cultural",
        "status": "recruiting",
        "is_featured": false,
        "view_count": 156,
        "like_count": 23,
        "comment_count": 8,
        "created_by": 1,
        "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,
    "price_per_person": 2500.00,
    "includes": "住宿、早餐、门票、导游",
    "excludes": "午餐、晚餐、个人消费",
    "travel_type": "cultural",
    "itinerary": [
      {
        "day": 1,
        "title": "抵达大理",
        "activities": ["接机", "入住客栈", "古城夜游"]
      },
      {
        "day": 2,
        "title": "大理古城游览",
        "activities": ["洱海骑行", "三塔寺参观", "古城购物"]
      }
    ],
    "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/admin/animals
接口描述：获取动物列表，支持分页、搜索和筛选
是否需要认证：是

查询参数

参数名	类型	必填	默认值	说明
page	integer	否	1	页码
limit	integer	否	10	每页数量
keyword	string	否	-	搜索关键词（动物名称）
type	string	否	-	动物类型
status	string	否	-	状态（available/claimed/unavailable）
farmer_id	integer	否	-	农场主ID
start_date	string	否	-	开始日期
end_date	string	否	-	结束日期
sort_by	string	否	created_at	排序字段
sort_order	string	否	desc	排序方向（asc/desc）

响应示例

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "animals": [
      {
        "id": 1,
        "name": "小花",
        "species": "猫",
        "breed": "英国短毛猫",
        "age": 24,
        "gender": "female",
        "price": 500.00,
        "status": "available",
        "description": "性格温顺，喜欢晒太阳",
        "images": [
          "https://example.com/cat1.jpg",
          "https://example.com/cat2.jpg"
        ],
        "merchant_id": 1,
        "merchant_name": "爱心动物农场",
        "claim_count": 0,
        "created_at": "2024-01-10T10:00:00Z",
        "updated_at": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 30,
      "pages": 3
    }
  }
}

6.2 获取动物详情

接口信息

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

路径参数

参数名	类型	必填	说明
animal_id	integer	是	动物ID

响应示例

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "animal": {
      "id": 1,
      "name": "小花",
      "type": "猫",
      "breed": "英国短毛猫",
      "age": 24,
      "gender": "female",
      "price": 500.00,
      "daily_cost": 15.00,
      "location": "北京市朝阳区",
      "status": "available",
      "health_status": "健康",
      "description": "小花是一只非常温顺的英国短毛猫，喜欢晒太阳和玩毛线球...",
      "images": [
        "https://example.com/cat1.jpg",
        "https://example.com/cat2.jpg"
      ],
      "vaccination_records": [
        {
          "vaccine": "狂犬疫苗",
          "date": "2024-01-01",
          "next_date": "2025-01-01"
        }
      ],
      "farmer": {
        "id": 1,
        "name": "爱心动物农场",
        "contact_phone": "13800138000"
      },
      "claim_count": 0,
      "recent_claims": [
        {
          "id": 1,
          "user_name": "张三",
          "status": "pending",
          "created_at": "2024-01-15T10:00:00Z"
        }
      ],
      "created_at": "2024-01-10T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  }
}

6.3 更新动物状态

接口信息

接口路径：PUT /api/v1/admin/animals/{animal_id}/status
接口描述：更新动物状态
是否需要认证：是

路径参数

参数名	类型	必填	说明
animal_id	integer	是	动物ID

请求参数

{
  "status": "unavailable",
  "reason": "动物生病，暂停认领"
}

参数名	类型	必填	说明
status	string	是	动物状态（available/claimed/unavailable）
reason	string	否	操作原因

响应示例

{
  "success": true,
  "code": 200,
  "message": "状态更新成功"
}

6.4 批量更新动物状态

接口信息

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

请求参数

{
  "animal_ids": [1, 2, 3],
  "status": "unavailable",
  "reason": "批量下架"
}

参数名	类型	必填	说明
animal_ids	array	是	动物ID数组
status	string	是	动物状态（available/claimed/unavailable）
reason	string	否	操作原因

响应示例

{
  "success": true,
  "code": 200,
  "message": "批量更新成功",
  "data": {
    "successCount": 3,
    "failedCount": 0
  }
}

6.5 获取动物统计数据

接口信息

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

响应示例

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "totalStats": {
      "total_animals": 100,
      "available_animals": 60,
      "claimed_animals": 30,
      "total_claims": 150,
      "avg_price": 450.00
    },
    "speciesStats": [
      {
        "species": "猫",
        "count": 50,
        "percentage": 50.0
      },
      {
        "species": "狗",
        "count": 30,
        "percentage": 30.0
      }
    ],
    "statusStats": {
      "available": 60,
      "claimed": 30,
      "unavailable": 10
    },
    "monthlyTrends": [
      {
        "month": "2024-01",
        "new_animals": 10,
        "claims": 15
      }
    ]
  }
}

6.6 导出动物数据

接口信息

接口路径：GET /api/v1/admin/animals/export
接口描述：导出动物数据
是否需要认证：是

查询参数

参数名	类型	必填	说明
format	string	否	导出格式（csv/json），默认csv
keyword	string	否	搜索关键词
species	string	否	物种筛选
status	string	否	状态筛选
merchant_id	integer	否	商家ID筛选
start_date	string	否	开始日期
end_date	string	否	结束日期

响应

成功时返回文件流
失败时返回JSON错误信息

6.7 获取动物认领记录

接口信息

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

路径参数

参数名	类型	必填	说明
animal_id	integer	是	动物ID

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
limit	integer	否	每页数量，默认10
status	string	否	认领状态（pending/approved/rejected/cancelled）

响应示例

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "claims": [
      {
        "id": 1,
        "user_id": 2,
        "user_name": "张三",
        "user_phone": "13800138000",
        "status": "pending",
        "claim_reason": "喜欢小动物，有养宠经验",
        "admin_note": "",
        "created_at": "2024-01-15T10:00:00Z",
        "updated_at": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 5,
      "pages": 1
    }
  }
}

所需权限：animal:create

请求参数

{
  "name": "小白",
  "type": "狗",
  "breed": "金毛寻回犬",
  "gender": 1,
  "age": 36,
  "weight": 25.5,
  "color": "金黄色",
  "description": "性格活泼，喜欢运动",
  "personality": "活泼、友善、聪明",
  "health_status": "健康",
  "vaccination_records": "已完成基础疫苗接种",
  "location": "上海市浦东新区",
  "farmer_id": 2,
  "price": 800.00,
  "daily_cost": 15.00,
  "images": [
    "https://example.com/dog1.jpg",
    "https://example.com/dog2.jpg"
  ],
  "status": "available"
}

响应示例

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

7. 认领管理接口

7.1 获取认领申请列表

接口信息

接口路径：GET /api/v1/admin/animal-claims
接口描述：获取所有认领申请列表，支持分页、搜索和筛选
是否需要认证：是

查询参数

参数名	类型	必填	默认值	说明
page	integer	否	1	页码
limit	integer	否	10	每页数量
status	string	否	-	申请状态（pending/approved/rejected/cancelled）
animal_type	string	否	-	动物类型
user_id	integer	否	-	用户ID
start_date	string	否	-	开始日期
end_date	string	否	-	结束日期

响应示例

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "claims": [
      {
        "id": 1,
        "claim_no": "CLAIM202401150001",
        "animal_id": 1,
        "animal_name": "小花",
        "animal_type": "猫",
        "animal_image": "https://example.com/cat1.jpg",
        "user_id": 2,
        "username": "张三",
        "user_phone": "13800138000",
        "claim_reason": "喜欢小动物，有养宠经验",
        "claim_duration": 12,
        "total_amount": 2400.00,
        "contact_info": "微信：zhangsan123",
        "status": "pending",
        "created_at": "2024-01-15T10:00:00Z",
        "updated_at": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 30,
      "pages": 3
    }
  }
}

7.2 获取认领申请详情

接口信息

接口路径：GET /api/v1/admin/animal-claims/{claim_id}
接口描述：获取指定认领申请的详细信息
是否需要认证：是

路径参数

参数名	类型	必填	说明
claim_id	integer	是	认领申请ID

响应示例

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "claim": {
      "id": 1,
      "claim_no": "CLAIM202401150001",
      "animal": {
        "id": 1,
        "name": "小花",
        "species": "猫",
        "breed": "英国短毛猫",
        "images": ["https://example.com/cat1.jpg"]
      },
      "user": {
        "id": 2,
        "username": "张三",
        "phone": "13800138000",
        "avatar_url": "https://example.com/avatar.jpg"
      },
      "claim_reason": "喜欢小动物，有养宠经验，家里环境适合养宠物",
      "claim_duration": 12,
      "total_amount": 2400.00,
      "contact_info": "微信：zhangsan123，QQ：123456789",
      "status": "pending",
      "review_remark": "",
      "reviewed_by": null,
      "reviewed_at": null,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  }
}

7.3 审核认领申请

接口信息

接口路径：PUT /api/v1/admin/animal-claims/{claim_id}/review
接口描述：审核认领申请
是否需要认证：是

路径参数

参数名	类型	必填	说明
claim_id	integer	是	认领申请ID

请求参数

{
  "status": "approved",
  "review_remark": "申请人条件符合要求，同意认领"
}

参数名	类型	必填	说明
status	string	是	审核状态（approved/rejected）
review_remark	string	否	审核备注

响应示例

{
  "success": true,
  "code": 200,
  "message": "认领申请审核通过",
  "data": {
    "claim": {
      "id": 1,
      "status": "approved",
      "review_remark": "申请人条件符合要求，同意认领",
      "reviewed_by": 1,
      "reviewed_at": "2024-01-16T09:00:00Z"
    }
  }
}

7.4 获取认领统计数据

接口信息

接口路径：GET /api/v1/admin/animal-claims/statistics
接口描述：获取认领申请统计数据
是否需要认证：是

响应示例

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "totalStats": {
      "total_claims": 150,
      "pending_claims": 20,
      "approved_claims": 100,
      "rejected_claims": 25,
      "cancelled_claims": 5,
      "total_amount": 360000.00,
      "avg_duration": 10.5
    },
    "statusStats": {
      "pending": 20,
      "approved": 100,
      "rejected": 25,
      "cancelled": 5
    },
    "monthlyTrends": [
      {
        "month": "2024-01",
        "new_claims": 15,
        "approved_claims": 12,
        "total_amount": 28800.00
      }
    ],
    "animalTypeStats": [
      {
        "animal_type": "猫",
        "count": 80,
        "percentage": 53.3
      },
      {
        "animal_type": "狗",
        "count": 50,
        "percentage": 33.3
      }
    ]
  }
}

7.5 导出认领数据

接口信息

接口路径：GET /api/v1/admin/animal-claims/export
接口描述：导出认领申请数据
是否需要认证：是

查询参数

参数名	类型	必填	说明
format	string	否	导出格式（csv/json），默认csv
status	string	否	状态筛选
animal_type	string	否	动物类型筛选
user_id	integer	否	用户ID筛选
start_date	string	否	开始日期
end_date	string	否	结束日期

响应

成功时返回文件流
失败时返回JSON错误信息

7. 订单管理

7.1 获取订单列表

接口路径： GET /orders/admin

接口描述： 管理员获取所有订单列表，支持分页和筛选

查询参数：

page (integer, optional): 页码，默认为1
limit (integer, optional): 每页数量，默认为10
status (string, optional): 订单状态筛选

响应示例：

{
  "success": true,
  "data": [
    {
      "id": 1,
      "order_no": "ORD20231201001",
      "user_id": 1,
      "user_name": "张三",
      "animal_id": 1,
      "animal_name": "小花",
      "merchant_id": 1,
      "merchant_name": "爱心农场",
      "total_amount": 299.00,
      "status": "paid",
      "created_at": "2023-12-01T10:00:00Z",
      "updated_at": "2023-12-01T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total": 50,
    "total_pages": 5
  }
}

7.2 获取订单详情

接口路径： GET /orders/{orderId}

接口描述： 获取指定订单的详细信息

路径参数：

orderId (integer, required): 订单ID

响应示例：

{
  "success": true,
  "data": {
    "order": {
      "id": 1,
      "order_no": "ORD20231201001",
      "user_id": 1,
      "user_name": "张三",
      "user_phone": "13800138000",
      "animal_id": 1,
      "animal_name": "小花",
      "animal_species": "猫",
      "merchant_id": 1,
      "merchant_name": "爱心农场",
      "total_amount": 299.00,
      "status": "paid",
      "payment_method": "wechat",
      "payment_time": "2023-12-01T10:30:00Z",
      "created_at": "2023-12-01T10:00:00Z",
      "updated_at": "2023-12-01T10:30:00Z"
    }
  }
}

7.3 更新订单状态

接口路径： PUT /orders/{orderId}/status

接口描述： 管理员更新订单状态

路径参数：

orderId (integer, required): 订单ID

请求参数：

{
  "status": "cancelled",
  "reason": "用户申请取消"
}

响应示例：

{
  "success": true,
  "message": "订单状态更新成功",
  "data": {
    "order_id": 1,
    "status": "cancelled",
    "updated_at": "2023-12-01T15:30:00Z"
  }
}

7.4 删除订单

接口路径： DELETE /orders/{orderId}

接口描述： 管理员删除订单

路径参数：

orderId (integer, required): 订单ID

响应示例：

{
  "success": true,
  "message": "订单删除成功"
}

7.5 获取订单统计数据

接口路径： GET /admin/system/order-stats

接口描述： 获取订单统计数据

响应示例：

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 1250,
    "totalAmount": 125000.00,
    "byStatus": [
      {
        "status": "pending",
        "count": 45
      },
      {
        "status": "paid",
        "count": 980
      },
      {
        "status": "cancelled",
        "count": 225
      }
    ],
    "byDate": [
      {
        "date": "2023-12-01",
        "count": 25,
        "amount": 2500.00
      }
    ]
  }
}

8. 系统管理

8.1 获取管理员列表

接口路径： GET /admin

接口描述： 获取管理员列表，支持分页和筛选

查询参数：

page (integer, optional): 页码，默认为1
pageSize (integer, optional): 每页数量，默认为10
username (string, optional): 用户名搜索
role (string, optional): 角色筛选
status (integer, optional): 状态筛选

响应示例：

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "admins": [
      {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com",
        "nickname": "系统管理员",
        "role": "super_admin",
        "status": 1,
        "last_login_at": "2023-12-01T09:30:00Z",
        "created_at": "2023-01-01T10:00:00Z",
        "updated_at": "2023-12-01T09:30:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total": 5,
      "total_pages": 1
    }
  }
}

8.2 创建管理员

接口路径： POST /admin

接口描述： 创建新管理员

请求参数：

{
  "username": "newadmin",
  "password": "password123",
  "email": "newadmin@example.com",
  "nickname": "新管理员",
  "role": "admin"
}

响应示例：

{
  "success": true,
  "code": 201,
  "message": "创建成功",
  "data": {
    "admin": {
      "id": 6,
      "username": "newadmin",
      "email": "newadmin@example.com",
      "nickname": "新管理员",
      "role": "admin",
      "status": 1,
      "created_at": "2023-12-01T10:30:00Z"
    }
  }
}

8.3 更新管理员

接口路径： PUT /admin/{id}

接口描述： 更新管理员信息

路径参数：

id (integer, required): 管理员ID

请求参数：

{
  "email": "updated@example.com",
  "nickname": "更新后的昵称",
  "role": "admin",
  "status": 1
}

响应示例：

{
  "success": true,
  "code": 200,
  "message": "更新成功",
  "data": {
    "admin": {
      "id": 6,
      "username": "newadmin",
      "email": "updated@example.com",
      "nickname": "更新后的昵称",
      "role": "admin",
      "status": 1,
      "updated_at": "2023-12-01T15:30:00Z"
    }
  }
}

8.4 删除管理员

接口路径： DELETE /admin/{id}

接口描述： 删除管理员

路径参数：

id (integer, required): 管理员ID

响应示例：

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

    "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`

#### 响应示例
```json
{
  "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 /admin/statistics/overview

接口描述： 获取系统概览统计数据

响应示例：

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "users": {
      "total_users": 1250,
      "active_users": 890,
      "new_users_today": 15,
      "new_users_week": 89
    },
    "travels": {
      "total_travels": 156,
      "published_travels": 89,
      "new_travels_today": 3
    },
    "animals": {
      "total_animals": 234,
      "available_animals": 156,
      "claimed_animals": 78
    },
    "orders": {
      "total_orders": 445,
      "completed_orders": 389,
      "pending_orders": 56,
      "total_revenue": 125600.00
    }
  }
}

9.2 获取用户增长趋势

接口路径： GET /admin/statistics/user-growth

接口描述： 获取用户增长趋势数据

查询参数：

period (string, optional): 统计周期，可选值：7d, 30d, 90d, 365d，默认30d

响应示例：

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "period": "30d",
    "trendData": [
      {
        "date": "2023-11-01",
        "new_users": 12,
        "total_users": 1180
      },
      {
        "date": "2023-11-02",
        "new_users": 15,
        "total_users": 1195
      }
    ]
  }
}

9.3 获取业务统计

接口路径： GET /admin/statistics/business

接口描述： 获取业务相关统计数据

查询参数：

period (string, optional): 统计周期，可选值：7d, 30d, 90d，默认30d

响应示例：

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "period": "30d",
    "travelStats": [
      {
        "date": "2023-11-01",
        "new_travels": 5,
        "published_travels": 3,
        "total_views": 245
      }
    ],
    "claimStats": [
      {
        "date": "2023-11-01",
        "new_claims": 8,
        "approved_claims": 6,
        "rejected_claims": 1
      }
    ],
    "orderStats": [
      {
        "date": "2023-11-01",
        "new_orders": 12,
        "completed_orders": 10,
        "daily_revenue": 2500.00
      }
    ]
  }
}

9.4 获取地域分布统计

接口路径： GET /admin/statistics/geographic

接口描述： 获取地域分布统计数据

响应示例：

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "userDistribution": [
      {
        "province": "北京市",
        "city": "北京市",
        "user_count": 156
      },
      {
        "province": "上海市",
        "city": "上海市",
        "user_count": 134
      }
    ],
    "provinceStats": [
      {
        "province": "北京市",
        "user_count": 156,
        "farmer_count": 23,
        "merchant_count": 12
      }
    ],
    "destinationStats": [
      {
        "destination": "云南大理",
        "travel_count": 45
      },
      {
        "destination": "西藏拉萨",
        "travel_count": 38
      }
    ]
  }
}

9.5 获取用户行为分析

接口路径： GET /admin/statistics/user-behavior

接口描述： 获取用户行为分析数据

响应示例：

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "activityStats": [
      {
        "activity_level": "高活跃",
        "user_count": 234
      },
      {
        "activity_level": "中活跃",
        "user_count": 456
      },
      {
        "activity_level": "低活跃",
        "user_count": 560
      }
    ],
    "levelDistribution": [
      {
        "level": "新手",
        "user_count": 456,
        "avg_points": 120.5,
        "avg_travel_count": 1.2,
        "avg_claim_count": 0.8
      }
    ],
    "behaviorStats": [
      {
        "behavior_type": "浏览旅行",
        "user_count": 890
      },
      {
        "behavior_type": "发布旅行",
        "user_count": 234
      },
      {
        "behavior_type": "认领动物",
        "user_count": 156
      }
    ]
  }
}

9.6 获取收入统计

接口路径： GET /admin/statistics/revenue

接口描述： 获取收入统计数据

查询参数：

period (string, optional): 统计周期，可选值：7d, 30d, 90d, 365d，默认30d

响应示例：

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "period": "30d",
    "revenueStats": [
      {
        "date": "2023-11-01",
        "total_revenue": 2500.00,
        "order_count": 12,
        "avg_order_value": 208.33
      }
    ],
    "categoryStats": [
      {
        "category": "旅行费用",
        "total_revenue": 45600.00,
        "order_count": 156,
        "avg_order_value": 292.31
      }
    ],
    "paymentMethodStats": [
      {
        "payment_method": "微信支付",
        "order_count": 234,
        "total_amount": 56780.00
      },
      {
        "payment_method": "支付宝",
        "order_count": 189,
        "total_amount": 45230.00
      }
    ]
  }
}

9.7 导出统计报告

接口路径： GET /admin/statistics/export

接口描述： 导出统计报告

查询参数：

reportType (string, optional): 报告类型，可选值：overview, users, revenue，默认overview
period (string, optional): 统计周期，可选值：7d, 30d, 90d，默认30d
format (string, optional): 导出格式，可选值：csv, json，默认csv

响应示例：

{
  "success": true,
  "code": 200,
  "message": "导出成功",
  "data": {
    "downloadUrl": "https://example.com/exports/report_20231201.csv",
    "filename": "统计报告_20231201.csv",
    "fileSize": 2048
  }
}

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

#### 响应示例
```json
{
  "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版本管理和功能扩展

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

54 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 获取仪表板数据

接口信息

响应示例

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 获取动物详情

接口信息

路径参数

响应示例

6.3 更新动物状态

54 KiB

Raw Blame History