jiebanke/docs/小程序app接口设计文档.md

# 小程序app接口设计文档

## 1. 概述

### 1.1 项目简介
本文档详细描述了解班客小程序端的所有API接口设计，包括用户系统、旅行结伴、动物认领、支付系统、消息通知等模块的接口规范。

### 1.2 接口设计原则
- **RESTful风格**：遵循REST架构风格
- **统一响应格式**：所有接口采用统一的响应格式
- **微信生态集成**：深度集成微信小程序能力
- **安全认证**：基于微信授权和JWT Token
- **性能优化**：针对移动端网络环境优化

### 1.3 技术规范
- **协议**：HTTPS
- **数据格式**：JSON
- **字符编码**：UTF-8
- **认证方式**：微信授权 + JWT Token
- **API版本**：v1

## 2. 通用规范

### 2.1 请求格式

#### 2.1.1 请求头
```http
Content-Type: application/json
Authorization: Bearer <JWT_TOKEN>
Accept: application/json
User-Agent: JieBanKe-MiniProgram/1.0.0
X-Platform: miniprogram
X-Version: 1.0.0
```

#### 2.1.2 请求参数
- **路径参数**：用于资源标识，如 `/api/v1/travels/{id}`
- **查询参数**：用于过滤、排序、分页等，如 `?page=1&size=10&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": 10,
      "total": 50,
      "pages": 5,
      "has_next": true,
      "has_prev": false
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}
```

#### 2.2.3 错误响应
```json
{
  "code": 400,
  "message": "请求参数错误",
  "error": {
    "type": "VALIDATION_ERROR",
    "details": [
      {
        "field": "phone",
        "message": "手机号格式不正确"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}
```

### 2.3 状态码规范

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

### 2.4 分页参数

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

## 3. 用户认证接口

### 3.1 微信登录

#### 接口信息
- **接口路径**：`POST /api/v1/auth/wechat/login`
- **接口描述**：微信小程序登录
- **是否需要认证**：否

#### 请求参数
```json
{
  "code": "wx_code_from_login",
  "encrypted_data": "encrypted_user_info",
  "iv": "initialization_vector",
  "raw_data": "raw_user_data",
  "signature": "data_signature"
}
```

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| code | string | 是 | 微信登录凭证 |
| encrypted_data | string | 否 | 加密的用户信息 |
| iv | string | 否 | 加密算法的初始向量 |
| raw_data | string | 否 | 原始数据字符串 |
| signature | string | 否 | 数据签名 |

#### 响应示例
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200,
    "token_type": "Bearer",
    "user_info": {
      "id": 1,
      "uuid": "user_123456",
      "openid": "wx_openid_123",
      "unionid": "wx_unionid_456",
      "nickname": "微信用户",
      "real_name": "",
      "avatar": "https://wx.qlogo.cn/avatar.jpg",
      "user_type": "regular",
      "balance": 0.00,
      "status": "active",
      "is_new_user": false,
      "profile_completed": true
    }
  }
}
```

### 3.2 刷新令牌

#### 接口信息
- **接口路径**：`POST /api/v1/auth/refresh`
- **接口描述**：刷新访问令牌
- **是否需要认证**：否

#### 请求参数
```json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "令牌刷新成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200,
    "token_type": "Bearer"
  }
}
```

### 3.3 获取用户信息

#### 接口信息
- **接口路径**：`GET /api/v1/auth/me`
- **接口描述**：获取当前用户信息
- **是否需要认证**：是

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "uuid": "user_123456",
    "nickname": "旅行达人",
    "real_name": "张三",
    "avatar_url": "https://example.com/avatar.jpg",
    "user_type": "normal",
    "balance": 1500.00,
    "status": 1,
    "profile_completed": true,
    "created_at": "2024-01-01T10:00:00Z",
    "statistics": {
      "travel_count": 5,
      "adoption_count": 2,
      "following_count": 15,
      "followers_count": 8,
      "like_count": 23
    }
  }
}
```

### 3.4 更新用户信息

#### 接口信息
- **接口路径**：`PUT /api/v1/auth/profile`
- **接口描述**：更新用户个人信息
- **是否需要认证**：是

