jiebanke/docs/API_DOCS.md

# 📚 结伴客API接口文档

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

## 🔐 认证方式

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

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

## 👥 用户模块

### 微信用户登录

**Endpoint:** `POST /api/v1/auth/wechat-login`

**请求参数:**
```json
{
  "code": "string, required, 微信登录code",
  "userInfo": {
    "nickName": "string, required, 用户昵称",
    "avatarUrl": "string, required, 用户头像",
    "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"
    }
  }
}
```

**错误代码:**
- `400`: 参数验证失败
- `401`: 登录失败
- `500`: 服务器内部错误

### 获取用户信息

**Endpoint:** `GET /api/v1/users/profile`

**请求头:**
```
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": "test@jiebanke.com",
    "travelCount": 5,
    "animalClaimCount": 2,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

**错误代码:**
- `401`: 未授权访问
- `404`: 用户不存在
- `500`: 服务器内部错误

## 🧳 旅行结伴模块

### 发布旅行计划

**Endpoint:** `POST /api/v1/travel/plans`

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

**请求参数:**
```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)"
}
```

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

### 获取旅行计划列表

**Endpoint:** `GET /api/v1/travel/plans`

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

**查询参数:**
```
?page=1&limit=10&destination=大理&startDate=2024-06-01&endDate=2024-06-30
```

| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码，默认1 |
| limit | number | 每页数量，默认10 |
| destination | string | 目的地过滤 |
| startDate | string | 开始日期过滤 |
| endDate | string | 结束日期过滤 |
| budgetMin | number | 最低预算 |
| budgetMax | number | 最高预算 |

**响应示例:**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1001,
        "userId": 1,
        "userInfo": {
          "nickname": "旅行达人",
          "avatar": "https://avatar.url"
        },
        "destination": "云南大理",
        "startDate": "2024-06-01",
        "endDate": "2024-06-07",
        "budget": 2000,
        "interests": "美食,摄影,文化",
        "matchScore": 85,
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 100,
      "pages": 10
    }
  }
}
```

### 发起结伴邀请

**Endpoint:** `POST /api/v1/travel/invitations`

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

**请求参数:**
```json
{
  "travelPlanId": "number, required, 旅行计划ID",
  "inviteeId": "number, required, 被邀请用户ID",
  "message": "string, optional, 邀请消息"
}
```

**响应示例:**
```json
{
  "code": 200,
  "message": "邀请发送成功",
  "data": {
    "id": 5001,
    "travelPlanId": 1001,
    "inviterId": 1,
    "inviteeId": 2,
    "status": "pending",
    "message": "一起结伴去大理吧！",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}
```

## 🐄 动物认领模块

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

**Endpoint:** `GET /api/v1/animals/available`

**查询参数:**
```
?page=1&limit=10&species=牛&farmLocation=云南
```

| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码，默认1 |
| limit | number | 每页数量，默认10 |
| species | string | 动物种类过滤 |
| breed | string | 品种过滤 |
| farmLocation | string | 农场位置过滤 |
| priceMin | number | 最低价格 |
| priceMax | number | 最高价格 |

