jiebanke/docs/管理后台接口设计文档.md

# 管理后台接口设计文档

## 1. 概述

### 1.1 项目简介
本文档详细描述了结伴客管理后台系统的所有API接口设计，包括用户管理、旅行管理、动物认领管理、订单管理、系统管理等模块的接口规范。

### 1.2 接口设计原则
- **RESTful风格**：遵循REST架构风格
- **统一响应格式**：所有接口采用统一的响应格式
- **版本控制**：支持API版本管理
- **安全认证**：JWT Token认证机制
- **错误处理**：统一的错误码和错误信息

### 1.3 技术规范
- **协议**：HTTPS
- **数据格式**：JSON
- **字符编码**：UTF-8
- **认证方式**：JWT Bearer Token
- **API版本**：v1
- **基础URL**：`http://localhost:3000/api/v1`

### 1.4 API模块概览

| 模块 | 描述 | 接口数量 | 状态 |
|------|------|----------|------|
| 认证授权 | 管理员登录、权限验证 | 5 | ✅ |
| 用户管理 | 用户CRUD、状态管理 | 8 | ✅ |
| 商户管理 | 商户信息管理 | 7 | ✅ |
| 旅行管理 | 旅行活动管理 | 8 | ✅ |
| 动物管理 | 动物认领管理 | 12 | ✅ |
| 订单管理 | 订单处理、状态跟踪 | 15 | ✅ |
| 花卉管理 | 花卉商品管理 | 9 | ✅ |
| 促销活动 | 促销活动和奖励管理 | 10 | ✅ |
| 系统管理 | 系统配置、监控 | 12 | ✅ |
| 仪表板 | 数据统计、图表 | 6 | ✅ |
| 权限管理 | 角色权限管理 | 8 | ✅ |

## 2. 通用规范

### 2.1 请求格式

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

#### 2.1.2 请求参数
- **路径参数**：用于资源标识，如 `/api/v1/users/{id}`
- **查询参数**：用于过滤、排序、分页等，如 `?page=1&size=20&sort=created_at:desc`
- **请求体**：JSON格式的数据

### 2.2 响应格式

#### 2.2.1 成功响应
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}
```

#### 2.2.2 分页响应
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      // 数据列表
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "pages": 5
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}
```

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

### 2.3 状态码规范

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

### 2.4 分页参数

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

### 2.5 排序参数格式
- 单字段排序：`sort=created_at:desc`
- 多字段排序：`sort=status:asc,created_at:desc`
- 支持的排序方向：`asc`（升序）、`desc`（降序）

## 3. 认证授权接口

### 3.1 管理员登录

#### 接口信息
- **接口路径**：`POST /api/v1/admin/login`
- **接口描述**：管理员登录获取访问令牌
- **是否需要认证**：否

#### 请求参数
```json
{
  "username": "admin",
  "password": "password123"
}
```

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |

#### 响应示例
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200,
    "admin": {
      "id": 1,
      "username": "admin",
      "name": "系统管理员",
      "email": "admin@example.com",
      "role": "super_admin",
      "permissions": ["user:read", "user:write", "system:manage"]
    }
  }
}
```

### 3.2 刷新令牌

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

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

### 3.3 退出登录

#### 接口信息
- **接口路径**：`POST /api/v1/admin/logout`
- **接口描述**：管理员退出登录
- **是否需要认证**：是

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

### 3.4 获取当前用户信息

#### 接口信息
- **接口路径**：`GET /api/v1/admin/profile`
- **接口描述**：获取当前登录管理员信息
- **是否需要认证**：是

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "admin",
    "name": "系统管理员",
    "email": "admin@example.com",
    "role": "super_admin",
    "permissions": ["user:read", "user:write", "system:manage"],
    "last_login": "2024-01-15T10:30:00Z"
  }
}
```

### 3.5 修改密码

#### 接口信息
- **接口路径**：`PUT /api/v1/admin/password`
- **接口描述**：修改管理员密码
- **是否需要认证**：是