#### 请求参数
```json
{
  "nickname": "新昵称",
  "avatar_url": "https://example.com/new_avatar.jpg",
  "gender": 2,
  "birthday": "1995-05-15",
  "location": "上海市",
  "bio": "更新的个人简介",
  "interests": ["旅行", "摄影", "美食"],
  "occupation": "软件工程师"
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "nickname": "新昵称",
    "avatar": "https://example.com/new_avatar.jpg",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

## 4. 旅行结伴接口

### 4.1 获取旅行列表

#### 接口信息
- **接口路径**：`GET /api/v1/travels`
- **接口描述**：分页获取旅行活动列表
- **是否需要认证**：否

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |
| sort | string | 否 | 排序，默认created_at:desc |
| keyword | string | 否 | 搜索关键词 |
| destination | string | 否 | 目的地 |
| travel_type | string | 否 | 旅行类型 |
| start_date | string | 否 | 开始日期（YYYY-MM-DD） |
| end_date | string | 否 | 结束日期（YYYY-MM-DD） |
| budget_min | number | 否 | 预算下限 |
| budget_max | number | 否 | 预算上限 |
| status | integer | 否 | 状态：1-招募中，2-进行中，3-已完成 |
| is_featured | integer | 否 | 是否精选：1-是 |

#### 响应示例
```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": "午餐、晚餐、个人消费",
        "travel_type": "cultural",
        "status": "recruiting",
        "is_featured": true,
        "view_count": 156,
        "like_count": 23,
        "comment_count": 8,
        "creator": {
          "id": 1,
          "nickname": "旅行达人",
          "avatar": "https://example.com/avatar.jpg"
        },
        "cover_image": "https://example.com/cover.jpg",
        "images": [
          "https://example.com/image1.jpg",
          "https://example.com/image2.jpg"
        ],
        "tags": ["文化", "古城", "摄影"],
        "created_at": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 50,
      "pages": 5,
      "has_next": true,
      "has_prev": false
    }
  }
}
```

### 4.2 获取旅行详情

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

#### 响应示例
```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": "身体健康，有一定体力，热爱文化旅行",
    "included_services": ["住宿", "早餐", "景点门票", "导游服务"],
    "excluded_services": ["往返交通", "午晚餐", "个人消费"],
    "contact_info": {
      "wechat": "traveler001",
      "phone": "13800138000"
    },
    "images": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg"
    ],
    "tags": ["文化", "古城", "摄影"],
    "status": "recruiting",
    "is_featured": true,
    "view_count": 156,
    "like_count": 23,
    "comment_count": 8,
    "share_count": 5,
    "creator": {
      "id": 1,
      "nickname": "旅行达人",
      "avatar": "https://example.com/avatar.jpg",
      "travel_count": 15,
      "rating": 4.8,
      "verified": true
    },
    "participants": [
      {
        "id": 1,
        "user": {
          "id": 2,
          "nickname": "小明",
          "avatar": "https://example.com/avatar2.jpg",
          "age": 28,
          "gender": 1
        },
        "status": "confirmed",
        "applied_at": "2024-01-10T15:30:00Z"
      }
    ],
    "is_liked": false,
    "is_applied": false,
    "can_apply": true,
    "created_at": "2024-01-15T10:00:00Z"
  }
}
```

### 4.3 创建旅行活动

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

#### 请求参数
```json
{
  "title": "西藏拉萨朝圣之旅",
  "description": "深度体验西藏文化，朝圣布达拉宫...",
  "destination": "西藏拉萨",
  "start_date": "2024-04-01",
  "end_date": "2024-04-07",
  "max_participants": 6,
  "price_per_person": 6500.00,
  "includes": "住宿、早餐、景点门票",
  "excludes": "往返机票、午晚餐",
  "travel_type": "cultural",
  "itinerary": [
    {
      "day": 1,
      "title": "抵达拉萨",
      "activities": ["接机", "入住酒店", "适应高原"]
    }
  ],
  "requirements": "身体健康，无高原反应病史",
  "contact_info": {
    "wechat": "tibet_lover",
    "phone": "13900139000"
  },
  "images": [
    "https://example.com/tibet1.jpg",
    "https://example.com/tibet2.jpg"
  ],
  "tags": ["西藏", "文化", "朝圣"]
}
```

#### 响应示例
```json
{
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 101,
    "uuid": "travel_654321",
    "title": "西藏拉萨朝圣之旅",
    "status": 0,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 4.4 申请参加旅行

#### 接口信息
- **接口路径**：`POST /api/v1/travels/{id}/apply`
- **接口描述**：申请参加旅行活动
- **是否需要认证**：是

#### 请求参数
```json
{
  "join_reason": "对大理文化很感兴趣，希望能参加这次深度游",
  "contact_info": {
    "wechat": "xiaoming123",
    "phone": "13900139000"
  },
  "emergency_contact": {
    "name": "李四",
    "phone": "13800138000",
    "relationship": "朋友"
  },
  "special_requirements": "素食主义者，需要素食安排",
  "travel_experience": "去过云南多次，有丰富的旅行经验"
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "申请成功",
  "data": {
    "application_id": 1,
    "status": 0,
    "applied_at": "2024-01-15T10:30:00Z",
    "message": "申请已提交，请等待组织者审核"
  }
}
```

### 4.5 获取我的旅行

#### 接口信息
- **接口路径**：`GET /api/v1/travels/mine`
- **接口描述**：获取我创建和参与的旅行活动
- **是否需要认证**：是

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | string | 否 | 类型：created-我创建的，joined-我参与的，applied-我申请的 |
| status | integer | 否 | 状态筛选 |
| page | integer | 否 | 页码 |
| size | integer | 否 | 每页数量 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "title": "云南大理古城深度游",
        "destination": "云南大理",
        "start_date": "2024-03-01",
        "end_date": "2024-03-05",
        "status": 1,
        "my_role": "creator",
        "my_status": 1,
        "participants_count": 3,
        "max_participants": 8,
        "cover_image": "https://example.com/cover.jpg",
        "created_at": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 5,
      "pages": 1
    }
  }
}
```

## 5. 动物认领接口

### 5.1 获取动物列表

#### 接口信息
- **接口路径**：`GET /api/v1/animals`
- **接口描述**：分页获取可认领动物列表
- **是否需要认证**：否

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |
| sort | string | 否 | 排序，默认created_at:desc |
| keyword | string | 否 | 搜索关键词（动物名称） |
| type | string | 否 | 动物类型：cat,dog,rabbit,other |
| breed | string | 否 | 品种 |
| gender | string | 否 | 性别：male,female |
| age_min | integer | 否 | 年龄下限（月） |
| age_max | integer | 否 | 年龄上限（月） |
| location | string | 否 | 所在地 |
| status | string | 否 | 状态：available,claimed,unavailable |
| is_featured | integer | 否 | 是否精选：1-是 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "uuid": "animal_123456",
        "name": "小花",
        "type": "猫",
        "breed": "英国短毛猫",
        "gender": "female",
        "age": 24,
        "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": "爱心动物农场",
          "location": "北京市朝阳区"
        },
        "view_count": 89,
        "like_count": 15,
        "created_at": "2024-01-10T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 30,
      "pages": 3
    }
  }
}
```