**响应示例:**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 2001,
        "name": "小白",
        "species": "牛",
        "breed": "荷斯坦",
        "birthDate": "2023-01-15",
        "personality": "温顺亲人",
        "farmLocation": "云南大理幸福农场",
        "price": 2999,
        "images": ["https://animal.image1.jpg", "https://animal.image2.jpg"],
        "merchantInfo": {
          "businessName": "幸福农场",
          "contactPerson": "张老板"
        },
        "claimCount": 3,
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 50,
      "pages": 5
    }
  }
}
```

### 认领动物

**Endpoint:** `POST /api/v1/animals/claim`

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

**请求参数:**
```json
{
  "animalId": "number, required, 动物ID",
  "duration": "number, required, 认领时长(月)",
  "agreementAccepted": "boolean, required, 是否接受协议"
}
```

**响应示例:**
```json
{
  "code": 200,
  "message": "认领成功",
  "data": {
    "id": 3001,
    "userId": 1,
    "animalId": 2001,
    "animalName": "小白",
    "duration": 12,
    "totalAmount": 35988,
    "status": "paid",
    "startDate": "2024-01-01",
    "endDate": "2025-01-01",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}
```

## 💐 送花服务模块

### 获取鲜花商品列表

**Endpoint:** `GET /api/v1/flower/products`

**查询参数:**
```
?page=1&limit=10&category=情人节&merchantId=1
```

| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码，默认1 |
| limit | number | 每页数量，默认10 |
| category | string | 商品分类过滤 |
| merchantId | number | 商家ID过滤 |
| priceMin | number | 最低价格 |
| priceMax | number | 最高价格 |

**响应示例:**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 4001,
        "name": "红玫瑰礼盒",
        "description": "11朵红玫瑰精美礼盒",
        "price": 199,
        "originalPrice": 259,
        "images": ["https://flower.image1.jpg"],
        "category": "情人节",
        "merchantInfo": {
          "businessName": "爱之花店",
          "contactPhone": "13800138000"
        },
        "salesCount": 150,
        "rating": 4.8,
        "status": "active",
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 100,
      "pages": 10
    }
  }
}
```

### 下单送花

**Endpoint:** `POST /api/v1/flower/orders`

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

**请求参数:**
```json
{
  "productId": "number, required, 商品ID",
  "quantity": "number, required, 数量",
  "recipientInfo": {
    "name": "string, required, 收花人姓名",
    "phone": "string, required, 收花人电话",
    "address": "string, required, 配送地址"
  },
  "deliveryDate": "string, required, 配送日期(YYYY-MM-DD)",
  "message": "string, optional, 祝福语"
}
```

**响应示例:**
```json
{
  "code": 200,
  "message": "下单成功",
  "data": {
    "id": 5001,
    "orderNo": "FLOWER202401010001",
    "productId": 4001,
    "productName": "红玫瑰礼盒",
    "quantity": 1,
    "totalAmount": 199,
    "recipientName": "李小姐",
    "recipientPhone": "13800138001",
    "deliveryAddress": "北京市朝阳区xxx路xxx号",
    "deliveryDate": "2024-02-14",
    "status": "pending",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}
```

## 📊 数据字典

### 旅行计划状态
| 状态值 | 描述 |
|--------|------|
| active | 活跃中 |
| completed | 已完成 |
| cancelled | 已取消 |

### 结伴邀请状态
| 状态值 | 描述 |
|--------|------|
| pending | 待接受 |
| accepted | 已接受 |
| rejected | 已拒绝 |
| cancelled | 已取消 |

### 动物认领状态
| 状态值 | 描述 |
|--------|------|
| pending | 待支付 |
| paid | 已支付 |
| active | 认领中 |
| completed | 已完成 |
| cancelled | 已取消 |

### 送花订单状态
| 状态值 | 描述 |
|--------|------|
| pending | 待支付 |
| paid | 已支付 |
| confirmed | 商家已确认 |
| delivering | 配送中 |
| completed | 已完成 |
| cancelled | 已取消 |

### 错误代码
| 代码 | 描述 |
|------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权访问 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 409 | 资源冲突 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |
| 503 | 服务不可用 |

## 🔗 API 版本控制

当前API版本为v1，所有接口前缀为`/api/v1/`。

版本更新策略：
- 向后兼容的修改直接更新
- 不兼容的修改创建新版本v2
- 旧版本API保持维护至少6个月

## 📡 接口限流

### 限流策略
- 匿名用户: 60请求/分钟
- 认证用户: 120请求/分钟
- VIP用户: 300请求/分钟

### 限流响应
当超过限流阈值时返回：
```json
{
  "code": 429,
  "message": "请求过于频繁，请稍后再试",
  "retryAfter": 60
}
```

## 🧪 接口测试

### 使用curl测试
```bash
# 微信用户登录
curl -X POST https://api.jiebanke.com/api/v1/auth/wechat-login \
  -H "Content-Type: application/json" \
  -d '{"code":"wxlogincode123","userInfo":{"nickName":"测试用户","avatarUrl":"https://avatar.url","gender":1}}'

# 获取旅行计划列表
curl -X GET https://api.jiebanke.com/api/v1/travel/plans \
  -H "Authorization: Bearer <token>"
```

### 使用Postman测试
1. 导入Postman集合文件
2. 设置环境变量（base_url, token等）
3. 运行测试用例

## 📝 更新日志

### v1.0.0 (2024-01-01)
- 微信用户登录接口
- 旅行结伴管理接口
- 动物认领管理接口
- 送花服务接口
- 基础认证系统

---
*最后更新: 2024年* 📅