jiebanke/docs/api-documentation.md

# 结伴客系统 API 接口文档

## 基础信息

**Base URL**: `https://www.jiebanke.com/api/v1`

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

**响应格式**: JSON

**API版本**: v1

**开发状态**: 开发中

## 响应格式

### 成功响应
```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"
}
```

## 通用状态码

| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 401 | 未授权访问 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |

## 认证接口

### 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@jiebanke.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, 密码"
}
```

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "登录成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@jiebanke.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**: `GET /auth/me`

**认证**: 需要Bearer Token

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

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@jiebanke.com",
      "phone": "13800138000",
      "avatar": "https://www.jiebanke.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"
    }
  }
}
```

### 4. 更新用户信息

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

**认证**: 需要Bearer Token

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

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

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "用户信息更新成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "新昵称",
      "avatar": "https://www.jiebanke.com/new-avatar.jpg",
      "gender": "male",
      "birthday": "1990-01-01",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

### 5. 微信登录

**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": "测试用户",
      "avatar": "https://www.jiebanke.com/avatar.jpg",
      "gender": "male",
      "points": 100,
      "level": 2,
      "status": "active",
      "last_login_at": "2025-01-01T00:00:00.000Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

### 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://www.jiebanke.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"
    }
  }
}
```

### 6. 更新用户信息

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

**认证**: 需要Bearer Token

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

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

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "用户信息更新成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "新昵称",
      "avatar": "https://example.com/new-avatar.jpg",
      "gender": "male",
      "birthday": "1990-01-01",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

## 用户服务接口

### 1. 获取用户列表

**Endpoint**: `GET /users`

**认证**: 需要Bearer Token

**描述**: 获取用户列表（管理员权限）

**查询参数**:
- `page` (可选): 页码，默认1
- `limit` (可选): 每页数量，默认20
- `username` (可选): 用户名模糊搜索
- `status` (可选): 状态过滤

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "users": [
      {
        "id": 1,
        "username": "testuser",
        "nickname": "测试用户",
        "email": "test@example.com",
        "phone": "13800138000",
        "avatar": "https://www.jiebanke.com/avatar.jpg",
        "gender": "male",
        "points": 100,
        "level": 2,
        "status": "active",
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 20,
      "pages": 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://www.jiebanke.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"
    }
  }
}
```

## 8. 管理员接口

### 8.1 管理员登录
- **Endpoint**: POST /api/v1/admin/login
- **认证要求**: 无
- **描述**: 管理员登录系统
- **请求体**:
```json
{
  "username": "admin",
  "password": "password123"
}
```
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "admin": {
      "id": 1,
      "username": "admin",
      "email": "admin@jiebanke.com",
      "nickname": "超级管理员",
      "avatar": "https://example.com/avatar.jpg",
      "role": "super_admin",
      "status": 1,
      "last_login": "2024-01-15T10:30:00.000Z"
    }
  }
}
```

### 8.2 获取管理员信息
- **Endpoint**: GET /api/v1/admin/profile
- **认证要求**: Bearer Token
- **描述**: 获取当前登录管理员信息
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "nickname": "超级管理员",
    "avatar": "https://example.com/avatar.jpg",
    "role": "super_admin",
    "status": 1,
    "last_login": "2024-01-15T10:30:00.000Z",
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}
```

### 8.3 更新管理员信息
- **Endpoint**: PUT /api/v1/admin/profile
- **认证要求**: Bearer Token
- **描述**: 更新当前登录管理员信息
- **请求体**:
```json
{
  "nickname": "新昵称",
  "email": "newemail@example.com",
  "avatar": "https://example.com/new-avatar.jpg"
}
```
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "newemail@example.com",
    "nickname": "新昵称",
    "avatar": "https://example.com/new-avatar.jpg",
    "role": "super_admin",
    "status": 1
  }
}
```

### 8.4 修改密码
- **Endpoint**: PUT /api/v1/admin/password
- **认证要求**: Bearer Token
- **描述**: 修改当前登录管理员密码
- **请求体**:
```json
{
  "old_password": "oldpassword123",
  "new_password": "newpassword456"
}
```
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "密码修改成功"
}
```

### 7. 获取管理员信息

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

**认证**: 需要Bearer Token

**描述**: 获取当前登录管理员信息及权限

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@jiebanke.com",
      "real_name": "管理员",
      "avatar": "",
      "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"
    },
    "roles": [
      {
        "id": 2,
        "name": "admin",
        "description": "普通管理员"
      }
    ],
    "permissions": [
      "user:manage",
      "content:review",
      "content:publish",
      "data:view",
      "data:export"
    ]
  }
}
```

### 9. 管理员后台接口

#### 9.1 用户管理接口

##### 9.1.1 获取用户列表
- **Endpoint**: GET /api/v1/admin/users
- **认证要求**: Bearer Token，需要user:manage权限
- **查询参数**:
  - `page` (可选): 页码，默认1
  - `limit` (可选): 每页数量，默认20
  - `username` (可选): 用户名模糊搜索
  - `user_type` (可选): 用户类型过滤（normal/merchant/farmer/organizer）
  - `status` (可选): 状态过滤（active/inactive/banned）
  - `start_date` (可选): 注册开始时间
  - `end_date` (可选): 注册结束时间
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "users": [
      {
        "id": 1,
        "username": "testuser",
        "nickname": "测试用户",
        "email": "test@example.com",
        "phone": "13800138000",
        "user_type": "normal",
        "status": "active",
        "points": 100,
        "level": 2,
        "travel_count": 5,
        "animal_adopt_count": 2,
        "flower_order_count": 3,
        "created_at": "2025-01-01T00:00:00.000Z",
        "last_login_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 20,
      "pages": 5
    },
    "statistics": {
      "total_users": 100,
      "active_users": 80,
      "new_users_today": 5,
      "merchant_users": 15,
      "farmer_users": 10
    }
  }
}
```