### 5.2 获取动物详情

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

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "uuid": "animal_123456",
    "name": "小花",
    "type": "猫",
    "breed": "英国短毛猫",
    "gender": "female",
    "age": 24,
    "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": "爱心动物农场",
      "location": "北京市朝阳区",
      "contact_phone": "13800138000"
    },
    "view_count": 89,
    "like_count": 15,
    "is_liked": false,
    "can_adopt": true,
    "created_at": "2024-01-10T10:00:00Z"
  }
}
```

### 5.3 申请认领动物

#### 接口信息
- **接口路径**：`POST /api/v1/animals/{id}/adopt`
- **接口描述**：申请认领动物
- **是否需要认证**：是

#### 请求参数
```json
{
  "adoption_type": 1,
  "duration_months": 12,
  "start_date": "2024-02-01",
  "adoption_reason": "非常喜欢小花，希望能给它一个温暖的家",
  "experience": "养过猫咪，有丰富的养宠经验",
  "living_condition": "独居公寓，环境安静，适合猫咪生活",
  "contact_info": {
    "wechat": "cat_lover",
    "phone": "13900139000"
  },
  "emergency_contact": {
    "name": "李四",
    "phone": "13800138000",
    "relationship": "朋友"
  },
  "special_requirements": "希望能定期收到小花的照片和视频"
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "申请成功",
  "data": {
    "adoption_id": 1,
    "status": 0,
    "total_fee": 2400.00,
    "applied_at": "2024-01-15T10:30:00Z",
    "message": "认领申请已提交，请等待农场审核"
  }
}
```

### 5.4 获取我的认领

#### 接口信息
- **接口路径**：`GET /api/v1/adoptions/mine`
- **接口描述**：获取我的动物认领记录
- **是否需要认证**：是

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| status | integer | 否 | 状态：0-申请中，1-已通过，2-已拒绝，3-进行中，4-已完成 |
| page | integer | 否 | 页码 |
| size | integer | 否 | 每页数量 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "uuid": "adoption_123456",
        "animal": {
          "id": 1,
          "name": "小花",
          "species": "cat",
          "breed": "英国短毛猫",
          "cover_image": "https://example.com/cat_cover.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,
        "status": 3,
        "progress": {
          "days_passed": 15,
          "total_days": 365,
          "percentage": 4.1
        },
        "next_update_date": "2024-02-15",
        "applied_at": "2024-01-15T10:30:00Z",
        "approved_at": "2024-01-16T09:00:00Z",
        "started_at": "2024-02-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 2,
      "pages": 1
    }
  }
}
```