#### 请求参数
```json
{
  "old_password": "oldpassword123",
  "new_password": "newpassword123"
}
```

## 4. 用户管理接口

### 4.1 获取用户列表

#### 接口信息
- **接口路径**：`GET /api/v1/users`
- **接口描述**：获取用户列表，支持分页和筛选
- **是否需要认证**：是

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词（用户名、昵称、手机号） |
| status | string | 否 | 用户状态：active, inactive, banned |
| gender | string | 否 | 性别：male, female, other |
| age_min | integer | 否 | 最小年龄 |
| age_max | integer | 否 | 最大年龄 |
| created_start | string | 否 | 注册开始时间 |
| created_end | string | 否 | 注册结束时间 |
| sort | string | 否 | 排序字段 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "username": "user001",
        "nickname": "小明",
        "avatar": "https://example.com/avatar/1.jpg",
        "phone": "13800138000",
        "email": "user001@example.com",
        "gender": "male",
        "age": 25,
        "status": "active",
        "created_at": "2024-01-01T00:00:00Z",
        "last_login": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "pages": 5
    }
  }
}
```

### 4.2 获取用户详情

#### 接口信息
- **接口路径**：`GET /api/v1/users/{id}`
- **接口描述**：获取指定用户的详细信息
- **是否需要认证**：是

#### 路径参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | integer | 是 | 用户ID |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "user001",
    "nickname": "小明",
    "avatar": "https://example.com/avatar/1.jpg",
    "phone": "13800138000",
    "email": "user001@example.com",
    "gender": "male",
    "age": 25,
    "birthday": "1999-01-01",
    "location": "北京市朝阳区",
    "bio": "热爱旅行的90后",
    "status": "active",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "last_login": "2024-01-15T10:30:00Z",
    "stats": {
      "travel_count": 5,
      "animal_adoption_count": 2,
      "order_count": 10,
      "total_spent": 1500.00
    }
  }
}
```

### 4.3 创建用户

#### 接口信息
- **接口路径**：`POST /api/v1/users`
- **接口描述**：创建新用户
- **是否需要认证**：是

#### 请求参数
```json
{
  "username": "user002",
  "nickname": "小红",
  "phone": "13800138001",
  "email": "user002@example.com",
  "password": "password123",
  "gender": "female",
  "age": 23,
  "location": "上海市浦东新区"
}
```

### 4.4 更新用户信息

#### 接口信息
- **接口路径**：`PUT /api/v1/users/{id}`
- **接口描述**：更新用户信息
- **是否需要认证**：是

### 4.5 删除用户

#### 接口信息
- **接口路径**：`DELETE /api/v1/users/{id}`
- **接口描述**：删除用户（软删除）
- **是否需要认证**：是

### 4.6 更新用户状态

#### 接口信息
- **接口路径**：`PUT /api/v1/users/{id}/status`
- **接口描述**：更新用户状态（激活/禁用/封禁）
- **是否需要认证**：是

#### 请求参数
```json
{
  "status": "banned",
  "reason": "违规行为"
}
```

### 4.7 重置用户密码

#### 接口信息
- **接口路径**：`PUT /api/v1/users/{id}/password`
- **接口描述**：重置用户密码
- **是否需要认证**：是

### 4.8 获取用户统计

#### 接口信息
- **接口路径**：`GET /api/v1/users/stats`
- **接口描述**：获取用户统计数据
- **是否需要认证**：是

## 5. 商户管理接口

### 5.1 获取商户列表

