jiebanke/docs/API接口文档.md

# 📚 结伴客API接口文档

## 📋 文档说明

本文档详细描述了结伴客项目的所有API接口，包括请求参数、响应格式和错误代码。结伴客是一个专注于结伴旅行和动物认领的社交平台。

**基础信息：**
- 基础URL：`https://api.jiebanke.com`
- API版本：`v1`
- 数据格式：`JSON`
- 字符编码：`UTF-8`

## 🔐 认证方式

### JWT Token 认证
所有需要认证的API必须在请求头中携带Token：
```http
Authorization: Bearer <your_jwt_token>
```

### Token 获取
通过微信登录接口获取Token，Token有效期为7天。

## 📊 通用响应格式

### 成功响应
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据内容
  }
}
```

### 错误响应
```json
{
  "code": 400,
  "message": "错误描述",
  "error": "详细错误信息"
}
```

### 状态码说明
- `200`: 请求成功
- `400`: 请求参数错误
- `401`: 未授权访问
- `403`: 权限不足
- `404`: 资源不存在
- `500`: 服务器内部错误

## 👥 用户管理模块

### 微信用户登录

**接口地址：** `POST /api/v1/auth/wechat-login`

**接口描述：** 用户通过微信授权登录系统

**请求参数：**
```json
{
  "code": "string, required, 微信登录授权码",
  "userInfo": {
    "nickName": "string, required, 用户昵称",
    "avatarUrl": "string, required, 用户头像URL",
    "gender": "number, optional, 性别(0:未知,1:男,2:女)",
    "province": "string, optional, 省份",
    "city": "string, optional, 城市"
  }
}
```

**响应示例：**
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "openid": "wx1234567890",
      "nickname": "旅行达人",
      "avatar": "https://avatar.url",
      "gender": "male",
      "phone": "13800138000",
      "isNewUser": false
    }
  }
}
```

### 获取用户信息

**接口地址：** `GET /api/v1/users/profile`

**接口描述：** 获取当前登录用户的详细信息

**请求头：**
```http
Authorization: Bearer <token>
```

**响应示例：**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "openid": "wx1234567890",
    "nickname": "旅行达人",
    "avatar": "https://avatar.url",
    "gender": "male",
    "birthday": "1990-01-01",
    "phone": "13800138000",
    "email": "user@jiebanke.com",
    "travelCount": 5,
    "animalClaimCount": 2,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 更新用户信息

**接口地址：** `PUT /api/v1/users/profile`

**接口描述：** 更新用户个人信息

**请求参数：**
```json
{
  "nickname": "string, optional, 用户昵称",
  "avatar": "string, optional, 头像URL",
  "birthday": "string, optional, 生日(YYYY-MM-DD)",
  "phone": "string, optional, 手机号码",
  "email": "string, optional, 邮箱地址",
  "interests": "array, optional, 兴趣爱好标签"
}
```

## 🧳 旅行结伴模块

### 发布旅行计划

**接口地址：** `POST /api/v1/travel/plans`

**接口描述：** 用户发布新的旅行计划

**请求参数：**
```json
{
  "destination": "string, required, 目的地",
  "startDate": "string, required, 开始日期(YYYY-MM-DD)",
  "endDate": "string, required, 结束日期(YYYY-MM-DD)",
  "budget": "number, optional, 预算金额",
  "interests": "string, optional, 兴趣偏好",
  "description": "string, optional, 行程描述",
  "visibility": "string, optional, 可见性(public/friends/private)",
  "maxParticipants": "number, optional, 最大参与人数"
}
```

**响应示例：**
```json
{
  "code": 200,
  "message": "旅行计划发布成功",
  "data": {
    "id": 1001,
    "userId": 1,
    "destination": "云南大理",
    "startDate": "2024-06-01",
    "endDate": "2024-06-07",
    "budget": 2000,
    "interests": "美食,摄影,文化",
    "status": "active",
    "participantCount": 1,
    "maxParticipants": 4,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 获取旅行计划列表

**接口地址：** `GET /api/v1/travel/plans`

**接口描述：** 获取旅行计划列表，支持筛选和分页

**查询参数：**
```
page: number, optional, 页码(默认1)
limit: number, optional, 每页数量(默认10)
destination: string, optional, 目的地筛选
startDate: string, optional, 开始日期筛选
endDate: string, optional, 结束日期筛选
budget: number, optional, 预算筛选
status: string, optional, 状态筛选(active/completed/cancelled)
```

**响应示例：**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "plans": [
      {
        "id": 1001,
        "user": {
          "id": 1,
          "nickname": "旅行达人",
          "avatar": "https://avatar.url"
        },
        "destination": "云南大理",
        "startDate": "2024-06-01",
        "endDate": "2024-06-07",
        "budget": 2000,
        "participantCount": 2,
        "maxParticipants": 4,
        "status": "active"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3
    }
  }
}
```

### 申请加入旅行计划