### 5.5 获取认领动态

#### 接口信息
- **接口路径**：`GET /api/v1/adoptions/{id}/updates`
- **接口描述**：获取认领动物的成长动态
- **是否需要认证**：是

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "type": "daily_care",
        "title": "小花今日状况",
        "content": "小花今天很活泼，吃了很多猫粮，还玩了新玩具",
        "images": [
          "https://example.com/update1.jpg",
          "https://example.com/update2.jpg"
        ],
        "videos": [
          "https://example.com/update_video.mp4"
        ],
        "caretaker": {
          "name": "张三",
          "avatar_url": "https://example.com/caretaker.jpg"
        },
        "created_at": "2024-02-15T14:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 20,
      "pages": 2
    }
  }
}
```

## 6. 支付系统接口

### 6.1 创建订单

#### 接口信息
- **接口路径**：`POST /api/v1/orders`
- **接口描述**：创建支付订单
- **是否需要认证**：是

#### 请求参数
```json
{
  "order_type": "adoption",
  "related_id": 1,
  "items": [
    {
      "name": "认领小花（英国短毛猫）",
      "description": "12个月长期认领",
      "quantity": 1,
      "unit_price": 2400.00
    }
  ],
  "amount": 2400.00,
  "currency": "CNY",
  "payment_method": "wechat",
  "metadata": {
    "adoption_id": 1,
    "source": "miniprogram"
  }
}
```

#### 响应示例
```json
{
  "code": 201,
  "message": "订单创建成功",
  "data": {
    "order_id": 1,
    "order_no": "ORD202401150001",
    "amount": 2400.00,
    "currency": "CNY",
    "status": 0,
    "expires_at": "2024-01-15T11:00:00Z",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 6.2 发起支付

#### 接口信息
- **接口路径**：`POST /api/v1/orders/{id}/pay`
- **接口描述**：发起微信支付
- **是否需要认证**：是

#### 请求参数
```json
{
  "payment_method": "wechat",
  "openid": "wx_openid_123456"
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "支付参数获取成功",
  "data": {
    "payment_id": 1,
    "payment_no": "PAY202401150001",
    "payment_params": {
      "appId": "wx_app_id",
      "timeStamp": "1705312200",
      "nonceStr": "random_string",
      "package": "prepay_id=wx_prepay_123456",
      "signType": "RSA",
      "paySign": "signature_string"
    },
    "expires_at": "2024-01-15T11:00:00Z"
  }
}
```

### 6.3 查询订单状态

#### 接口信息
- **接口路径**：`GET /api/v1/orders/{id}`
- **接口描述**：查询订单详情和支付状态
- **是否需要认证**：是

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "order_no": "ORD202401150001",
    "order_type": "adoption",
    "related_id": 1,
    "related_info": {
      "animal": {
        "id": 1,
        "name": "小花",
        "species": "cat",
        "cover_image": "https://example.com/cat_cover.jpg"
      }
    },
    "title": "认领小花（英国短毛猫）",
    "description": "12个月长期认领",
    "amount": 2400.00,
    "currency": "CNY",
    "status": 2,
    "payment_method": "wechat",
    "payment_status": 2,
    "paid_at": "2024-01-15T10:35:00Z",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 6.4 获取我的订单

#### 接口信息
- **接口路径**：`GET /api/v1/orders/mine`
- **接口描述**：获取我的订单列表
- **是否需要认证**：是

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| status | integer | 否 | 订单状态 |
| order_type | string | 否 | 订单类型 |
| page | integer | 否 | 页码 |
| size | integer | 否 | 每页数量 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "order_no": "ORD202401150001",
        "order_type": "adoption",
        "title": "认领小花（英国短毛猫）",
        "amount": 2400.00,
        "status": 2,
        "payment_status": 2,
        "cover_image": "https://example.com/cat_cover.jpg",
        "paid_at": "2024-01-15T10:35:00Z",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 5,
      "pages": 1
    }
  }
}
```

## 7. 消息通知接口

### 7.1 获取消息列表

#### 接口信息
- **接口路径**：`GET /api/v1/messages`
- **接口描述**：获取用户消息列表
- **是否需要认证**：是

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | string | 否 | 消息类型：system,travel,adoption,order |
| status | integer | 否 | 状态：0-未读，1-已读 |
| page | integer | 否 | 页码 |
| size | integer | 否 | 每页数量 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "type": "adoption",
        "title": "认领申请通过",
        "content": "您的动物认领申请已通过审核，请及时完成支付",
        "avatar": "https://example.com/system_avatar.jpg",
        "related_type": "adoption",
        "related_id": 1,
        "status": 0,
        "created_at": "2024-01-16T09:00:00Z"
      },
      {
        "id": 2,
        "type": "travel",
        "title": "旅行申请通过",
        "content": "您申请参加的"云南大理古城深度游"已通过审核",
        "avatar": "https://example.com/travel_avatar.jpg",
        "related_type": "travel",
        "related_id": 1,
        "status": 1,
        "created_at": "2024-01-15T16:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 15,
      "pages": 2
    },
    "unread_count": 3
  }
}
```

