# 爱鉴花后台管理系统 API 接口文档

## 概述
本文档描述了爱鉴花后台管理系统的 RESTful API 接口规范，基于 OpenAPI 3.0 标准。

## 基础信息
- **Base URL**: `http://localhost:3200/api/v1`
- **认证方式**: Bearer Token (JWT)
- **响应格式**: JSON

## 通用响应格式
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {}
}
```

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

## 用户管理接口

### 1. 获取用户列表

**接口摘要**: 获取用户列表（需要管理员权限）

**请求方法**: `GET`
**请求路径**: `/users`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| limit | integer | 否 | 每页数量，默认10 |
| keyword | string | 否 | 搜索关键词（用户名/手机号/邮箱） |
| user_type | string | 否 | 用户类型（farmer/buyer/admin） |

**请求示例**:
```http
GET /api/v1/users?page=1&limit=10&keyword=test&user_type=farmer
Authorization: Bearer <token>
```

**响应示例 (200)**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "users": [
      {
        "id": 1,
        "username": "testuser",
        "phone": "13800138000",
        "email": "test@example.com",
        "user_type": "farmer",
        "avatar_url": null,
        "created_at": "2023-12-01 10:00:00",
        "last_login": "2023-12-15 15:30:00"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 100,
      "pages": 10
    }
  }
}
```

### 2. 创建用户

**接口摘要**: 创建新用户（需要管理员权限）

**请求方法**: `POST`
**请求路径**: `/users`

**请求体**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 是 | 用户名 |
| phone | string | 是 | 手机号 |
| email | string | 是 | 邮箱地址 |
| user_type | string | 是 | 用户类型（farmer/buyer/admin） |
| password | string | 是 | 密码（最少6位） |
| real_name | string | 否 | 真实姓名 |
| avatar_url | string | 否 | 头像URL |

**请求示例**:
```http
POST /api/v1/users
Authorization: Bearer <token>
Content-Type: application/json

{
  "username": "newuser",
  "phone": "13900139000",
  "email": "newuser@example.com",
  "user_type": "buyer",
  "password": "123456",
  "real_name": "张三",
  "avatar_url": null
}
```

**响应示例 (201)**:
```json
{
  "code": 201,
  "message": "用户创建成功",
  "data": {
    "id": 2,
    "username": "newuser",
    "phone": "13900139000",
    "email": "newuser@example.com",
    "user_type": "buyer",
    "avatar_url": null,
    "real_name": "张三"
  }
}
```

**错误响应示例 (409)**:
```json
{
  "code": 409,
  "message": "用户名已存在",
  "data": null
}
```

### 3. 获取用户详情

**接口摘要**: 获取指定用户的详细信息

**请求方法**: `GET`
**请求路径**: `/users/{id}`

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

**请求示例**:
```http
GET /api/v1/users/1
Authorization: Bearer <token>
```

**响应示例 (200)**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "phone": "13800138000",
    "email": "test@example.com",
    "user_type": "farmer",
    "avatar_url": null,
    "real_name": "测试用户",
    "created_at": "2023-12-01 10:00:00",
    "last_login": "2023-12-15 15:30:00"
  }
}
```

### 4. 更新用户信息

**接口摘要**: 更新用户信息

**请求方法**: `PUT`
**请求路径**: `/users/{id}`

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

**请求体**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 否 | 用户名 |
| phone | string | 否 | 手机号 |
| email | string | 否 | 邮箱地址 |
| user_type | string | 否 | 用户类型 |
| real_name | string | 否 | 真实姓名 |
| avatar_url | string | 否 | 头像URL |

**请求示例**:
```http
PUT /api/v1/users/1
Authorization: Bearer <token>
Content-Type: application/json

{
  "username": "updateduser",
  "phone": "13800138001",
  "email": "updated@example.com",
  "user_type": "admin",
  "real_name": "更新用户"
}
```

**响应示例 (200)**:
```json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "username": "updateduser",
    "phone": "13800138001",
    "email": "updated@example.com",
    "user_type": "admin",
    "avatar_url": null,
    "real_name": "更新用户"
  }
}
```

### 5. 删除用户

**接口摘要**: 删除用户（软删除，需要管理员权限）

**请求方法**: `DELETE`
**请求路径**: `/users/{id}`

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

**请求示例**:
```http
DELETE /api/v1/users/1
Authorization: Bearer <token>
```

**响应示例 (200)**:
```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

### 6. 修改密码

**接口摘要**: 修改用户密码

**请求方法**: `PUT`
**请求路径**: `/users/{id}/password`

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

**请求体**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| old_password | string | 是 | 原密码 |
| new_password | string | 是 | 新密码（最少6位） |

**请求示例**:
```http
PUT /api/v1/users/1/password
Authorization: Bearer <token>
Content-Type: application/json

{
  "old_password": "oldpassword123",
  "new_password": "newpassword456"
}
```

**响应示例 (200)**:
```json
{
  "code": 200,
  "message": "密码修改成功",
  "data": null
}
```

## 认证接口

### 1. 用户登录

**接口摘要**: 用户登录获取访问令牌

**请求方法**: `POST`
**请求路径**: `/auth/login`

**请求体**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |

**请求示例**:
```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}
```

**响应示例 (200)**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin",
      "user_type": "admin"
    }
  }
}
```

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

**接口摘要**: 获取当前登录用户信息

**请求方法**: `GET`
**请求路径**: `/users/me`

**请求示例**:
```http
GET /api/v1/users/me
Authorization: Bearer <token>
```

**响应示例 (200)**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "admin",
    "phone": "13800138000",
    "email": "admin@example.com",
    "user_type": "admin",
    "avatar_url": null,
    "real_name": "管理员",
    "created_at": "2023-12-01 10:00:00",
    "last_login": "2023-12-15 15:30:00"
  }
}
```