##### 9.1.2 获取用户详情
- **Endpoint**: GET /api/v1/admin/users/{id}
- **认证要求**: Bearer Token，需要user:manage权限
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "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",
      "user_type": "normal",
      "status": "active",
      "points": 1000,
      "level": 3,
      "balance": 500.00,
      "travel_count": 5,
      "animal_adopt_count": 2,
      "flower_order_count": 3,
      "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"
    },
    "activity_stats": {
      "last_7_days_login_count": 5,
      "total_travel_plans": 3,
      "total_animal_claims": 2,
      "total_flower_orders": 1
    }
  }
}
```

##### 9.1.3 更新用户状态
- **Endpoint**: PUT /api/v1/admin/users/{id}/status
- **认证要求**: Bearer Token，需要user:manage权限
- **请求体**:
```json
{
  "status": "banned",
  "reason": "违反平台规则"
}
```
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "用户状态更新成功"
}
```

##### 9.1.4 导出用户数据
- **Endpoint**: GET /api/v1/admin/users/export
- **认证要求**: Bearer Token，需要user:manage权限
- **查询参数**:
  - `format` (可选): 导出格式（csv/excel），默认csv
  - `start_date` (可选): 注册开始时间
  - `end_date` (可选): 注册结束时间
  - `user_type` (可选): 用户类型过滤
- **响应**: 返回文件下载流

#### 9.2 商家审核接口

##### 9.2.1 获取待审核商家列表
- **Endpoint**: GET /api/v1/admin/merchants/pending
- **认证要求**: Bearer Token，需要merchant:review权限
- **查询参数**:
  - `page` (可选): 页码，默认1
  - `limit` (可选): 每页数量，默认20
  - `merchant_type` (可选): 商家类型（flower_shop/farm/activity_organizer）
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "merchants": [
      {
        "id": 1,
        "user_id": 2,
        "shop_name": "鲜花小店",
        "merchant_type": "flower_shop",
        "contact_name": "张老板",
        "contact_phone": "13800138001",
        "business_license": "https://www.jiebanke.com/license.jpg",
        "status": "pending",
        "apply_reason": "希望加入平台提供鲜花服务",
        "created_at": "2025-01-01T00:00:00.000Z",
        "user_info": {
          "username": "merchant1",
          "nickname": "花店老板",
          "email": "merchant@jiebanke.com"
        }
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}
```

##### 9.2.2 审核商家申请
- **Endpoint**: POST /api/v1/admin/merchants/{id}/review
- **认证要求**: Bearer Token，需要merchant:review权限
- **请求体**:
```json
{
  "action": "approve",
  "review_notes": "资质齐全，符合要求",
  "reject_reason": ""
}
```
或者
```json
{
  "action": "reject",
  "review_notes": "营业执照不清晰",
  "reject_reason": "营业执照图片模糊，无法辨认"
}
```
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "商家审核完成"
}
```

##### 9.2.3 获取商家列表
- **Endpoint**: GET /api/v1/admin/merchants
- **认证要求**: Bearer Token，需要merchant:manage权限
- **查询参数**:
  - `page` (可选): 页码，默认1
  - `limit` (可选): 每页数量，默认20
  - "shop_name" (可选): 店铺名称模糊搜索
  - "merchant_type" (可选): 商家类型
  - "status" (可选): 状态（active/inactive/rejected）
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "merchants": [
      {
        "id": 1,
        "user_id": 2,
        "shop_name": "鲜花小店",
        "merchant_type": "flower_shop",
        "contact_name": "张老板",
        "contact_phone": "13800138001",
        "business_license": "https://www.jiebanke.com/license.jpg",
        "status": "active",
        "total_products": 15,
        "total_orders": 120,
        "total_revenue": 5000.00,
        "avg_rating": 4.8,
        "created_at": "2025-01-01T00:00:00.000Z",
        "approved_at": "2025-01-02T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "limit": 20,
      "pages": 3
    },
    "statistics": {
      "total_merchants": 50,
      "active_merchants": 45,
      "flower_shops": 20,
      "farms": 15,
      "organizers": 15,
      "pending_reviews": 5
    }
  }
}
```

#### 9.3 内容审核接口

##### 9.3.1 获取待审核内容列表
- **Endpoint**: GET /api/v1/admin/content/pending
- **认证要求**: Bearer Token，需要content:review权限
- **查询参数**:
  - `page` (可选): 页码，默认1
  - `limit` (可选): 每页数量，默认20
  - `content_type` (可选): 内容类型（travel_plan/dynamic/comment）
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "contents": [
      {
        "id": 1,
        "type": "travel_plan",
        "title": "云南大理之旅",
        "content": "计划去大理游玩5天，寻找同行伙伴...",
        "author_id": 3,
        "author_name": "旅行爱好者",
        "status": "pending",
        "created_at": "2025-01-01T00:00:00.000Z",
        "review_count": 0
      },
      {
        "id": 2,
        "type": "dynamic", 
        "title": "",
        "content": "今天认领了一只可爱的小羊！",
        "images": ["https://www.jiebanke.com/sheep.jpg"],
        "author_id": 4,
        "author_name": "动物爱好者",
        "status": "pending",
        "created_at": "2025-01-01T00:00:00.000Z",
        "review_count": 0
      }
    ],
    "pagination": {
      "total": 25,
      "page": 1,
      "limit": 20,
      "pages": 2
    }
  }
}
```

##### 9.3.2 审核内容
- **Endpoint**: POST /api/v1/admin/content/{id}/review
- **认证要求**: Bearer Token，需要content:review权限
- **请求体**:
```json
{
  "action": "approve",
  "review_notes": "内容符合规范"
}
```
或者
```json
{
  "action": "reject",
  "review_notes": "包含不当内容",
  "reject_reason": "包含联系方式"
}
```
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "内容审核完成"
}
```

##### 9.3.3 获取内容统计
- **Endpoint**: GET /api/v1/admin/content/statistics
- **认证要求**: Bearer Token，需要content:review权限
- **查询参数**:
  - `days` (可选): 统计天数，默认7
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "total_contents": 1000,
    "pending_review": 25,
    "approved": 900,
    "rejected": 75,
    "daily_stats": [
      {
        "date": "2025-01-01",
        "total": 50,
        "approved": 45,
        "rejected": 5
      }
    ],
    "by_type": {
      "travel_plan": 300,
      "dynamic": 500,
      "comment": 200
    }
  }
}
```