### 7.2 标记消息已读

#### 接口信息
- **接口路径**：`PUT /api/v1/messages/{id}/read`
- **接口描述**：标记消息为已读
- **是否需要认证**：是

#### 响应示例
```json
{
  "code": 200,
  "message": "标记成功"
}
```

### 7.3 批量标记已读

#### 接口信息
- **接口路径**：`PUT /api/v1/messages/batch-read`
- **接口描述**：批量标记消息为已读
- **是否需要认证**：是

#### 请求参数
```json
{
  "message_ids": [1, 2, 3, 4, 5]
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "批量标记成功",
  "data": {
    "updated_count": 5
  }
}
```

## 8. 文件上传接口

### 8.1 上传图片

#### 接口信息
- **接口路径**：`POST /api/v1/upload/image`
- **接口描述**：上传图片文件
- **是否需要认证**：是

#### 请求参数
- **Content-Type**：`multipart/form-data`

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file | file | 是 | 图片文件 |
| category | string | 否 | 分类：avatar,travel,animal,other |

#### 响应示例
```json
{
  "code": 200,
  "message": "上传成功",
  "data": {
    "file_id": 1,
    "file_url": "https://cdn.example.com/uploads/images/2024/01/15/image_123456.jpg",
    "file_size": 1024000,
    "width": 1920,
    "height": 1080,
    "uploaded_at": "2024-01-15T10:30:00Z"
  }
}
```

### 8.2 批量上传图片

