jiebanke/docs/api-documentation.md

# 结伴客系统 API 接口文档

## 基础信息

**Base URL**: `http://localhost:3000/api/v1`

**认证方式**: Bearer Token (JWT)

**响应格式**: JSON

## 响应格式

### 成功响应
```json
{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据
  },
  "timestamp": "2025-01-01T00:00:00.000Z"
}
```

### 错误响应
```json
{
  "success": false,
  "code": 400,
  "message": "错误信息",
  "error": "详细错误描述",
  "timestamp": "2025-01-01T00:00:00.000Z"
}
```

## 认证接口

### 1. 用户注册

**Endpoint**: `POST /auth/register`

**描述**: 创建新用户账号

**请求体**:
```json
{
  "username": "string, required, 用户名(4-20字符)",
  "password": "string, required, 密码(6-20字符)",
  "nickname": "string, optional, 昵称",
  "email": "string, optional, 邮箱",
  "phone": "string, optional, 手机号",
  "gender": "string, optional, 性别(male/female/unknown)",
  "birthday": "string, optional, 生日(YYYY-MM-DD)"
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "注册成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "13800138000",
      "avatar": "",
      "gender": "unknown",
      "points": 0,
      "level": 1,
      "status": "active",
      "created_at": "2025-01-01T00:00:00.000Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

### 2. 用户登录

**Endpoint**: `POST /auth/login`

**描述**: 用户登录获取访问令牌

**请求体**:
```json
{
  "username": "string, required, 用户名/邮箱/手机号",
  "password": "string, required, 密码"
}
```

### 2.1 微信登录

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

**描述**: 微信授权登录

**请求体**:
```json
{
  "code": "string, required, 微信授权码",
  "userInfo": {
    "nickName": "string, optional, 微信昵称",
    "avatarUrl": "string, optional, 微信头像",
    "gender": "number, optional, 性别(0:未知,1:男,2:女)"
  }
}
```

**响应**: 同登录接口

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "登录成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "13800138000",
      "avatar": "",
      "gender": "unknown",
      "points": 100,
      "level": 2,
      "status": "active",
      "last_login_at": "2025-01-01T00:00:00.000Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

### 3. 微信登录

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

**描述**: 微信授权登录

**请求体**:
```json
{
  "code": "string, required, 微信授权码",
  "userInfo": {
    "nickName": "string, optional, 微信昵称",
    "avatarUrl": "string, optional, 微信头像",
    "gender": "number, optional, 性别(0:未知,1:男,2:女)"
  }
}
```

**响应**: 同登录接口

### 4. 获取当前用户信息

**Endpoint**: `GET /auth/me`

**认证**: 需要Bearer Token

**描述**: 获取当前登录用户信息

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "13800138000",
      "avatar": "https://example.com/avatar.jpg",
      "gender": "male",
      "birthday": "1990-01-01",
      "points": 1000,
      "level": 3,
      "balance": 500.00,
      "travel_count": 5,
      "animal_adopt_count": 2,
      "flower_order_count": 3,
      "status": "active",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z",
      "last_login_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

### 5. 更新用户信息

**Endpoint**: `PUT /auth/profile`

**认证**: 需要Bearer Token

**描述**: 更新用户个人信息

**请求体**:
```json
{
  "nickname": "string, optional, 昵称",
  "avatar": "string, optional, 头像URL",
  "gender": "string, optional, 性别(male/female/unknown)",
  "birthday": "string, optional, 生日(YYYY-MM-DD)"
}
```

**响应**: 同获取用户信息接口

### 6. 修改密码

**Endpoint**: `PUT /auth/password`

**认证**: 需要Bearer Token

**描述**: 修改用户密码

**请求体**:
```json
{
  "currentPassword": "string, required, 当前密码",
  "newPassword": "string, required, 新密码(6-20字符)"
}
```

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "密码修改成功"
}
```

## 用户接口

### 1. 获取用户列表

**Endpoint**: `GET /users`

**认证**: 需要Bearer Token (管理员权限)

