jiebanke/docs/管理后台接口设计文档.md

# 管理后台接口设计文档

## 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 请求头
```http
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 成功响应
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}
```

#### 2.2.2 分页响应
```json
{
  "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 错误响应
```json
{
  "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`
- **接口描述**：管理员登录获取访问令牌
- **是否需要认证**：否

#### 请求参数
```json
{
  "username": "admin",
  "password": "password123"
}
```

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

#### 响应示例
```json
{
  "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`
- **接口描述**：获取当前登录管理员的信息
- **是否需要认证**：是

#### 响应示例
```json
{
  "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`
- **接口描述**：获取管理后台仪表板统计数据
- **是否需要认证**：是

#### 响应示例
```json
{
  "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） |

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

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

#### 请求参数
```json
{
  "status": "banned",
  "reason": "违规行为"
}
```

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

#### 响应示例
```json
{
  "success": true,
  "code": 200,
  "message": "状态更新成功"
}
```

### 4.4 批量更新用户状态

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

#### 请求参数
```json
{
  "userIds": [1, 2, 3],
  "status": "inactive",
  "reason": "批量操作"
}
```

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

#### 响应示例
```json
{
  "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） |

#### 响应示例
```json
{
  "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） |

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

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

#### 请求参数
```json
{
  "action": "approve",
  "reason": "内容符合规范，通过审核",
  "is_featured": 1
}
```

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

#### 响应示例
```json
{
  "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-已退出 |

#### 响应示例
```json
{
  "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） |

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

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

#### 请求参数
```json
{
  "status": "unavailable",
  "reason": "动物生病，暂停认领"
}
```

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

#### 响应示例
```json
{
  "success": true,
  "code": 200,
  "message": "状态更新成功"
}
```

### 6.4 批量更新动物状态

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

#### 请求参数
```json
{
  "animal_ids": [1, 2, 3],
  "status": "unavailable",
  "reason": "批量下架"
}
```

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

#### 响应示例
```json
{
  "success": true,
  "code": 200,
  "message": "批量更新成功",
  "data": {
    "successCount": 3,
    "failedCount": 0
  }
}
```

### 6.5 获取动物统计数据

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

#### 响应示例
```json
{
  "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） |

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

#### 请求参数
```json
{
  "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"
}
```

#### 响应示例
```json
{
  "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 | 否 | - | 结束日期 |

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

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

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

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

#### 响应示例
```json
{
  "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`
- **接口描述**：获取认领申请统计数据
- **是否需要认证**：是

#### 响应示例
```json
{
  "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): 订单状态筛选

**响应示例：**
```json
{
  "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

**响应示例：**
```json
{
  "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

**请求参数：**
```json
{
  "status": "cancelled",
  "reason": "用户申请取消"
}
```

**响应示例：**
```json
{
  "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

**响应示例：**
```json
{
  "success": true,
  "message": "订单删除成功"
}
```

### 7.5 获取订单统计数据

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

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

**响应示例：**
```json
{
  "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): 状态筛选

**响应示例：**
```json
{
  "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`

**接口描述：** 创建新管理员

**请求参数：**
```json
{
  "username": "newadmin",
  "password": "password123",
  "email": "newadmin@example.com",
  "nickname": "新管理员",
  "role": "admin"
}
```

**响应示例：**
```json
{
  "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

**请求参数：**
```json
{
  "email": "updated@example.com",
  "nickname": "更新后的昵称",
  "role": "admin",
  "status": 1
}
```

**响应示例：**
```json
{
  "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

**响应示例：**
```json
{
  "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`

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

**响应示例：**
```json
{
  "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

**响应示例：**
```json
{
  "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

**响应示例：**
```json
{
  "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`

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

**响应示例：**
```json
{
  "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`

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

**响应示例：**
```json
{
  "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

**响应示例：**
```json
{
  "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

**响应示例：**
```json
{
  "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 | 否 | 文件分类 |

#### 响应示例
```json
{
  "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 | 否 | 搜索关键词（文件名） |

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

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

#### 请求参数
```json
{
  "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 |

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

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

#### 请求参数
```json
{
  "site": {
    "name": "结伴客",
    "description": "专业的旅行结伴和动物认领平台"
  },
  "upload": {
    "max_file_size": 20971520
  }
}
```

#### 响应示例
```json
{
  "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接口规范，包括：

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

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