#### 接口信息
- **接口路径**：`POST /api/v1/upload/images`
- **接口描述**：批量上传多张图片
- **是否需要认证**：是

#### 请求参数
- **Content-Type**：`multipart/form-data`

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| files[] | file[] | 是 | 图片文件数组 |
| category | string | 否 | 分类 |

#### 响应示例
```json
{
  "code": 200,
  "message": "批量上传完成",
  "data": {
    "success_count": 3,
    "failed_count": 0,
    "files": [
      {
        "file_id": 1,
        "file_url": "https://cdn.example.com/uploads/images/image1.jpg"
      },
      {
        "file_id": 2,
        "file_url": "https://cdn.example.com/uploads/images/image2.jpg"
      }
    ]
  }
}
```

## 9. 搜索接口

### 9.1 综合搜索

#### 接口信息
- **接口路径**：`GET /api/v1/search`
- **接口描述**：综合搜索旅行和动物
- **是否需要认证**：否

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| keyword | string | 是 | 搜索关键词 |
| type | string | 否 | 搜索类型：all,travel,animal，默认all |
| page | integer | 否 | 页码 |
| size | integer | 否 | 每页数量 |

#### 响应示例
```json
{
  "code": 200,
  "message": "搜索成功",
  "data": {
    "travels": {
      "items": [
        {
          "id": 1,
          "title": "云南大理古城深度游",
          "destination": "云南大理",
          "cover_image": "https://example.com/travel_cover.jpg",
          "creator": {
            "nickname": "旅行达人"
          }
        }
      ],
      "total": 5
    },
    "animals": {
      "items": [
        {
          "id": 1,
          "name": "小花",
          "species": "cat",
          "breed": "英国短毛猫",
          "cover_image": "https://example.com/cat_cover.jpg",
          "farm": {
            "name": "爱心动物农场"
          }
        }
      ],
      "total": 3
    },
    "total_count": 8
  }
}
```

### 9.2 搜索建议

#### 接口信息
- **接口路径**：`GET /api/v1/search/suggestions`
- **接口描述**：获取搜索建议
- **是否需要认证**：否

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| keyword | string | 是 | 搜索关键词 |
| type | string | 否 | 类型：travel,animal |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "suggestions": [
      "大理古城",
      "大理洱海",
      "大理三塔",
      "大理旅游"
    ]
  }
}
```

## 10. 收藏点赞接口

### 10.1 点赞/取消点赞

#### 接口信息
- **接口路径**：`POST /api/v1/likes`
- **接口描述**：点赞或取消点赞
- **是否需要认证**：是

#### 请求参数
```json
{
  "target_type": "travel",
  "target_id": 1,
  "action": "like"
}
```

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| target_type | string | 是 | 目标类型：travel,animal |
| target_id | integer | 是 | 目标ID |
| action | string | 是 | 操作：like-点赞，unlike-取消点赞 |

#### 响应示例
```json
{
  "code": 200,
  "message": "点赞成功",
  "data": {
    "is_liked": true,
    "like_count": 24
  }
}
```

### 10.2 收藏/取消收藏

#### 接口信息
- **接口路径**：`POST /api/v1/favorites`
- **接口描述**：收藏或取消收藏
- **是否需要认证**：是

#### 请求参数
```json
{
  "target_type": "animal",
  "target_id": 1,
  "action": "favorite"
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "收藏成功",
  "data": {
    "is_favorited": true,
    "favorite_count": 16
  }
}
```

### 10.3 获取我的收藏

#### 接口信息
- **接口路径**：`GET /api/v1/favorites/mine`
- **接口描述**：获取我的收藏列表
- **是否需要认证**：是

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | string | 否 | 类型：travel,animal |
| page | integer | 否 | 页码 |
| size | integer | 否 | 每页数量 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "target_type": "travel",
        "target_id": 1,
        "target_info": {
          "id": 1,
          "title": "云南大理古城深度游",
          "destination": "云南大理",
          "cover_image": "https://example.com/travel_cover.jpg"
        },
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 8,
      "pages": 1
    }
  }
}
```

## 11. 评论接口

### 11.1 获取评论列表