#### 9.4 数据统计接口

##### 9.4.1 获取平台概览数据
- **Endpoint**: GET /api/v1/admin/dashboard/overview
- **认证要求**: Bearer Token，需要data:view权限
- **查询参数**:
  - `days` (可选): 统计天数，默认30
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "user_stats": {
      "total_users": 10000,
      "new_users_today": 50,
      "new_users_7d": 300,
      "new_users_30d": 1200,
      "active_users_7d": 2000,
      "active_users_30d": 6000
    },
    "order_stats": {
      "total_orders": 5000,
      "today_orders": 25,
      "revenue_today": 1250.00,
      "revenue_7d": 8500.00,
      "revenue_30d": 35000.00,
      "avg_order_value": 70.00
    },
    "content_stats": {
      "total_travel_plans": 2000,
      "total_animal_claims": 800,
      "total_flower_orders": 1200,
      "total_dynamics": 3000
    },
    "merchant_stats": {
      "total_merchants": 150,
      "active_merchants": 120,
      "flower_shops": 60,
      "farms": 50,
      "organizers": 40
    }
  }
}
```

##### 9.4.2 获取用户增长图表
- **Endpoint**: GET /api/v1/admin/dashboard/user-growth
- **认证要求**: Bearer Token，需要data:view权限
- **查询参数**:
  - `days` (可选): 统计天数，默认30
  - `group_by` (可选): 分组方式（day/week/month），默认day
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "chart_data": [
      {
        "date": "2025-01-01",
        "new_users": 45,
        "total_users": 10045
      },
      {
        "date": "2025-01-02", 
        "new_users": 52,
        "total_users": 10097
      }
    ],
    "summary": {
      "total_new_users": 1200,
      "growth_rate": 12.5,
      "avg_daily_new_users": 40
    }
  }
}
```

##### 9.4.3 获取订单统计图表
- **Endpoint**: GET /api/v1/admin/dashboard/order-stats
- **认证要求**: Bearer Token，需要data:view权限
- **查询参数**:
  - `days` (可选): 统计天数，默认30
  - `order_type` (可选): 订单类型（flower/animal/travel）
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "chart_data": [
      {
        "date": "2025-01-01",
        "total_orders": 28,
        "total_revenue": 1960.00,
        "flower_orders": 15,
        "animal_orders": 8,
        "travel_orders": 5
      }
    ],
    "summary": {
      "total_revenue": 35000.00,
      "avg_daily_revenue": 1166.67,
      "order_conversion_rate": 8.5
    }
  }
}
```

##### 9.4.4 导出数据报表
- **Endpoint**: GET /api/v1/admin/dashboard/export
- **认证要求**: Bearer Token，需要data:export权限
- **查询参数**:
  - `report_type` (必选): 报表类型（users/orders/contents/merchants）
  - `format` (可选): 格式（csv/excel），默认csv
  - `start_date` (可选): 开始时间
  - `end_date` (可选): 结束时间
- **响应**: 返回文件下载流

#### 9.5 权限管理接口

##### 9.5.1 获取管理员列表
- **Endpoint**: GET /api/v1/admin/administrators
- **认证要求**: Bearer Token，需要admin:manage权限
- **查询参数**:
  - `page` (可选): 页码，默认1
  - `limit` (可选): 每页数量，默认20
  - `username` (可选): 用户名模糊搜索
  - `role` (可选): 角色过滤
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "admins": [
      {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com",
        "nickname": "超级管理员",
        "avatar": "https://example.com/avatar.jpg",
        "role": "super_admin",
        "status": 1,
        "last_login": "2025-01-15T10:30:00.000Z",
        "created_at": "2025-01-01T00:00:00.000Z",
        "permissions": ["user:manage", "content:review", "data:view", "data:export"]
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}
```

##### 9.5.2 创建管理员账号
- **Endpoint**: POST /api/v1/admin/administrators
- **认证要求**: Bearer Token，需要admin:manage权限
- **请求体**:
```json
{
  "username": "newadmin",
  "password": "password123",
  "email": "newadmin@example.com",
  "nickname": "新管理员",
  "role": "content_admin",
  "permissions": ["content:review", "content:publish"]
}
```
- **响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "管理员创建成功",
  "data": {
    "id": 2,
    "username": "newadmin",
    "email": "newadmin@example.com",
    "nickname": "新管理员",
    "role": "content_admin",
    "status": 1,
    "created_at": "2025-01-01T00:00:00.000Z"
  }
}
```

##### 9.5.3 更新管理员权限
- **Endpoint**: PUT /api/v1/admin/administrators/{id}/permissions
- **认证要求**: Bearer Token，需要admin:manage权限
- **请求体**:
```json
{
  "permissions": ["content:review", "content:publish", "data:view"]
}
```
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "权限更新成功"
}
```

##### 9.5.4 禁用/启用管理员账号
- **Endpoint**: PUT /api/v1/admin/administrators/{id}/status
- **认证要求**: Bearer Token，需要admin:manage权限
- **请求体**:
```json
{
  "status": 0
}
```
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "管理员状态更新成功"
}
```

##### 9.5.5 获取权限列表
- **Endpoint**: GET /api/v1/admin/permissions
- **认证要求**: Bearer Token，需要admin:manage权限
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "permissions": [
      {
        "code": "user:manage",
        "name": "用户管理",
        "description": "管理用户账号和状态"
      },
      {
        "code": "content:review", 
        "name": "内容审核",
        "description": "审核用户发布的内容"
      },
      {
        "code": "content:publish",
        "name": "内容发布",
        "description": "发布和管理平台内容"
      },
      {
        "code": "data:view",
        "name": "数据查看",
        "description": "查看平台统计数据"
      },
      {
        "code": "data:export",
        "name": "数据导出",
        "description": "导出数据报表"
      },
      {
        "code": "merchant:review",
        "name": "商家审核",
        "description": "审核商家入驻申请"
      },
      {
        "code": "merchant:manage",
        "name": "商家管理",
        "description": "管理商家账号和信息"
      },
      {
        "code": "admin:manage",
        "name": "管理员管理",
        "description": "管理其他管理员账号"
      }
    ]
  }
}
```