**查询参数**:
- `page`: number, optional, 页码 (默认: 1)
- `pageSize`: number, optional, 每页数量 (默认: 20)
- `search`: string, optional, 搜索关键词
- `status`: string, optional, 状态过滤(active/inactive/banned)

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "users": [
      {
        "id": 1,
        "username": "user1",
        "nickname": "用户1",
        "email": "user1@example.com",
        "phone": "13800138001",
        "status": "active",
        "level": 2,
        "created_at": "2025-01-01极速版T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "pageSize": 20,
      "totalPages": 5
    }
  }
}
```

### 2. 获取用户详情

**Endpoint**: `GET /users/:id`

**认证**: 需要Bearer Token

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "13800138000",
      "avatar": "https://example.com/avatar.jpg",
      "gender": "male",
      "points": 1000,
      "level": 3,
      "status": "active",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

## 旅行接口

### 1. 创建旅行计划

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

**认证**: 需要Bearer Token

**请求体**:
```json
{
  "destination": "string, required, 目的地",
  "start_date": "string, required, 开始日期(YYYY-MM-DD)",
  "end_date": "string, required, 结束日期(YYYY-MM-DD)",
  "budget": "number, required, 预算",
  "interests": "string, optional, 兴趣偏好",
  "visibility": "string, optional, 可见范围(public/friends/private)"
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "旅行计划创建成功",
  "data": {
    "plan": {
      "id": 1,
      "title": "西藏自驾游",
      "description": "寻找志同道合的旅友一起探索西藏",
      "destination": "西藏",
      "start_date": "2025-07-01",
      "end_date": "2025-07-15",
      "budget": 5000,
      "max_members": 4,
      "current_members": 1,
      "status": "recruiting",
      "tags": ["自驾", "摄影", "探险"],
      "creator_id": 1,
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

### 2. 获取旅行计划列表

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

**查询参数**:
- `page`: number, optional, 页码
- `pageSize`: number, optional, 每页数量
- `destination`: string, optional, 目的地搜索
- `start_date`: string, optional, 开始日期之后
- `end_date`: string, optional, 结束日期之前
- `status`: string, optional, 状态(recruiting/in_progress/completed/cancelled)
- `tags`: string, optional, 标签过滤(多个用逗号分隔)

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "plans": [
      {
        "id": 1,
        "destination": "西藏",
        "start_date": "2025-07-01",
        "end_date": "2025-07-15",
        "budget": 5000.00,
        "interests": "自驾,摄影,探险",
        "visibility": "public",
        "creator": {
          "id": 1,
          "nickname": "旅行达人",
          "avatar": "https://example.com/avatar.jpg"
        },
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "pageSize": 20,
      "totalPages": 3
    }
  }
}
```

### 3. 匹配旅行伙伴

**Endpoint**: `GET /travel/matches`

**认证**: 需要Bearer Token

**查询参数**:
- `plan_id`: number, required, 旅行计划ID
- `page`: number, optional, 页码
- `pageSize`: number, optional, 每页数量

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "list": [
      {
        "id": 2,
        "destination": "西藏",
        "start_date": "2025-07-02",
        "end_date": "2025-07-08",
        "budget": 4500.00,
        "interests": "徒步,美食",
        "match_score": 0.85,
        "user": {
          "id": 2,
          "nickname": "旅行伙伴",
          "avatar": "https://example.com/avatar2.jpg"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 1
    }
  }
}
```

## 动物认领接口

### 1. 发布动物认领

**Endpoint**: `POST /animals`

**认证**: 需要Bearer Token

**请求体**:
```json
{
  "name": "string, required, 动物名称",
  "species": "string, required, 物种",
  "breed": "string, optional, 品种",
  "age": "number, optional, 年龄",
  "gender": "string, optional, 性别(male/female/unknown)",
  "description": "string, required, 描述",
  "location": "string, required, 位置",
  "images": "array, optional, 图片URL数组",
  "vaccination_status": "string, optional, 疫苗接种情况",
  "sterilization_status": "string, optional, 绝育情况"
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "动物认领发布成功",
  "data": {
    "animal": {
      "id": 1,
      "name": "小白",
      "species": "猫",
      "breed": "中华田园猫",
      "age": 2,
      "gender": "male",
      "description": "非常温顺的猫咪，寻找有爱心的主人",
      "location": "北京市朝阳区",
      "status": "available",
      "images": ["https://example.com/cat1.jpg"],
      "creator_id": 1,
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

## 商家服务接口

### 1. 商家注册

**Endpoint**: `POST /merchants/register`

**认证**: 需要Bearer Token

**请求体**:
```json
{
  "merchant_type": "string, required, 商家类型(flower_shop/activity_organizer/farm_owner)",
  "business_name": "string, required, 商家名称",
  "business_license": "string, optional, 营业执照URL",
  "contact_person": "string, required, 联系人",
  "contact_phone": "string, required, 联系电话",
  "address": "string, optional, 地址",
  "description": "string, optional, 商家介绍"
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "商家注册申请已提交",
  "data": {
    "merchant": {
      "id": 1,
      "user_id": 1,
      "merchant_type": "farm_owner",
      "business_name": "XX农场",
      "business_license": "https://example.com/license.jpg",
      "contact_person": "张三",
      "contact_phone": "13800138000",
      "address": "北京市朝阳区XX路XX号",
      "description": "专业养殖羊驼的农场",
      "status": "pending",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

### 2. 发布商品/服务

**Endpoint**: `POST /merchants/products`

**认证**: 需要Bearer Token

**请求体**:
```json
{
  "name": "string, required, 商品名称",
  "description": "string, required, 商品描述",
  "price": "number, required, 价格",
  "image_url": "string, optional, 图片URL",
  "category": "string, required, 商品类别",
  "status": "string, optional, 状态(available/unavailable)"
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "商品发布成功",
  "data": {
    "product": {
      "id": 1,
      "merchant_id": 1,
      "name": "羊驼认领体验",
      "description": "提供一个月的羊驼认领体验服务",
      "price": 1000.00,
      "image_url": "https://example.com/product.jpg",
      "category": "animal_claim",
      "status": "available",
      "created_at": "202极速版5-01-01T00:00:00.000Z"
    }
  }
}
```

### 3. 获取商家订单

**Endpoint**: `GET /merchants/orders`

**认证**: 需要Bearer Token

**查询参数**:
- `page`: number, optional, 页码
- `pageSize`: number, optional, 每页数量
- `status`: string, optional, 订单状态

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "orders": [
      {
        "id": 1,
        "user_id": 2,
        "order_number": "ORD202501010001",
        "total_amount": 1000.00,
        "status": "paid",
        "ordered_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "pageSize": 20,
      "totalPages": 3
    }
  }
}
```

## 鲜花订购接口

### 1. 创建鲜花订单

**Endpoint**: `POST /flowers/orders`

**认证**: 需要Bearer Token

**请求体**:
```json
{
  "product_id": "number, required, 商品ID",
  "quantity": "number, required, 数量",
  "recipient_name": "string, required, 收花人姓名",
  "recipient_phone": "string, required, 收花人电话",
  "delivery_address": "string, required, 配送地址",
  "delivery_date": "string, required, 配送日期(YYYY-MM-DD)",
  "delivery_time": "string, required, 配送时间段",
  "message": "string, optional, 祝福语",
  "special_instructions": "string, optional, 特殊说明"
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "订单创建成功",
  "data": {
    "order": {
      "极速版id": 1,
      "order_number": "F202501010001",
      "product_id": 1,
      "quantity": 1,
      "total_amount": 199.00,
      "status": "pending",
      "recipient_name": "张三",
      "recipient_phone": "13800138000",
      "delivery_address": "北京市朝阳区xxx路xxx号",
      "delivery_date": "2025-01-01",
      "delivery_time": "09:00-12:00",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

## 推广奖励接口

### 1. 获取推广链接

**Endpoint**: `GET /promotion/link`

**认证**: 需要Bearer Token

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "promotion_link": "https://example.com/promotion?ref=user123",
    "qr_code": "https://example.com/qrcode.png"
  }
}
```

### 2. 获取推广数据

**Endpoint**: `GET /promotion/stats`

**认证**: 需要Bearer Token

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "total_referrals": 50,
    "successful_registrations": 25,
    "total_rewards": 500.00,
    "available_rewards": 300.00,
    "withdrawn_rewards": 200.00
  }
}
```

### 3. 申请提现

**Endpoint**: `POST /promotion/withdraw`

**认证**: 需要Bearer Token

**请求体**:
```json
{
  "amount": "number, required, 提现金额",
  "payment_method": "string, required, 支付方式(wechat/alipay)"
}
```

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "提现申请已提交",
  "data": {
    "withdrawal_id": "WD202501010001",
    "status": "processing"
  }
}
```

## 系统接口

### 1. 健康检查

**Endpoint**: `GET /health`

**描述**: 检查服务健康状态

**响应**:
```json
{
  "status": "OK",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "uptime": 12345.67,
  "environment": "development",
  "services": {
    "database": "connected",
    "redis": "disconnected",
    "rabbitmq": "disconnected"
  }
}
```

## 官网接口

### 1. 提交商家入驻申请

**Endpoint**: `POST /website/merchant/apply`

**请求体**:
```json
{
  "business_name": "string, required, 商家名称",
  "contact_person": "string, required, 联系人",
  "contact_phone": "string, required, 联系电话",
  "email": "string, optional, 邮箱",
  "description": "string, optional, 商家描述"
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "入驻申请已提交",
  "data": {
    "application_id": 1,
    "status": "pending"
  }
}
```

### 2. 获取成功案例列表

**Endpoint**: `GET /website/cases`

**查询参数**:
- `page`: number, optional, 页码
- `pageSize`: number, optional, 每页数量

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "cases": [
      {
        "id": 1,
        "title": "XX农场成功入驻案例",
        "description": "XX农场通过平台实现了数字化转型",
        "image_url": "https://example.com/case1.jpg",
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "pageSize": 20,
      "totalPages": 3
    }
  }
}
```

## 错误码说明

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 200 | 成功 | 操作成功 |
| 201 | 创建成功 | 资源创建成功 |
| 400 | 请求错误 | 检查请求参数 |
| 401 | 未授权 | 需要登录认证 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 资源不存在 | 检查资源ID |
| 409 | 资源冲突 | 资源已存在 |
| 429 | 请求过多 | 降低请求频率 |
| 500 | 服务器错误 | 联系管理员 |

## 版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2025-01-01 | 初始版本发布 |
| v1.1 | 2025-02-01 | 新增微信登录接口 |
| v1.2 | 2025-03-01 | 优化错误处理机制 |

## 注意事项

1. 所有时间格式均为 ISO 8601 格式 (YYYY-MM-DDTHH:mm:ss.sssZ)
2. 金额单位为元，保留两位小数
3. 图片URL需要支持HTTPS
4. 敏感操作需要二次验证
5. API调用频率限制为每分钟100次