**接口地址：** `POST /api/v1/travel/plans/{planId}/join`

**接口描述：** 申请加入指定的旅行计划

**请求参数：**
```json
{
  "message": "string, optional, 申请留言"
}
```

## 🐄 动物认领模块

### 获取可认领动物列表

**接口地址：** `GET /api/v1/animals/available`

**接口描述：** 获取可认领的动物列表

**查询参数：**
```
type: string, optional, 动物类型(cow/sheep/pig/chicken)
farmId: number, optional, 农场ID筛选
page: number, optional, 页码
limit: number, optional, 每页数量
```

**响应示例：**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "animals": [
      {
        "id": 2001,
        "name": "小花牛",
        "type": "cow",
        "age": 6,
        "gender": "female",
        "description": "温顺可爱的小花牛",
        "images": ["https://image1.url", "https://image2.url"],
        "price": 1200,
        "farm": {
          "id": 101,
          "name": "阳光农场",
          "location": "四川成都"
        },
        "status": "available"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 15
    }
  }
}
```

### 认领动物

**接口地址：** `POST /api/v1/animals/{animalId}/claim`

**接口描述：** 认领指定的动物

**请求参数：**
```json
{
  "duration": "number, required, 认领时长(月)",
  "message": "string, optional, 认领留言"
}
```

### 获取我的认领记录

**接口地址：** `GET /api/v1/animals/my-claims`

**接口描述：** 获取当前用户的动物认领记录

## 🏪 商家服务模块

### 商家注册

**接口地址：** `POST /api/v1/merchants/register`

**接口描述：** 商家用户注册

**请求参数：**
```json
{
  "businessName": "string, required, 商家名称",
  "businessType": "string, required, 商家类型(flower_shop/farm/activity_organizer)",
  "contactName": "string, required, 联系人姓名",
  "contactPhone": "string, required, 联系电话",
  "businessLicense": "string, required, 营业执照号",
  "address": "string, required, 经营地址",
  "description": "string, optional, 商家描述"
}
```

### 获取商家产品列表

**接口地址：** `GET /api/v1/merchants/{merchantId}/products`

**接口描述：** 获取指定商家的产品列表

## 📦 订单管理模块

### 创建订单

**接口地址：** `POST /api/v1/orders`

**接口描述：** 创建新订单

**请求参数：**
```json
{
  "type": "string, required, 订单类型(animal_claim/product_purchase/activity_booking)",
  "items": [
    {
      "itemId": "number, required, 商品/服务ID",
      "quantity": "number, required, 数量",
      "price": "number, required, 单价"
    }
  ],
  "totalAmount": "number, required, 总金额",
  "deliveryAddress": "object, optional, 配送地址信息"
}
```

### 获取订单列表

**接口地址：** `GET /api/v1/orders`

**接口描述：** 获取用户订单列表

**查询参数：**
```
status: string, optional, 订单状态筛选
type: string, optional, 订单类型筛选
page: number, optional, 页码
limit: number, optional, 每页数量
```

## 🎯 活动管理模块

### 获取活动列表

**接口地址：** `GET /api/v1/activities`

**接口描述：** 获取活动列表

**查询参数：**
```
type: string, optional, 活动类型
location: string, optional, 地点筛选
date: string, optional, 日期筛选
status: string, optional, 状态筛选
```

### 报名参加活动

**接口地址：** `POST /api/v1/activities/{activityId}/register`

**接口描述：** 报名参加指定活动

## 💬 消息通知模块

### 获取消息列表

**接口地址：** `GET /api/v1/messages`

**接口描述：** 获取用户消息列表

### 发送消息

**接口地址：** `POST /api/v1/messages`

**接口描述：** 发送消息给其他用户

## 🔧 系统管理模块

### 获取系统配置

**接口地址：** `GET /api/v1/system/config`

**接口描述：** 获取系统配置信息

### 文件上传

**接口地址：** `POST /api/v1/upload`

**接口描述：** 上传文件（图片、文档等）

**请求格式：** `multipart/form-data`

**请求参数：**
```
file: File, required, 上传的文件
type: string, optional, 文件类型(avatar/product/document)
```

## 📱 错误代码参考

| 错误代码 | 错误描述 | 解决方案 |
|---------|---------|---------|
| 400 | 请求参数错误 | 检查请求参数格式和必填项 |
| 401 | 未授权访问 | 检查Token是否有效 |
| 403 | 权限不足 | 检查用户权限 |
| 404 | 资源不存在 | 检查请求的资源ID |
| 409 | 资源冲突 | 检查是否重复操作 |
| 429 | 请求频率限制 | 降低请求频率 |
| 500 | 服务器内部错误 | 联系技术支持 |

## 📞 技术支持

如有API使用问题，请联系技术支持：
- 邮箱：tech-support@jiebanke.com
- 微信群：结伴客开发者群

---

*文档版本：v1.0*  
*最后更新：2025年1月*