#### 9.6 操作日志接口

##### 9.6.1 获取操作日志列表
- **Endpoint**: GET /api/v1/admin/operation-logs
- **认证要求**: Bearer Token，需要admin:manage权限
- **查询参数**:
  - `page` (可选): 页码，默认1
  - `limit` (可选): 每页数量，默认20
  - `admin_id` (可选): 操作管理员ID
  - `action_type` (可选): 操作类型
  - `start_date` (可选): 开始时间
  - `end_date` (可选): 结束时间
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "logs": [
      {
        "id": 1,
        "admin_id": 1,
        "admin_name": "超级管理员",
        "action_type": "user_status_update",
        "target_type": "user",
        "target_id": 5,
        "target_name": "testuser",
        "old_value": "active",
        "new_value": "banned",
        "ip_address": "192.168.1.100",
        "user_agent": "Mozilla/5.0...",
        "created_at": "2025-01-01T10:30:00.000Z"
      }
    ],
    "pagination": {
      "total": 1000,
      "page": 1,
      "limit": 20,
      "pages": 50
    }
  }
}
```

##### 9.6.2 导出操作日志
- **Endpoint**: GET /api/v1/admin/operation-logs/export
- **认证要求**: Bearer Token，需要admin:manage权限
- **查询参数**:
  - `format` (可选): 格式（csv/excel），默认csv
  - `start_date` (可选): 开始时间
  - `end_date` (可选): 结束时间
- **响应**: 返回文件下载流
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 20,
      "pages": 5
    }
  }
}
```

#### 9.2 获取用户详情
- **Endpoint**: GET /api/v1/users/{id}
- **认证要求**: Bearer Token，需要user:manage权限
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "13800138000",
      "user_type": "farmer",
      "status": "active",
      "points": 100,
      "level": 2,
      "created_at": "2025-01-01T00:00:00.000Z",
      "last_login_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

#### 9.3 更新用户状态
- **Endpoint**: PUT /api/v1/users/{id}/status
- **认证要求**: Bearer Token，需要user:manage权限
- **请求体**:
```json
{
  "status": "active"
}
```
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "用户状态更新成功"
}
```

#### 9.4 删除用户
- **Endpoint**: DELETE /api/v1/users/{id}
- **认证要求**: Bearer Token，需要user:manage权限
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "用户删除成功"
}
```

### 10. 系统管理接口

#### 10.1 获取系统信息
- **Endpoint**: GET /api/v1/admin/system/info
- **认证要求**: Bearer Token，需要system:view权限
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "system": {
      "version": "1.0.0",
      "node_version": "v18.17.0",
      "platform": "linux",
      "arch": "x64",
      "uptime": 123456,
      "memory_usage": {
        "total": 17179869184,
        "used": 8589934592,
        "free": 8589934592
      },
      "cpu_usage": 25.5
    }
  }
}
```

#### 10.2 获取系统服务列表
- **Endpoint**: GET /api/v1/admin/system/services
- **认证要求**: Bearer Token，需要system:manage权限
- **查询参数**:
  - `page` (可选): 页码，默认1
  - `limit` (可选): 每页数量，默认20
  - `type` (可选): 服务类型(database/cache/mq)
  - `status` (可选): 服务状态(running/stopped)
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "services": [
      {
        "id": "mysql",
        "name": "MySQL数据库",
        "type": "database",
        "status": "running",
        "host": "mysql.jiebanke.com",
        "port": 3306,
        "description": "主数据库服务",
        "created_at": "2024-01-01T00:00:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "total": 5,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}
```

#### 10.3 更新服务状态
- **Endpoint**: PUT /api/v1/admin/system/services/{id}/status
- **认证要求**: Bearer Token，需要system:manage权限
- **请求体**:
```json
{
  "status": "stopped"
}
```
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "服务状态更新成功"
}
```

#### 10.4 获取系统配置
- **Endpoint**: GET /api/v1/admin/system/configs
- **认证要求**: Bearer Token，需要system:config权限
- **查询参数**:
  - `page` (可选): 页码，默认1
  - `limit` (可选): 每页数量，默认20
  - `group` (可选): 配置分组
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "configs": [
      {
        "id": "site_name",
        "name": "网站名称",
        "value": "结伴客",
        "type": "string",
        "group": "basic",
        "description": "网站显示名称",
        "created_at": "2024-01-01T00:00:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}
```

#### 10.5 更新系统配置
- **Endpoint**: PUT /api/v1/admin/system/configs/{id}
- **认证要求**: Bearer Token，需要system:config权限
- **请求体**:
```json
{
  "value": "新网站名称"
}
```
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "配置更新成功"
}
```

### 11. 内容管理接口

#### 11.1 获取内容列表
- **Endpoint**: GET /admin/contents
- **认证要求**: Bearer Token，需要content:review权限
- **查询参数**:
  - `page` (可选): 页码，默认1
  - `limit` (可选): 每页数量，默认20
  - `type` (可选): 内容类型
  - `status` (可选): 审核状态
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "contents": [
      {
        "id": 1,
        "title": "测试内容",
        "type": "article",
        "author": "测试用户",
        "status": "pending",
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "limit": 20,
      "pages": 3
    }
  }
}
```

#### 9.2 获取内容详情

**Endpoint**: `GET /admin/contents/{id}`