#### 接口信息
- **接口路径**：`GET /api/v1/merchants`
- **接口描述**：获取商户列表，支持分页和筛选
- **是否需要认证**：是

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词（商户名称、联系人） |
| status | string | 否 | 商户状态：active, inactive, pending |
| category | string | 否 | 商户类别 |
| city | string | 否 | 所在城市 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "阳光旅行社",
        "logo": "https://example.com/logo/1.jpg",
        "category": "travel",
        "contact_person": "张经理",
        "phone": "400-123-4567",
        "email": "contact@sunshine-travel.com",
        "address": "北京市朝阳区xxx街道xxx号",
        "city": "北京",
        "status": "active",
        "rating": 4.8,
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 50,
      "pages": 3
    }
  }
}
```

### 5.2 获取商户详情

#### 接口信息
- **接口路径**：`GET /api/v1/merchants/{id}`
- **接口描述**：获取指定商户的详细信息
- **是否需要认证**：是

### 5.3 创建商户

#### 接口信息
- **接口路径**：`POST /api/v1/merchants`
- **接口描述**：创建新商户
- **是否需要认证**：是

### 5.4 更新商户信息

#### 接口信息
- **接口路径**：`PUT /api/v1/merchants/{id}`
- **接口描述**：更新商户信息
- **是否需要认证**：是

### 5.5 删除商户

#### 接口信息
- **接口路径**：`DELETE /api/v1/merchants/{id}`
- **接口描述**：删除商户
- **是否需要认证**：是

### 5.6 更新商户状态

#### 接口信息
- **接口路径**：`PUT /api/v1/merchants/{id}/status`
- **接口描述**：更新商户状态
- **是否需要认证**：是

### 5.7 获取商户统计

#### 接口信息
- **接口路径**：`GET /api/v1/merchants/stats`
- **接口描述**：获取商户统计数据
- **是否需要认证**：是

## 6. 旅行管理接口

### 6.1 获取旅行列表

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

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词（标题、目的地） |
| status | string | 否 | 状态：draft, published, cancelled, completed |
| category | string | 否 | 旅行类别 |
| destination | string | 否 | 目的地 |
| price_min | number | 否 | 最低价格 |
| price_max | number | 否 | 最高价格 |
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "title": "云南大理古城三日游",
        "description": "探索古城文化，体验白族风情",
        "images": ["https://example.com/travel/1/1.jpg"],
        "destination": "云南大理",
        "category": "cultural",
        "price": 1299.00,
        "max_participants": 20,
        "current_participants": 8,
        "start_date": "2024-03-01",
        "end_date": "2024-03-03",
        "status": "published",
        "organizer": {
          "id": 1,
          "name": "阳光旅行社"
        },
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 80,
      "pages": 4
    }
  }
}
```

### 6.2 获取旅行详情

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

### 6.3 创建旅行活动

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

### 6.4 更新旅行活动

#### 接口信息
- **接口路径**：`PUT /api/v1/travels/{id}`
- **接口描述**：更新旅行活动信息
- **是否需要认证**：是

### 6.5 删除旅行活动

#### 接口信息
- **接口路径**：`DELETE /api/v1/travels/{id}`
- **接口描述**：删除旅行活动
- **是否需要认证**：是

### 6.6 更新旅行状态

#### 接口信息
- **接口路径**：`PUT /api/v1/travels/{id}/status`
- **接口描述**：更新旅行活动状态
- **是否需要认证**：是

### 6.7 获取旅行参与者

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

### 6.8 获取旅行统计

#### 接口信息
- **接口路径**：`GET /api/v1/travels/stats`
- **接口描述**：获取旅行活动统计数据
- **是否需要认证**：是

## 7. 动物管理接口