#### 接口信息
- **接口路径**：`GET /api/v1/comments`
- **接口描述**：获取评论列表
- **是否需要认证**：否

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| target_type | string | 是 | 目标类型：travel,animal |
| target_id | integer | 是 | 目标ID |
| page | integer | 否 | 页码 |
| size | integer | 否 | 每页数量 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "content": "这个旅行计划看起来很不错，很想参加！",
        "user": {
          "id": 2,
          "nickname": "旅行爱好者",
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "like_count": 3,
        "is_liked": false,
        "replies": [
          {
            "id": 2,
            "content": "欢迎加入我们！",
            "user": {
              "id": 1,
              "nickname": "旅行达人",
              "avatar_url": "https://example.com/avatar2.jpg"
            },
            "created_at": "2024-01-15T11:00:00Z"
          }
        ],
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 8,
      "pages": 1
    }
  }
}
```

### 11.2 发表评论

#### 接口信息
- **接口路径**：`POST /api/v1/comments`
- **接口描述**：发表评论
- **是否需要认证**：是

#### 请求参数
```json
{
  "target_type": "travel",
  "target_id": 1,
  "content": "这个旅行计划很棒，期待参加！",
  "parent_id": null
}
```

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| target_type | string | 是 | 目标类型：travel,animal |
| target_id | integer | 是 | 目标ID |
| content | string | 是 | 评论内容 |
| parent_id | integer | 否 | 父评论ID（回复时填写） |

#### 响应示例
```json
{
  "code": 201,
  "message": "评论成功",
  "data": {
    "id": 10,
    "content": "这个旅行计划很棒，期待参加！",
    "user": {
      "id": 3,
      "nickname": "我的昵称",
      "avatar_url": "https://example.com/my_avatar.jpg"
    },
    "like_count": 0,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

## 12. 系统配置接口

### 12.1 获取小程序配置

#### 接口信息
- **接口路径**：`GET /api/v1/config/miniprogram`
- **接口描述**：获取小程序相关配置
- **是否需要认证**：否

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "app_info": {
      "name": "解班客",
      "version": "1.0.0",
      "description": "专业的旅行结伴和动物认领平台"
    },
    "features": {
      "travel_enabled": true,
      "adoption_enabled": true,
      "payment_enabled": true,
      "share_enabled": true
    },
    "upload": {
      "max_image_size": 5242880,
      "max_images_count": 9,
      "allowed_image_types": ["jpg", "jpeg", "png"]
    },
    "payment": {
      "min_amount": 0.01,
      "max_amount": 50000.00,
      "supported_methods": ["wechat"]
    },
    "contact": {
      "customer_service": "kefu001",
      "phone": "400-123-4567",
      "email": "support@jiebanke.com"
    }
  }
}
```

### 12.2 获取首页配置

#### 接口信息
- **接口路径**：`GET /api/v1/config/home`
- **接口描述**：获取首页配置信息
- **是否需要认证**：否

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "banners": [
      {
        "id": 1,
        "title": "春节特惠旅行",
        "image_url": "https://example.com/banner1.jpg",
        "link_type": "travel",
        "link_value": "1",
        "sort_order": 1
      }
    ],
    "featured_travels": [
      {
        "id": 1,
        "title": "云南大理古城深度游",
        "cover_image": "https://example.com/travel_cover.jpg",
        "destination": "云南大理"
      }
    ],
    "featured_animals": [
      {
        "id": 1,
        "name": "小花",
        "species": "cat",
        "cover_image": "https://example.com/cat_cover.jpg"
      }
    ],
    "announcements": [
      {
        "id": 1,
        "title": "平台升级公告",
        "content": "为了提供更好的服务...",
        "created_at": "2024-01-15T10:00:00Z"
      }
    ]
  }
}
```

## 13. 错误码说明

### 13.1 通用错误码

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

### 13.2 业务错误码