**认证**: 需要Bearer Token，需要content:review权限

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "content": {
      "id": 1,
      "title": "测试内容",
      "type": "article",
      "content": "详细内容文本...",
      "author": {
        "id": 1,
        "username": "testuser",
        "nickname": "测试用户"
      },
      "images": ["https://www.jiebanke.com/image1.jpg"],
      "status": "pending",
      "created_at": "2025-01-01T12:00:00.000Z",
      "updated_at": "2025-01-01T12:00:00.000Z"
    }
  }
}
```

#### 9.3 审核内容

**Endpoint**: `PUT /admin/contents/{id}/review`

**认证**: 需要Bearer Token，需要content:review权限

**请求体**:
```json
{
  "status": "string, required, 审核状态(approved/rejected)",
  "review_comment": "string, optional, 审核意见"
}
```

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "内容审核完成"
}
```

#### 9.4 批量审核内容

**Endpoint**: `POST /admin/contents/batch-review`

**认证**: 需要Bearer Token，需要content:review权限

**请求体**:
```json
{
  "content_ids": ["number, required, 内容ID列表"],
  "status": "string, required, 审核状态(approved/rejected)",
  "review_comment": "string, optional, 审核意见"
}
```

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "批量审核完成",
  "data": {
    "success_count": 5,
    "failed_count": 0
  }
}
```

### 13. 商家管理接口

#### 13.1 获取商家申请列表

**Endpoint**: `GET /admin/merchant-applications`

**认证**: 需要Bearer Token，需要merchant:approve权限

**查询参数**:
- `page` (可选): 页码，默认1
- `limit` (可选): 每页数量，默认20
- `status` (可选): 状态过滤(pending/approved/rejected)
- `business_name` (可选): 商家名称搜索

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "applications": [
      {
        "id": 1,
        "user_id": 1,
        "business_name": "XX农场",
        "contact_person": "张三",
        "contact_phone": "13800138000",
        "merchant_type": "farm_owner",
        "status": "pending",
        "created_at": "2025-01-01T12:00:00.000Z",
        "updated_at": "2025-01-01T12:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 15,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}
```

#### 13.2 审核商家申请

**Endpoint**: `PUT /admin/merchant-applications/{id}/review`

**认证**: 需要Bearer Token，需要merchant:approve权限

**请求体**:
```json
{
  "status": "string, required, 审核状态(approved/rejected)",
  "review_comment": "string, optional, 审核意见"
}
```

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "商家申请审核完成"
}
```

#### 13.3 获取商家列表

**Endpoint**: `GET /admin/merchants`

**认证**: 需要Bearer Token，需要merchant:view权限

**查询参数**:
- `page` (可选): 页码，默认1
- `limit` (可选): 每页数量，默认20
- `merchant_type` (可选): 商家类型过滤
- `status` (可选): 状态过滤(active/inactive)
- `business_name` (可选): 商家名称搜索

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "merchants": [
      {
        "id": 1,
        "user_id": 1,
        "business_name": "XX农场",
        "merchant_type": "farm_owner",
        "contact_person": "张三",
        "contact_phone": "13800138000",
        "status": "active",
        "product_count": 5,
        "order_count": 20,
        "total_revenue": 50000.00,
        "created_at": "2025-01-01T12:00:00.000Z",
        "updated_at": "2025-01-01T12:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 25,
      "page": 1,
      "limit": 20,
      "pages": 2
    }
  }
}
```

#### 13.4 更新商家状态

**Endpoint**: `PUT /admin/merchants/{id}/status`

**认证**: 需要Bearer Token，需要merchant:manage权限

**请求体**:
```json
{
  "status": "string, required, 状态(active/inactive)"
}
```

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "商家状态更新成功"
}
```

### 14. 系统配置接口

#### 14.1 获取系统配置

**Endpoint**: `GET /admin/system-configs`

**认证**: 需要Bearer Token，需要system:config权限

**查询参数**:
- `group` (可选): 配置组过滤

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "configs": [
      {
        "id": "site_name",
        "name": "网站名称",
        "value": "结伴客",
        "type": "string",
        "group": "general",
        "description": "网站显示的名称",
        "created_at": "2025-01-01T12:00:00.000Z",
        "updated_at": "2025-01-01T12:00:00.000Z"
      },
      {
        "id": "site_description",
        "name": "网站描述",
        "value": "专业的旅行结伴和动物认领平台",
        "type": "text",
        "group": "general",
        "description": "网站的简要描述",
        "created_at": "2025-01-01T12:00:00.000Z",
        "updated_at": "2025-01-01T12:00:00.000Z"
      },
      {
        "id": "max_file_size",
        "name": "最大文件大小",
        "value": "10",
        "type": "number",
        "group": "upload",
        "description": "允许上传的最大文件大小(MB)",
        "created_at": "2025-01-01T12:00:00.000Z",
        "updated_at": "2025-01-01T12:00:00.000Z"
      }
    ]
  }
}
```

#### 14.2 更新系统配置

**Endpoint**: `PUT /admin/system-configs/{id}`

**认证**: 需要Bearer Token，需要system:config权限

**请求体**:
```json
{
  "value": "string, required, 配置值"
}
```

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "配置更新成功"
}
```

#### 14.3 批量更新系统配置

**Endpoint**: `POST /admin/system-configs/batch-update`

**认证**: 需要Bearer Token，需要system:config权限

**请求体**:
```json
{
  "configs": [
    {
      "id": "site_name",
      "value": "新网站名称"
    },
    {
      "id": "site_description",
      "value": "新的网站描述"
    }
  ]
}
```

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "批量配置更新成功",
  "data": {
    "success_count": 2,
    "failed_count": 0
  }
}
```

### 10. 数据统计接口

#### 10.1 获取系统统计数据

**Endpoint**: `GET /admin/statistics`