### 7.1 获取动物列表

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

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词（动物名称、品种） |
| species | string | 否 | 物种：dog, cat, bird, other |
| status | string | 否 | 状态：available, adopted, reserved |
| age_min | integer | 否 | 最小年龄（月） |
| age_max | integer | 否 | 最大年龄（月） |
| gender | string | 否 | 性别：male, female |
| location | string | 否 | 所在地区 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "小白",
        "species": "dog",
        "breed": "金毛",
        "age": 24,
        "gender": "male",
        "color": "金黄色",
        "weight": 25.5,
        "images": ["https://example.com/animal/1/1.jpg"],
        "description": "性格温顺，喜欢和人玩耍",
        "health_status": "healthy",
        "vaccination_status": "completed",
        "sterilization_status": "completed",
        "location": "北京市朝阳区",
        "status": "available",
        "rescue_date": "2024-01-01",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 120,
      "pages": 6
    }
  }
}
```

### 7.2 获取动物详情

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

### 7.3 创建动物信息

#### 接口信息
- **接口路径**：`POST /api/v1/animals`
- **接口描述**：添加新的动物信息
- **是否需要认证**：是

### 7.4 更新动物信息

#### 接口信息
- **接口路径**：`PUT /api/v1/animals/{id}`
- **接口描述**：更新动物信息
- **是否需要认证**：是

### 7.5 删除动物信息

#### 接口信息
- **接口路径**：`DELETE /api/v1/animals/{id}`
- **接口描述**：删除动物信息
- **是否需要认证**：是

### 7.6 更新动物状态

#### 接口信息
- **接口路径**：`PUT /api/v1/animals/{id}/status`
- **接口描述**：更新动物状态（可领养/已预约/已领养）
- **是否需要认证**：是

### 7.7 获取动物认领记录

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

### 7.8 创建认领申请

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

### 7.9 处理认领申请

#### 接口信息
- **接口路径**：`PUT /api/v1/adoptions/{id}/status`
- **接口描述**：处理认领申请（批准/拒绝）
- **是否需要认证**：是

### 7.10 获取认领申请列表

#### 接口信息
- **接口路径**：`GET /api/v1/adoptions`
- **接口描述**：获取认领申请列表
- **是否需要认证**：是

### 7.11 获取动物统计

#### 接口信息
- **接口路径**：`GET /api/v1/animals/stats`
- **接口描述**：获取动物统计数据
- **是否需要认证**：是

### 7.12 批量更新动物状态

#### 接口信息
- **接口路径**：`PUT /api/v1/animals/batch/status`
- **接口描述**：批量更新动物状态
- **是否需要认证**：是

## 8. 订单管理接口

### 8.1 获取订单列表

#### 接口信息
- **接口路径**：`GET /api/v1/orders`
- **接口描述**：获取订单列表，支持分页和筛选
- **是否需要认证**：是

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词（订单号、用户名） |
| status | string | 否 | 订单状态 |
| payment_status | string | 否 | 支付状态 |
| payment_method | string | 否 | 支付方式 |
| amount_min | number | 否 | 最小金额 |
| amount_max | number | 否 | 最大金额 |
| created_start | string | 否 | 创建开始时间 |
| created_end | string | 否 | 创建结束时间 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "order_no": "ORD202401150001",
        "user": {
          "id": 1,
          "username": "user001",
          "nickname": "小明"
        },
        "type": "travel",
        "title": "云南大理古城三日游",
        "amount": 1299.00,
        "status": "completed",
        "payment_status": "paid",
        "payment_method": "wechat",
        "created_at": "2024-01-15T10:00:00Z",
        "paid_at": "2024-01-15T10:05:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 200,
      "pages": 10
    }
  }
}
```

### 8.2 获取订单详情

#### 接口信息
- **接口路径**：`GET /api/v1/orders/{id}`
- **接口描述**：获取指定订单的详细信息
- **是否需要认证**：是

### 8.3 更新订单信息

#### 接口信息
- **接口路径**：`PUT /api/v1/orders/{id}`
- **接口描述**：更新订单信息
- **是否需要认证**：是

### 8.4 删除订单

#### 接口信息
- **接口路径**：`DELETE /api/v1/orders/{id}`
- **接口描述**：删除订单
- **是否需要认证**：是

### 8.5 更新订单状态

#### 接口信息
- **接口路径**：`PUT /api/v1/orders/{id}/status`
- **接口描述**：更新订单状态
- **是否需要认证**：是

### 8.6 订单发货

#### 接口信息
- **接口路径**：`PUT /api/v1/orders/{id}/ship`
- **接口描述**：订单发货
- **是否需要认证**：是