| 错误码 | 说明 |
|--------|------|
| 10001 | 微信授权失败 |
| 10002 | 用户信息不完整 |
| 10003 | 手机号格式错误 |
| 10004 | 用户不存在 |
| 20001 | 旅行活动不存在 |
| 20002 | 旅行活动已满员 |
| 20003 | 旅行活动已结束 |
| 20004 | 重复申请旅行活动 |
| 20005 | 不能申请自己创建的活动 |
| 30001 | 动物不存在 |
| 30002 | 动物已被认领 |
| 30003 | 重复申请认领 |
| 30004 | 认领申请不存在 |
| 40001 | 订单不存在 |
| 40002 | 订单已支付 |
| 40003 | 订单已过期 |
| 40004 | 支付失败 |
| 40005 | 退款失败 |
| 50001 | 文件上传失败 |
| 50002 | 文件格式不支持 |
| 50003 | 文件大小超限 |
| 60001 | 评论不存在 |
| 60002 | 不能删除他人评论 |

## 14. 接口测试

### 14.1 测试环境

- **测试域名**：`https://api-test.jiebanke.com`
- **文档地址**：`https://api-test.jiebanke.com/docs`
- **测试账号**：
  - 测试用户1：openid_test_001
  - 测试用户2：openid_test_002

### 14.2 测试工具

推荐使用以下工具进行接口测试：
- **Postman**：图形化接口测试工具
- **curl**：命令行测试工具
- **微信开发者工具**：小程序调试工具

### 14.3 测试示例

#### 14.3.1 登录测试
```bash
curl -X POST https://api-test.jiebanke.com/api/v1/auth/wechat/login \
  -H "Content-Type: application/json" \
  -d '{
    "code": "test_wx_code_123456"
  }'
```

#### 14.3.2 获取旅行列表测试
```bash
curl -X GET "https://api-test.jiebanke.com/api/v1/travels?page=1&size=10" \
  -H "Accept: application/json"
```

#### 14.3.3 创建旅行活动测试
```bash
curl -X POST https://api-test.jiebanke.com/api/v1/travels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "title": "测试旅行活动",
    "description": "这是一个测试活动",
    "destination": "北京",
    "start_date": "2024-03-01",
    "end_date": "2024-03-03",
    "max_participants": 5,
    "budget_min": 1000.00,
    "budget_max": 2000.00,
    "travel_type": "leisure"
  }'
```

### 14.4 Mock数据

为了方便前端开发，提供以下Mock数据接口：

- **Mock服务地址**：`https://mock.jiebanke.com`
- **数据更新频率**：每日更新
- **支持接口**：所有小程序端接口

## 15. 版本更新记录

### v1.0.0 (2024-01-15)
- 初始版本发布
- 完成用户认证、旅行结伴、动物认领、支付系统等核心功能接口
- 支持微信小程序登录和支付
- 实现文件上传、消息通知等辅助功能

### 后续版本规划

#### v1.1.0 (计划2024-02-15)
- 增加社交功能接口（关注、私信）
- 优化搜索算法和推荐系统
- 增加用户等级和积分系统

#### v1.2.0 (计划2024-03-15)
- 增加直播功能接口
- 支持多语言国际化
- 增加AI智能推荐接口

## 16. 总结

本文档详细描述了解班客小程序端的所有API接口设计，涵盖了：

### 16.1 核心功能
- **用户系统**：微信登录、用户信息管理
- **旅行结伴**：活动发布、申请、管理
- **动物认领**：动物展示、认领申请、动态更新
- **支付系统**：订单创建、微信支付集成
- **消息通知**：系统消息、业务通知

### 16.2 辅助功能
- **文件上传**：图片上传、批量处理
- **搜索功能**：综合搜索、智能建议
- **社交功能**：点赞、收藏、评论
- **系统配置**：动态配置、首页内容

### 16.3 技术特点
- **RESTful设计**：遵循REST架构原则
- **统一响应格式**：标准化的API响应
- **微信生态集成**：深度集成微信小程序能力
- **安全认证**：JWT Token + 微信授权
- **性能优化**：分页、缓存、CDN加速

### 16.4 开发支持
- **完整的错误码体系**：便于问题定位和处理
- **详细的接口文档**：包含请求参数、响应示例
- **测试环境支持**：提供测试环境和Mock数据
- **版本管理**：清晰的版本规划和更新记录

本接口设计文档将作为小程序前端开发的重要参考，确保前后端协作的高效进行。