**认证**: 需要Bearer Token，需要data:view权限

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "user_count": 1000,
    "active_user_count": 500,
    "new_user_today": 20,
    "order_count": 300,
    "revenue_today": 5000.00,
    "content_count": 200,
    "pending_review_count": 15,
    "animal_claim_count": 150,
    "travel_plan_count": 80,
    "flower_order_count": 120,
    "merchant_count": 25,
    "pending_merchant_approval_count": 8
  }
}
```

#### 10.2 获取数据趋势图表

**Endpoint**: `GET /admin/statistics/trend`

**认证**: 需要Bearer Token，需要data:view权限

**查询参数**:
- `type` (必选): 数据类型(user/order/revenue/content)
- `days` (可选): 天数，默认7天

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "labels": ["2025-01-01", "2025-01-02", "2025-01-03", "2025-01-04", "2025-01-05", "2025-01-06", "2025-01-07"],
    "datasets": [
      {
        "label": "用户增长",
        "data": [100, 120, 150, 180, 200, 220, 250],
        "borderColor": "rgb(75, 192, 192)"
      }
    ]
  }
}
```

#### 10.3 导出数据

**Endpoint**: `GET /admin/export/{type}`

**认证**: 需要Bearer Token，需要data:export权限

**查询参数**:
- `start_date` (可选): 开始日期
- `end_date` (可选): 结束日期
- `format` (可选): 导出格式(csv/excel)，默认csv

**响应**: 返回CSV或Excel文件下载

### 11. 权限管理接口

#### 11.1 获取角色列表

**Endpoint**: `GET /admin/roles`

**认证**: 需要Bearer Token，需要role:manage权限

**查询参数**:
- `page` (可选): 页码，默认1
- `limit` (可选): 每页数量，默认20

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "roles": [
      {
        "id": 1,
        "name": "super_admin",
        "description": "超级管理员",
        "permission_count": 20,
        "user_count": 3,
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z"
      },
      {
        "id": 2,
        "name": "content_admin",
        "description": "内容管理员",
        "permission_count": 8,
        "user_count": 5,
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}
```

#### 11.2 创建角色

**Endpoint**: `POST /admin/roles`

**认证**: 需要Bearer Token，需要role:manage权限

**请求体**:
```json
{
  "name": "string, required, 角色名称",
  "description": "string, required, 角色描述",
  "permissions": ["string, required, 权限列表"]
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "角色创建成功",
  "data": {
    "role": {
      "id": 3,
      "name": "data_admin",
      "description": "数据管理员",
      "permissions": ["data:view", "data:export"],
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

#### 11.3 更新角色权限

**Endpoint**: `PUT /admin/roles/{id}`

**认证**: 需要Bearer Token，需要role:manage权限

**请求体**:
```json
{
  "description": "string, optional, 角色描述",
  "permissions": ["string, required, 权限列表"]
}
```

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "角色更新成功"
}
```

#### 11.4 删除角色

**Endpoint**: `DELETE /admin/roles/{id}`

**认证**: 需要Bearer Token，需要role:manage权限

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "角色删除成功"
}
```

#### 11.5 获取权限列表

**Endpoint**: `GET /admin/permissions`

**认证**: 需要Bearer Token，需要role:manage权限

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "permissions": [
      {
        "id": "user:view",
        "name": "查看用户",
        "description": "允许查看用户列表和详情",
        "category": "用户管理"
      },
      {
        "id": "user:manage",
        "name": "管理用户",
        "description": "允许修改用户状态和信息",
        "category": "用户管理"
      },
      {
        "id": "content:review",
        "name": "审核内容",
        "description": "允许审核用户发布的内容",
        "category": "内容管理"
      },
      {
        "id": "content:publish",
        "name": "发布内容",
        "description": "允许发布系统公告和内容",
        "category": "内容管理"
      },
      {
        "id": "data:view",
        "name": "查看数据",
        "description": "允许查看系统统计数据",
        "category": "数据统计"
      },
      {
        "id": "data:export",
        "name": "导出数据",
        "description": "允许导出系统数据",
        "category": "数据统计"
      },
      {
        "id": "role:manage",
        "name": "管理角色",
        "description": "允许管理角色和权限",
        "category": "权限管理"
      },
      {
        "id": "merchant:approve",
        "name": "审核商家",
        "description": "允许审核商家入驻申请",
        "category": "商家管理"
      },
      {
        "id": "system:config",
        "name": "系统配置",
        "description": "允许修改系统配置参数",
        "category": "系统管理"
      }
    ]
  }
}
```

#### 11.6 分配用户角色

**Endpoint**: `POST /admin/users/{userId}/roles`

**认证**: 需要Bearer Token，需要role:manage权限

**请求体**:
```json
{
  "roleIds": ["number, required, 角色ID列表"]
}
```

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "角色分配成功"
}
```

### 12. 操作日志接口

#### 12.1 获取操作日志列表

**Endpoint**: `GET /admin/operation-logs`

**认证**: 需要Bearer Token，需要audit:view权限

**查询参数**:
- `page` (可选): 页码，默认1
- `limit` (可选): 每页数量，默认20
- `admin_id` (可选): 管理员ID过滤
- `module` (可选): 操作模块过滤
- `operation` (可选): 操作类型过滤
- `target_type` (可选): 目标对象类型过滤
- `status` (可选): 操作状态过滤(success/failed)
- `start_date` (可选): 开始日期
- `end_date` (可选): 结束日期
- `keyword` (可选): 关键词搜索(管理员姓名/操作描述)

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "logs": [
      {
        "id": 1,
        "admin_id": 1,
        "admin_name": "管理员A",
        "module": "用户管理",
        "operation": "user:update",
        "operation_name": "更新用户",
        "target_id": "2",
        "target_type": "user",
        "target_name": "用户B",
        "request_method": "PUT",
        "request_url": "/admin/users/2",
        "request_params": "{\"status\":\"inactive\"}",
        "ip_address": "192.168.1.100",
        "user_agent": "Mozilla/5.0...",
        "status": "success",
        "execution_time": 150,
        "created_at": "2025-01-01T12:00:00.000Z"
      },
      {
        "id": 2,
        "admin_id": 2,
        "admin_name": "管理员B",
        "module": "内容审核",
        "operation": "content:review",
        "operation_name": "审核内容",
        "target_id": "5",
        "target_type": "content",
        "target_name": "测试文章",
        "request_method": "PUT",
        "request_url": "/admin/contents/5/review",
        "request_params": "{\"status\":\"approved\",\"review_comment\":\"内容符合规范\"}",
        "ip_address": "192.168.1.101",
        "user_agent": "Mozilla/5.0...",
        "status": "success",
        "execution_time": 200,
        "created_at": "2025-01-01T12:30:00.000Z"
      }
    ],
    "pagination": {
      "total": 1000,
      "page": 1,
      "limit": 20,
      "pages": 50
    }
  }
}
```

#### 12.2 获取操作日志详情

**Endpoint**: `GET /admin/operation-logs/{id}`

**认证**: 需要Bearer Token，需要audit:view权限

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "log": {
      "id": 1,
      "admin_id": 1,
      "admin_name": "管理员A",
      "module": "用户管理",
      "operation": "user:update",
      "operation_name": "更新用户",
      "target_id": "2",
      "target_type": "user",
      "target_name": "用户B",
      "request_method": "PUT",
      "request_url": "/admin/users/2",
      "request_params": {
        "status": "inactive"
      },
      "request_headers": {
        "authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "user-agent": "Mozilla/5.0...",
        "accept": "application/json"
      },
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0...",
      "status": "success",
      "error_message": null,
      "execution_time": 150,
      "created_at": "2025-01-01T12:00:00.000Z"
    }
  }
}
```