### 8.7 订单完成

#### 接口信息
- **接口路径**：`PUT /api/v1/orders/{id}/complete`
- **接口描述**：订单完成
- **是否需要认证**：是

### 8.8 订单取消

#### 接口信息
- **接口路径**：`PUT /api/v1/orders/{id}/cancel`
- **接口描述**：取消订单
- **是否需要认证**：是

### 8.9 订单退款

#### 接口信息
- **接口路径**：`PUT /api/v1/orders/{id}/refund`
- **接口描述**：订单退款
- **是否需要认证**：是

### 8.10 获取订单统计

#### 接口信息
- **接口路径**：`GET /api/v1/orders/stats`
- **接口描述**：获取订单统计数据
- **是否需要认证**：是

### 8.11 导出订单数据

#### 接口信息
- **接口路径**：`GET /api/v1/orders/export`
- **接口描述**：导出订单数据
- **是否需要认证**：是

### 8.12 获取订单日统计

#### 接口信息
- **接口路径**：`GET /api/v1/orders/daily-stats`
- **接口描述**：获取订单日统计数据
- **是否需要认证**：是

### 8.13 获取订单月统计

#### 接口信息
- **接口路径**：`GET /api/v1/orders/monthly-stats`
- **接口描述**：获取订单月统计数据
- **是否需要认证**：是

### 8.14 批量处理订单

#### 接口信息
- **接口路径**：`PUT /api/v1/orders/batch`
- **接口描述**：批量处理订单
- **是否需要认证**：是

### 8.15 获取支付统计

#### 接口信息
- **接口路径**：`GET /api/v1/orders/payment-stats`
- **接口描述**：获取支付统计数据
- **是否需要认证**：是

## 9. 花卉管理接口

### 9.1 获取花卉列表

#### 接口信息
- **接口路径**：`GET /api/v1/flowers`
- **接口描述**：获取花卉商品列表，支持分页和筛选
- **是否需要认证**：是

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词（花卉名称、品种） |
| category | string | 否 | 花卉类别 |
| status | string | 否 | 状态：active, inactive |
| price_min | number | 否 | 最低价格 |
| price_max | number | 否 | 最高价格 |
| merchant_id | integer | 否 | 商户ID |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "玫瑰花束",
        "category": "rose",
        "variety": "红玫瑰",
        "price": 99.00,
        "stock": 50,
        "images": ["https://example.com/flower/1/1.jpg"],
        "description": "新鲜红玫瑰，适合表达爱意",
        "care_instructions": "保持水分，避免阳光直射",
        "merchant": {
          "id": 1,
          "name": "花语花店"
        },
        "status": "active",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 60,
      "pages": 3
    }
  }
}
```

### 9.2 获取花卉详情

#### 接口信息
- **接口路径**：`GET /api/v1/flowers/{id}`
- **接口描述**：获取指定花卉的详细信息
- **是否需要认证**：是

### 9.3 创建花卉商品

#### 接口信息
- **接口路径**：`POST /api/v1/flowers`
- **接口描述**：创建新的花卉商品
- **是否需要认证**：是

### 9.4 更新花卉信息

#### 接口信息
- **接口路径**：`PUT /api/v1/flowers/{id}`
- **接口描述**：更新花卉信息
- **是否需要认证**：是

### 9.5 删除花卉商品

#### 接口信息
- **接口路径**：`DELETE /api/v1/flowers/{id}`
- **接口描述**：删除花卉商品
- **是否需要认证**：是

### 9.6 获取花卉销售记录

#### 接口信息
- **接口路径**：`GET /api/v1/flowers/{id}/sales`
- **接口描述**：获取花卉销售记录
- **是否需要认证**：是

### 9.7 获取花卉统计

#### 接口信息
- **接口路径**：`GET /api/v1/flowers/stats`
- **接口描述**：获取花卉统计数据
- **是否需要认证**：是

### 9.8 获取花卉商户列表

#### 接口信息
- **接口路径**：`GET /api/v1/flowers/merchants`
- **接口描述**：获取花卉商户列表
- **是否需要认证**：是

### 9.9 批量更新花卉状态

#### 接口信息
- **接口路径**：`PUT /api/v1/flowers/batch/status`
- **接口描述**：批量更新花卉状态
- **是否需要认证**：是

## 10. 促销活动接口

### 10.1 获取促销活动列表

#### 接口信息
- **接口路径**：`GET /api/v1/promotions`
- **接口描述**：获取促销活动列表，支持分页和筛选
- **是否需要认证**：是

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词（活动名称） |
| type | string | 否 | 活动类型：discount, coupon, gift |
| status | string | 否 | 状态：active, inactive, expired |
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "title": "春节特惠活动",
        "description": "全场商品8折优惠",
        "type": "discount",
        "discount_rate": 0.8,
        "min_amount": 100.00,
        "max_discount": 200.00,
        "start_date": "2024-02-01",
        "end_date": "2024-02-15",
        "status": "active",
        "usage_count": 150,
        "usage_limit": 1000,
        "created_at": "2024-01-15T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 30,
      "pages": 2
    }
  }
}
```

