aijianhua/docs/后台管理系统API文档.md

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

基于 OpenAPI 3.0 规范

## 基础信息

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

## 统一响应格式

所有接口都遵循以下响应格式：

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {}
}
```

## 认证接口

### 管理员登录

**POST** `/auth/login`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| login | string | 是 | 用户名/手机号/邮箱 |
| password | string | 是 | 密码 |

**响应示例**:

```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user_id": 1,
    "username": "admin",
    "user_type": "admin",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

## 用户管理接口

### 获取用户列表

**GET** `/users`

**权限要求**: 管理员

**查询参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | number | 否 | 页码，默认1 |
| limit | number | 否 | 每页数量，默认10 |
| keyword | string | 否 | 搜索关键词 |
| user_type | string | 否 | 用户类型过滤 |

**响应示例**:

```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "users": [
      {
        "id": 1,
        "username": "testuser",
        "phone": "13800138000",
        "email": "test@example.com",
        "user_type": "farmer",
        "created_at": "2024-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 100,
      "pages": 10
    }
  }
}
```

### 获取用户详情

**GET** `/users/{id}`

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | number | 是 | 用户ID |

### 删除用户

**DELETE** `/users/{id}`

**权限要求**: 管理员

## 商品管理接口

### 获取商品列表

**GET** `/products`

**查询参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | number | 否 | 页码，默认1 |
| limit | number | 否 | 每页数量，默认10 |
| category_id | number | 否 | 分类ID过滤 |
| min_price | number | 否 | 最低价格 |
| max_price | number | 否 | 最高价格 |
| status | number | 否 | 状态过滤 |

### 创建商品

**POST** `/products`

**权限要求**: 管理员

**请求体**:

```json
{
  "name": "玫瑰花",
  "category_id": 1,
  "price": 29.9,
  "stock": 100,
  "image": "/uploads/roses.jpg",
  "description": "新鲜玫瑰花束"
}
```

## 订单管理接口

### 获取订单列表

**GET** `/orders`

**权限要求**: 管理员

**查询参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | number | 否 | 页码，默认1 |
| limit | number | 否 | 每页数量，默认10 |
| status | number | 否 | 订单状态过滤 |
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |

### 更新订单状态

**PUT** `/orders/{id}/status`

**权限要求**: 管理员

**请求体**:

```json
{
  "payment_status": 1,
  "shipping_status": 2
}
```

## 识别记录管理接口

### 获取识别记录列表

**GET** `/identifications`

**权限要求**: 管理员

**查询参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | number | 否 | 页码，默认1 |
| limit | number | 否 | 每页数量，默认10 |
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |
| min_confidence | number | 否 | 最低置信度 |

## 数据统计接口

### 获取系统统计概览

**GET** `/admin/statistics/overview`

**权限要求**: 管理员

**响应示例**:

```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total_users": 1000,
    "new_users_today": 10,
    "total_orders": 500,
    "total_revenue": 15000.50,
    "total_identifications": 2000,
    "active_users_today": 50
  }
}
```

### 获取趋势数据

**GET** `/admin/statistics/trend`

**查询参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| days | number | 否 | 天数，默认7 |
| type | string | 否 | 统计类型（users/orders/revenue/identifications） |

## 系统配置接口

### 获取系统配置

**GET** `/admin/config`

**权限要求**: 管理员

### 更新系统配置

**PUT** `/admin/config/{key}`

**权限要求**: 管理员

**请求体**:

```json
{
  "value": "new_value"
}
```

## 错误码说明

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 200 | 成功 | 请求成功 |
| 201 | 创建成功 | 资源创建成功 |
| 400 | 参数错误 | 请求参数验证失败 |
| 401 | 未授权 | 需要登录认证 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 资源不存在 | 请求的资源不存在 |
| 409 | 资源冲突 | 资源已存在或状态冲突 |
| 500 | 服务器内部错误 | 服务器内部处理错误 |
| 1001 | 识别失败 | 植物识别处理失败 |
| 1002 | 图片格式不支持 | 上传的图片格式不支持 |
| 2001 | 推广奖励不足 | 可提现余额不足50元 |
| 2002 | 提现频率限制 | 24小时内只能提现一次 |
| 3001 | 库存不足 | 商品库存不足 |
| 3002 | 订单状态异常 | 订单状态不允许此操作 |

## 安全要求

1. 所有敏感操作需要管理员权限
2. API请求需要携带有效的JWT Token
3. 密码传输需要加密
4. 文件上传需要验证文件类型和大小

---

*文档版本: 1.0.0*  
*最后更新: 2024-03-15*