#### 12.3 导出操作日志

**Endpoint**: `GET /admin/operation-logs/export`

**认证**: 需要Bearer Token，需要audit:export权限

**查询参数**:
- `start_date` (可选): 开始日期
- `end_date` (可选): 结束日期
- `module` (可选): 操作模块过滤
- `operation` (可选): 操作类型过滤
- `status` (可选): 操作状态过滤
- `format` (可选): 导出格式(csv/excel)，默认csv

**响应**: 返回CSV或Excel文件下载

#### 12.4 获取操作统计

**Endpoint**: `GET /admin/operation-logs/statistics`

**认证**: 需要Bearer Token，需要audit:view权限

**查询参数**:
- `start_date` (可选): 开始日期
- `end_date` (可选): 结束日期

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "total_operations": 1250,
    "success_count": 1200,
    "failed_count": 50,
    "avg_execution_time": 180,
    "top_modules": [
      {"module": "用户管理", "count": 450, "percentage": 36.0},
      {"module": "内容审核", "count": 300, "percentage": 24.0},
      {"module": "数据统计", "count": 200, "percentage": 16.0},
      {"module": "系统配置", "count": 150, "percentage": 12.0},
      {"module": "权限管理", "count": 100, "percentage": 8.0},
      {"module": "其他", "count": 50, "percentage": 4.0}
    ],
    "top_operations": [
      {"operation": "user:update", "count": 200, "percentage": 16.0},
      {"operation": "content:review", "count": 180, "percentage": 14.4},
      {"operation": "data:view", "count": 150, "percentage": 12.0},
      {"operation": "user:create", "count": 120, "percentage": 9.6},
      {"operation": "system:config", "count": 100, "percentage": 8.0}
    ],
    "top_admins": [
      {"admin_id": 1, "admin_name": "管理员A", "count": 500, "percentage": 40.0},
      {"admin_id": 2, "admin_name": "管理员B", "count": 400, "percentage": 32.0},
      {"admin_id": 3, "admin_name": "管理员C", "count": 350, "percentage": 28.0}
    ]
  }
}
```

## 旅行结伴接口

### 11. 发布旅行计划

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

**认证**: 需要Bearer Token

**请求体**:
```json
{
  "title": "string, required, 计划标题",
  "description": "string, required, 计划描述",
  "destination": "string, required, 目的地",
  "start_date": "string, required, 开始日期(YYYY-MM-DD)",
  "end_date": "string, required, 结束日期(YYYY-MM-DD)",
  "max_members": "number, required, 最大参与人数",
  "budget": "number, optional, 预算金额",
  "tags": "array, optional, 标签数组",
  "images": "array, optional, 图片URL数组"
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "旅行计划发布成功",
  "data": {
    "plan": {
      "id": 1,
      "title": "周末杭州西湖游",
      "description": "寻找志同道合的伙伴一起游玩西湖",
      "destination": "杭州西湖",
      "start_date": "2025-01-15",
      "end_date": "2025-01-16",
      "max_members": 6,
      "current_members": 1,
      "budget": 500,
      "status": "recruiting",
      "tags": ["休闲", "摄影", "美食"],
      "images": [],
      "creator_id": 1,
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

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

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

**查询参数**:
- `page` (可选): 页码，默认1
- `limit` (可选): 每页数量，默认20
- `destination` (可选): 目的地搜索
- `start_date` (可选): 开始日期筛选
- `end_date` (可选): 结束日期筛选
- `status` (可选): 状态筛选(recruiting/in_progress/completed/cancelled)
- `sort` (可选): 排序方式(created_at/start_date)

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "plans": [
      {
        "id": 1,
        "title": "周末杭州西湖游",
        "destination": "杭州西湖",
        "start_date": "2025-01-15",
        "end_date": "2025-01-16",
        "max_members": 6,
        "current_members": 3,
        "budget": 500,
        "status": "recruiting",
        "tags": ["休闲", "摄影", "美食"],
        "creator": {
          "id": 1,
          "username": "testuser",
          "nickname": "测试用户",
          "avatar": ""
        },
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "limit": 20,
      "pages": 3
    }
  }
}
```

### 13. 加入旅行计划

**Endpoint**: `POST /travel/plans/{id}/join`

**认证**: 需要Bearer Token

**请求体**:
```json
{
  "message": "string, optional, 加入留言"
}
```

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "成功加入旅行计划",
  "data": {
    "membership": {
      "id": 1,
      "plan_id": 1,
      "user_id": 2,
      "status": "pending",
      "message": "希望能一起游玩",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

## 动物认领接口

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

**Endpoint**: `GET /animals/adoptable`

**查询参数**:
- `page` (可选): 页码，默认1
- `limit` (可选): 每页数量，默认20
- `type` (可选): 动物类型
- `breed` (可选): 品种筛选
- `age_min` (可选): 最小年龄
- `age_max` (可选): 最大年龄
- `location` (可选): 地理位置

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "animals": [
      {
        "id": 1,
        "name": "小白",
        "type": "dog",
        "breed": "中华田园犬",
        "age": 2,
        "gender": "male",
        "description": "温顺可爱的狗狗，寻找有爱心的主人",
        "vaccination_status": "vaccinated",
        "sterilization_status": "sterilized",
        "location": "北京市朝阳区",
        "images": ["https://www.jiebanke.com/animal1.jpg"],
        "status": "available",
        "shelter": {
          "id": 1,
          "name": "爱心动物救助站",
          "contact": "13800138000"
        },
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 30,
      "page": 1,
      "limit": 20,
      "pages": 2
    }
  }
}
```

### 15. 申请认领动物

**Endpoint**: `POST /animals/{id}/adopt`

**认证**: 需要Bearer Token

**请求体**:
```json
{
  "application_reason": "string, required, 申请理由",
  "living_environment": "string, required, 居住环境描述",
  "experience": "string, optional, 养宠经验",
  "contact_info": "string, required, 联系方式"
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "认领申请已提交",
  "data": {
    "application": {
      "id": 1,
      "animal_id": 1,
      "applicant_id": 1,
      "status": "pending",
      "application_reason": "非常喜欢狗狗，有养宠经验",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

## 花卉订购接口

### 16. 获取花卉商品列表

**Endpoint**: `GET /flowers/products`

**查询参数**:
- `page` (可选): 页码，默认1
- `limit` (可选): 每页数量，默认20
- `category" (可选): 分类筛选
- "min_price" (可选): 最低价格
- "max_price" (可选): 最高价格
- "sort" (可选): 排序方式(price/created_at/sales)

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "products": [
      {
        "id": 1,
        "name": "玫瑰花束",
        "description": "新鲜玫瑰花束，适合送礼",
        "category": "鲜花",
        "price": 99.00,
        "original_price": 129.00,
        "stock": 50,
        "sales": 120,
        "images": ["https://www.jiebanke.com/rose.jpg"],
        "merchant": {
          "id": 1,
          "name": "花语花店",
          "rating": 4.8
        },
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 20,
      "pages": 5
    }
  }
}
```

### 17. 创建花卉订单

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

**认证**: 需要Bearer Token

**请求体**:
```json
{
  "items": [
    {
      "product_id": 1,
      "quantity": 2,
      "message": "string, optional, 留言卡片内容"
    }
  ],
  "shipping_address": {
    "recipient": "string, required, 收货人",
    "phone": "string, required, 联系电话",
    "address": "string, required, 详细地址",
    "postal_code": "string, optional, 邮政编码"
  },
  "delivery_date": "string, required, 配送日期(YYYY-MM-DD)",
  "delivery_time": "string, required, 配送时间段"
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "订单创建成功",
  "data": {
    "order": {
      "id": 1,
      "order_number": "F202501010001",
      "total_amount": 198.00,
      "status": "pending",
      "items": [
        {
          "product_id": 1,
          "product_name": "玫瑰花束",
          "quantity": 2,
          "price": 99.00,
          "subtotal": 198.00
        }
      ],
      "shipping_address": {
        "recipient": "张三",
        "phone": "13800138000",
        "address": "北京市朝阳区某某街道123号"
      },
      "delivery_date": "2025-01-15",
      "delivery_time": "14:00-16:00",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

## 社交互动接口

### 18. 发布动态

**Endpoint**: `POST /social/posts`

**认证**: 需要Bearer Token

**请求体**:
```json
{
  "content": "string, required, 动态内容",
  "images": "array, optional, 图片URL数组",
  "visibility": "string, optional, 可见性(public/friends/private)",
  "location": "string, optional, 位置信息"
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "动态发布成功",
  "data": {
    "post": {
      "id": 1,
      "content": "今天去了西湖，风景真美！",
      "images": ["https://www.jiebanke.com/westlake.jpg"],
      "visibility": "public",
      "location": "杭州西湖",
      "like_count": 0,
      "comment_count": 0,
      "author": {
        "id": 1,
        "username": "testuser",
        "nickname": "测试用户",
        "avatar": ""
      },
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

### 19. 点赞动态

**Endpoint**: `POST /social/posts/{id}/like`

**认证**: 需要Bearer Token

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "点赞成功",
  "data": {
    "like_count": 15
  }
}
```

### 20. 评论动态

**Endpoint**: `POST /social/posts/{id}/comments`

**认证**: 需要Bearer Token

**请求体**:
```json
{
  "content": "string, required, 评论内容",
  "parent_id": "number, optional, 父评论ID"
}
```

**响应**:
```json
{
  "success": true,
  "code": 201,
  "message": "评论成功",
  "data": {
    "comment": {
      "id": 1,
      "content": "照片拍得真漂亮！",
      "author": {
        "id": 2,
        "username": "user2",
        "nickname": "用户二",
        "avatar": ""
      },
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}
```

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

**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": "密码修改成功"
}
```

### 7. 退出登录

**Endpoint**: `POST /auth/logout`

**认证**: 需要Bearer Token

**描述**: 用户退出登录，使token失效

**响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "退出登录成功"
}
```

### 8. 刷新token

**Endpoint**: `POST /auth/refresh`

**认证**: 需要Bearer Token

**描述**: 刷新访问令牌

**响应**:
```json
{
  "success": true,
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

## 用户接口

### 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@jiebanke.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://www.jiebanke.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://www.jiebanke.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://www.jiebanke.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://www.jiebanke.com/promotion?ref=user123",
"qr_code": "https://www.jiebanke.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://www.jiebanke.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次