### 10.2 获取促销活动详情

#### 接口信息
- **接口路径**：`GET /api/v1/promotions/{id}`
- **接口描述**：获取指定促销活动的详细信息
- **是否需要认证**：是

### 10.3 创建促销活动

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

### 10.4 更新促销活动

#### 接口信息
- **接口路径**：`PUT /api/v1/promotions/{id}`
- **接口描述**：更新促销活动信息
- **是否需要认证**：是

### 10.5 删除促销活动

#### 接口信息
- **接口路径**：`DELETE /api/v1/promotions/{id}`
- **接口描述**：删除促销活动
- **是否需要认证**：是

### 10.6 获取促销活动统计

#### 接口信息
- **接口路径**：`GET /api/v1/promotions/stats`
- **接口描述**：获取促销活动统计数据
- **是否需要认证**：是

### 10.7 获取活动参与记录

#### 接口信息
- **接口路径**：`GET /api/v1/promotions/{id}/participants`
- **接口描述**：获取活动参与记录
- **是否需要认证**：是

### 10.8 获取奖励记录

#### 接口信息
- **接口路径**：`GET /api/v1/rewards`
- **接口描述**：获取奖励记录列表
- **是否需要认证**：是

### 10.9 创建奖励记录

#### 接口信息
- **接口路径**：`POST /api/v1/rewards`
- **接口描述**：创建奖励记录
- **是否需要认证**：是

### 10.10 获取促销活动模板

#### 接口信息
- **接口路径**：`GET /api/v1/promotions/templates`
- **接口描述**：获取促销活动模板
- **是否需要认证**：是

## 11. 系统管理接口

### 11.1 获取系统服务列表

#### 接口信息
- **接口路径**：`GET /api/v1/system/services`
- **接口描述**：获取系统服务状态列表
- **是否需要认证**：是

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "数据库服务",
      "type": "database",
      "status": "running",
      "health": "healthy",
      "cpu_usage": 15.5,
      "memory_usage": 45.2,
      "last_check": "2024-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "name": "Redis缓存",
      "type": "cache",
      "status": "running",
      "health": "healthy",
      "cpu_usage": 5.2,
      "memory_usage": 25.8,
      "last_check": "2024-01-15T10:30:00Z"
    }
  ]
}
```

### 11.2 更新服务状态

#### 接口信息
- **接口路径**：`PUT /api/v1/system/services/{id}/status`
- **接口描述**：更新系统服务状态
- **是否需要认证**：是

### 11.3 获取系统统计

#### 接口信息
- **接口路径**：`GET /api/v1/system/stats`
- **接口描述**：获取系统统计信息
- **是否需要认证**：是

### 11.4 获取系统日志

#### 接口信息
- **接口路径**：`GET /api/v1/system/logs`
- **接口描述**：获取系统日志
- **是否需要认证**：是

### 11.5 清理系统日志

#### 接口信息
- **接口路径**：`DELETE /api/v1/system/logs`
- **接口描述**：清理系统日志
- **是否需要认证**：是

### 11.6 获取系统配置

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

### 11.7 更新系统配置

#### 接口信息
- **接口路径**：`PUT /api/v1/system/config`
- **接口描述**：更新系统配置
- **是否需要认证**：是

### 11.8 系统备份

#### 接口信息
- **接口路径**：`POST /api/v1/system/backup`
- **接口描述**：创建系统备份
- **是否需要认证**：是

### 11.9 系统恢复

#### 接口信息
- **接口路径**：`POST /api/v1/system/restore`
- **接口描述**：系统恢复
- **是否需要认证**：是

### 11.10 获取监控数据

#### 接口信息
- **接口路径**：`GET /api/v1/system/monitoring`
- **接口描述**：获取系统监控数据
- **是否需要认证**：是

### 11.11 获取性能指标

#### 接口信息
- **接口路径**：`GET /api/v1/system/metrics`
- **接口描述**：获取系统性能指标
- **是否需要认证**：是

### 11.12 系统健康检查

#### 接口信息
- **接口路径**：`GET /api/v1/system/health`
- **接口描述**：系统健康检查
- **是否需要认证**：否

## 12. 仪表板接口

### 12.1 获取仪表板数据

#### 接口信息
- **接口路径**：`GET /api/v1/dashboard`
- **接口描述**：获取仪表板统计数据
- **是否需要认证**：是

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "overview": {
      "total_users": 1250,
      "total_orders": 3580,
      "total_revenue": 125000.00,
      "active_travels": 45
    },
    "recent_stats": {
      "new_users_today": 12,
      "orders_today": 28,
      "revenue_today": 3500.00
    },
    "growth_rate": {
      "users": 15.5,
      "orders": 22.3,
      "revenue": 18.7
    }
  }
}
```

### 12.2 获取用户增长数据

#### 接口信息
- **接口路径**：`GET /api/v1/dashboard/user-growth`
- **接口描述**：获取用户增长趋势数据
- **是否需要认证**：是

### 12.3 获取订单趋势数据

#### 接口信息
- **接口路径**：`GET /api/v1/dashboard/order-trends`
- **接口描述**：获取订单趋势数据
- **是否需要认证**：是

### 12.4 获取收入统计

#### 接口信息
- **接口路径**：`GET /api/v1/dashboard/revenue-stats`
- **接口描述**：获取收入统计数据
- **是否需要认证**：是

### 12.5 获取热门商品

#### 接口信息
- **接口路径**：`GET /api/v1/dashboard/popular-items`
- **接口描述**：获取热门商品数据
- **是否需要认证**：是

### 12.6 获取实时数据

#### 接口信息
- **接口路径**：`GET /api/v1/dashboard/realtime`
- **接口描述**：获取实时统计数据
- **是否需要认证**：是

## 13. 权限管理接口

### 13.1 获取权限列表

#### 接口信息
- **接口路径**：`GET /api/v1/permissions`
- **接口描述**：获取权限列表，支持分页和筛选
- **是否需要认证**：是

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词（权限名称、描述） |
| module | string | 否 | 权限模块 |
| type | string | 否 | 权限类型：read, write, delete, manage |

#### 响应示例
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "user:read",
        "display_name": "查看用户",
        "description": "查看用户信息的权限",
        "module": "user",
        "type": "read",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 50,
      "pages": 3
    }
  }
}
```

### 13.2 获取权限详情

#### 接口信息
- **接口路径**：`GET /api/v1/permissions/{id}`
- **接口描述**：获取指定权限的详细信息
- **是否需要认证**：是

### 13.3 创建权限

#### 接口信息
- **接口路径**：`POST /api/v1/permissions`
- **接口描述**：创建新权限
- **是否需要认证**：是

### 13.4 更新权限

#### 接口信息
- **接口路径**：`PUT /api/v1/permissions/{id}`
- **接口描述**：更新权限信息
- **是否需要认证**：是

### 13.5 删除权限

#### 接口信息
- **接口路径**：`DELETE /api/v1/permissions/{id}`
- **接口描述**：删除权限
- **是否需要认证**：是

### 13.6 获取角色列表

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

### 13.7 创建角色

#### 接口信息
- **接口路径**：`POST /api/v1/roles`
- **接口描述**：创建新角色
- **是否需要认证**：是

### 13.8 分配权限给角色

#### 接口信息
- **接口路径**：`PUT /api/v1/roles/{id}/permissions`
- **接口描述**：为角色分配权限
- **是否需要认证**：是

## 14. 错误码说明

### 14.1 通用错误码

| 错误码 | HTTP状态码 | 说明 |
|--------|------------|------|
| 10000 | 200 | 操作成功 |
| 10001 | 400 | 请求参数错误 |
| 10002 | 401 | 未授权访问 |
| 10003 | 403 | 权限不足 |
| 10004 | 404 | 资源不存在 |
| 10005 | 409 | 资源冲突 |
| 10006 | 422 | 业务逻辑错误 |
| 10007 | 500 | 内部服务器错误 |

### 14.2 业务错误码

| 错误码 | 说明 |
|--------|------|
| 20001 | 用户名或密码错误 |
| 20002 | 用户不存在 |
| 20003 | 用户已被禁用 |
| 20004 | 用户名已存在 |
| 20005 | 邮箱已存在 |
| 20006 | 手机号已存在 |
| 30001 | 商户不存在 |
| 30002 | 商户已被禁用 |
| 40001 | 旅行活动不存在 |
| 40002 | 旅行活动已满员 |
| 40003 | 旅行活动已结束 |
| 50001 | 动物不存在 |
| 50002 | 动物已被认领 |
| 50003 | 认领申请不存在 |
| 60001 | 订单不存在 |
| 60002 | 订单状态错误 |
| 60003 | 订单已支付 |
| 60004 | 订单已取消 |

## 15. 接口测试

### 15.1 测试环境
- **测试地址**：`https://api-test.jiebanke.com`
- **测试账号**：admin / admin123
- **API文档**：`https://api-test.jiebanke.com/docs`

### 15.2 测试工具推荐
- **Postman**：用于API接口测试
- **Swagger UI**：在线API文档和测试
- **curl**：命令行测试工具

### 15.3 测试示例

#### 登录测试
```bash
curl -X POST "https://api-test.jiebanke.com/api/v1/admin/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'
```

#### 获取用户列表测试
```bash
curl -X GET "https://api-test.jiebanke.com/api/v1/users?page=1&size=10" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## 16. 版本更新记录

### v1.0.0 (2024-01-15)
- 初始版本发布
- 完成所有核心模块API设计
- 支持用户管理、旅行管理、动物认领等功能

### v1.1.0 (2024-01-20)
- 新增花卉管理模块
- 新增促销活动模块
- 优化权限管理功能

### v1.2.0 (2024-01-25)
- 新增仪表板统计接口
- 新增系统监控功能
- 优化错误处理机制

## 17. 总结

本文档详细描述了结伴客管理后台系统的所有API接口设计，涵盖了用户管理、商户管理、旅行管理、动物认领、订单管理、花卉管理、促销活动、系统管理、仪表板统计和权限管理等11个核心模块，共计100+个API接口。

所有接口均遵循RESTful设计原则，采用统一的请求响应格式，支持JWT认证和权限控制。文档提供了详细的接口说明、参数定义、响应示例和错误码说明，为前端开发和接口对接提供了完整的技术规范。

随着业务的发展，本文档将持续更新和完善，确保API设计的准确性和实用性。