# 管理后台接口设计文档

## 版本历史
| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|----------|
| 1.0 | 2024-01-20 | 后端团队 | 初始版本 |

## 1. 接口概述

### 1.1 设计原则
- **RESTful风格**: 遵循REST架构风格，使用标准HTTP方法
- **统一响应格式**: 所有接口返回统一的JSON格式
- **版本控制**: 通过URL路径进行API版本管理
- **安全认证**: 基于JWT的身份认证和权限控制
- **参数验证**: 严格的输入参数验证和错误处理
- **文档完整**: 详细的接口文档和示例

### 1.2 基础信息
- **Base URL**: `https://api.xlxumu.com/admin/v1`
- **Content-Type**: `application/json`
- **字符编码**: `UTF-8`
- **认证方式**: `Bearer Token (JWT)`

### 1.3 通用响应格式
```json
{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": 1705747200000,
  "request_id": "req_123456789"
}
```

### 1.4 错误响应格式
```json
{
  "success": false,
  "code": 400,
  "message": "参数错误",
  "errors": [
    {
      "field": "username",
      "message": "用户名不能为空"
    }
  ],
  "timestamp": 1705747200000,
  "request_id": "req_123456789"
}
```

### 1.5 状态码说明
| 状态码 | 说明 | 描述 |
|--------|------|------|
| 200 | OK | 请求成功 |
| 201 | Created | 创建成功 |
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 未授权 |
| 403 | Forbidden | 禁止访问 |
| 404 | Not Found | 资源不存在 |
| 409 | Conflict | 资源冲突 |
| 422 | Unprocessable Entity | 参数验证失败 |
| 500 | Internal Server Error | 服务器内部错误 |

## 2. 认证授权

### 2.1 登录认证

#### 2.1.1 管理员登录
**接口地址**: `POST /auth/login`

**请求参数**:
```json
{
  "username": "admin",
  "password": "password123",
  "captcha": "ABCD",
  "captcha_key": "captcha_key_123"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "refresh_token_123",
    "expires_in": 7200,
    "user": {
      "id": 1,
      "username": "admin",
      "real_name": "系统管理员",
      "avatar": "https://example.com/avatar.jpg",
      "roles": ["super_admin"],
      "permissions": ["*"]
    }
  }
}
```

#### 2.1.2 刷新Token
**接口地址**: `POST /auth/refresh`

**请求参数**:
```json
{
  "refresh_token": "refresh_token_123"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "刷新成功",
  "data": {
    "token": "new_jwt_token",
    "expires_in": 7200
  }
}
```

#### 2.1.3 退出登录
**接口地址**: `POST /auth/logout`

**请求头**:
```
Authorization: Bearer {token}
```

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

### 2.2 权限验证

#### 2.2.1 获取用户信息
**接口地址**: `GET /auth/user`

**请求头**:
```
Authorization: Bearer {token}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "admin",
    "real_name": "系统管理员",
    "avatar": "https://example.com/avatar.jpg",
    "roles": ["super_admin"],
    "permissions": ["*"],
    "last_login_at": "2024-01-20 10:30:00",
    "last_login_ip": "192.168.1.100"
  }
}
```

#### 2.2.2 获取用户菜单
**接口地址**: `GET /auth/menus`

**请求头**:
```
Authorization: Bearer {token}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "系统管理",
      "path": "/system",
      "icon": "system",
      "sort_order": 1,
      "children": [
        {
          "id": 2,
          "name": "用户管理",
          "path": "/system/users",
          "icon": "user",
          "sort_order": 1
        }
      ]
    }
  ]
}
```

## 3. 用户管理

### 3.1 用户列表

#### 3.1.1 获取用户列表
**接口地址**: `GET /users`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词 |
| status | int | 否 | 用户状态：0-禁用，1-正常 |
| role_id | int | 否 | 角色ID |
| created_start | string | 否 | 创建开始时间 |
| created_end | string | 否 | 创建结束时间 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "username": "farmer001",
        "real_name": "张三",
        "phone": "138****8000",
        "email": "zhang@example.com",
        "avatar": "https://example.com/avatar.jpg",
        "status": 1,
        "roles": [
          {
            "id": 2,
            "name": "养殖户",
            "code": "farmer"
          }
        ],
        "last_login_at": "2024-01-20 10:30:00",
        "created_at": "2024-01-15 09:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 100,
      "total_pages": 5
    }
  }
}
```

### 3.2 用户详情

#### 3.2.1 获取用户详情
**接口地址**: `GET /users/{id}`

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

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "farmer001",
    "real_name": "张三",
    "phone": "13800138000",
    "email": "zhang@example.com",
    "avatar": "https://example.com/avatar.jpg",
    "gender": 1,
    "birthday": "1990-01-01",
    "address": "北京市朝阳区",
    "id_card": "110101199001010001",
    "status": 1,
    "roles": [
      {
        "id": 2,
        "name": "养殖户",
        "code": "farmer"
      }
    ],
    "farms": [
      {
        "id": 1,
        "name": "张三养猪场",
        "type": "pig",
        "status": 1
      }
    ],
    "last_login_at": "2024-01-20 10:30:00",
    "last_login_ip": "192.168.1.100",
    "created_at": "2024-01-15 09:00:00",
    "updated_at": "2024-01-20 10:30:00"
  }
}
```

### 3.3 用户操作

#### 3.3.1 创建用户
**接口地址**: `POST /users`

**请求参数**:
```json
{
  "username": "farmer002",
  "password": "password123",
  "real_name": "李四",
  "phone": "13900139000",
  "email": "li@example.com",
  "gender": 1,
  "birthday": "1985-05-15",
  "address": "上海市浦东新区",
  "role_ids": [2]
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 2,
    "username": "farmer002",
    "real_name": "李四",
    "phone": "139****9000",
    "email": "li@example.com",
    "status": 1,
    "created_at": "2024-01-20 11:00:00"
  }
}
```

#### 3.3.2 更新用户
**接口地址**: `PUT /users/{id}`

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

**请求参数**:
```json
{
  "real_name": "李四四",
  "phone": "13900139001",
  "email": "li4@example.com",
  "gender": 1,
  "birthday": "1985-05-15",
  "address": "上海市浦东新区张江镇",
  "role_ids": [2, 3]
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 2,
    "username": "farmer002",
    "real_name": "李四四",
    "phone": "139****9001",
    "email": "li4@example.com",
    "updated_at": "2024-01-20 11:30:00"
  }
}
```

#### 3.3.3 删除用户
**接口地址**: `DELETE /users/{id}`

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

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

#### 3.3.4 批量删除用户
**接口地址**: `DELETE /users`

**请求参数**:
```json
{
  "ids": [1, 2, 3]
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "批量删除成功",
  "data": {
    "deleted_count": 3
  }
}
```

#### 3.3.5 重置用户密码
**接口地址**: `POST /users/{id}/reset-password`

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

**请求参数**:
```json
{
  "new_password": "newpassword123"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "密码重置成功"
}
```

#### 3.3.6 启用/禁用用户
**接口地址**: `POST /users/{id}/toggle-status`

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

**请求参数**:
```json
{
  "status": 0
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "状态更新成功",
  "data": {
    "id": 1,
    "status": 0
  }
}
```

## 4. 角色权限管理

### 4.1 角色管理

#### 4.1.1 获取角色列表
**接口地址**: `GET /roles`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词 |
| status | int | 否 | 角色状态 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "超级管理员",
        "code": "super_admin",
        "description": "系统超级管理员，拥有所有权限",
        "status": 1,
        "user_count": 1,
        "created_at": "2024-01-01 00:00:00"
      },
      {
        "id": 2,
        "name": "养殖户",
        "code": "farmer",
        "description": "普通养殖户用户",
        "status": 1,
        "user_count": 50,
        "created_at": "2024-01-01 00:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 5,
      "total_pages": 1
    }
  }
}
```

#### 4.1.2 获取角色详情
**接口地址**: `GET /roles/{id}`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 角色ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 2,
    "name": "养殖户",
    "code": "farmer",
    "description": "普通养殖户用户",
    "status": 1,
    "permissions": [
      {
        "id": 10,
        "name": "查看养殖场",
        "code": "farm:view",
        "type": "api"
      },
      {
        "id": 11,
        "name": "管理动物",
        "code": "animal:manage",
        "type": "api"
      }
    ],
    "users": [
      {
        "id": 1,
        "username": "farmer001",
        "real_name": "张三"
      }
    ],
    "created_at": "2024-01-01 00:00:00",
    "updated_at": "2024-01-15 10:00:00"
  }
}
```

#### 4.1.3 创建角色
**接口地址**: `POST /roles`

**请求参数**:
```json
{
  "name": "运营管理员",
  "code": "operator",
  "description": "负责平台运营管理",
  "permission_ids": [10, 11, 12, 13]
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 3,
    "name": "运营管理员",
    "code": "operator",
    "description": "负责平台运营管理",
    "status": 1,
    "created_at": "2024-01-20 12:00:00"
  }
}
```

#### 4.1.4 更新角色
**接口地址**: `PUT /roles/{id}`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 角色ID |

**请求参数**:
```json
{
  "name": "高级运营管理员",
  "description": "负责平台高级运营管理",
  "permission_ids": [10, 11, 12, 13, 14, 15]
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 3,
    "name": "高级运营管理员",
    "description": "负责平台高级运营管理",
    "updated_at": "2024-01-20 12:30:00"
  }
}
```

#### 4.1.5 删除角色
**接口地址**: `DELETE /roles/{id}`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 角色ID |

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

### 4.2 权限管理

#### 4.2.1 获取权限树
**接口地址**: `GET /permissions/tree`

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "系统管理",
      "code": "system",
      "type": "menu",
      "path": "/system",
      "icon": "system",
      "sort_order": 1,
      "children": [
        {
          "id": 2,
          "name": "用户管理",
          "code": "system:user",
          "type": "menu",
          "path": "/system/users",
          "icon": "user",
          "sort_order": 1,
          "children": [
            {
              "id": 3,
              "name": "查看用户",
              "code": "system:user:view",
              "type": "button",
              "sort_order": 1
            },
            {
              "id": 4,
              "name": "创建用户",
              "code": "system:user:create",
              "type": "button",
              "sort_order": 2
            }
          ]
        }
      ]
    }
  ]
}
```

#### 4.2.2 获取权限列表
**接口地址**: `GET /permissions`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| type | string | 否 | 权限类型：menu,button,api |
| parent_id | int | 否 | 父权限ID |
| status | int | 否 | 权限状态 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "系统管理",
      "code": "system",
      "type": "menu",
      "parent_id": null,
      "path": "/system",
      "icon": "system",
      "sort_order": 1,
      "status": 1,
      "created_at": "2024-01-01 00:00:00"
    }
  ]
}
```

#### 4.2.3 创建权限
**接口地址**: `POST /permissions`

**请求参数**:
```json
{
  "name": "财务管理",
  "code": "finance",
  "type": "menu",
  "parent_id": null,
  "path": "/finance",
  "icon": "finance",
  "sort_order": 3
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 20,
    "name": "财务管理",
    "code": "finance",
    "type": "menu",
    "parent_id": null,
    "path": "/finance",
    "icon": "finance",
    "sort_order": 3,
    "status": 1,
    "created_at": "2024-01-20 13:00:00"
  }
}
```

## 5. 养殖场管理

### 5.1 养殖场列表

#### 5.1.1 获取养殖场列表
**接口地址**: `GET /farms`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词 |
| type | string | 否 | 养殖类型 |
| status | int | 否 | 养殖场状态 |
| province | string | 否 | 省份 |
| city | string | 否 | 城市 |
| user_id | int | 否 | 用户ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "张三养猪场",
        "code": "FARM001",
        "type": "pig",
        "area": 5000.00,
        "capacity": 500,
        "address": "北京市朝阳区某某村",
        "province": "北京市",
        "city": "北京市",
        "district": "朝阳区",
        "status": 1,
        "user": {
          "id": 1,
          "username": "farmer001",
          "real_name": "张三"
        },
        "animal_count": 150,
        "created_at": "2024-01-15 09:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 50,
      "total_pages": 3
    }
  }
}
```

### 5.2 养殖场详情

#### 5.2.1 获取养殖场详情
**接口地址**: `GET /farms/{id}`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 养殖场ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "name": "张三养猪场",
    "code": "FARM001",
    "type": "pig",
    "area": 5000.00,
    "capacity": 500,
    "address": "北京市朝阳区某某村123号",
    "province": "北京市",
    "city": "北京市",
    "district": "朝阳区",
    "longitude": 116.407526,
    "latitude": 39.904030,
    "license_number": "京农许字[2024]001号",
    "license_image": "https://example.com/license.jpg",
    "description": "专业养猪场，采用现代化养殖技术",
    "status": 1,
    "user": {
      "id": 1,
      "username": "farmer001",
      "real_name": "张三",
      "phone": "138****8000"
    },
    "statistics": {
      "total_animals": 150,
      "healthy_animals": 145,
      "sick_animals": 5,
      "total_value": 150000.00
    },
    "created_at": "2024-01-15 09:00:00",
    "updated_at": "2024-01-20 10:00:00"
  }
}
```

### 5.3 养殖场操作

#### 5.3.1 审核养殖场
**接口地址**: `POST /farms/{id}/audit`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 养殖场ID |

**请求参数**:
```json
{
  "status": 1,
  "audit_notes": "审核通过，符合养殖标准"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "审核成功",
  "data": {
    "id": 1,
    "status": 1,
    "audit_notes": "审核通过，符合养殖标准",
    "audited_at": "2024-01-20 14:00:00"
  }
}
```

#### 5.3.2 获取养殖场统计
**接口地址**: `GET /farms/{id}/statistics`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 养殖场ID |

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "basic_stats": {
      "total_animals": 150,
      "healthy_animals": 145,
      "sick_animals": 5,
      "dead_animals": 0,
      "total_value": 150000.00
    },
    "breed_stats": [
      {
        "breed": "杜洛克猪",
        "count": 80,
        "percentage": 53.33
      },
      {
        "breed": "长白猪",
        "count": 70,
        "percentage": 46.67
      }
    ],
    "health_stats": {
      "vaccination_rate": 95.5,
      "health_check_rate": 100.0,
      "disease_rate": 3.33
    },
    "financial_stats": {
      "total_income": 50000.00,
      "total_expense": 30000.00,
      "net_profit": 20000.00,
      "profit_margin": 40.0
    }
  }
}
```

## 6. 动物管理

### 6.1 动物列表

#### 6.1.1 获取动物列表
**接口地址**: `GET /animals`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词 |
| farm_id | int | 否 | 养殖场ID |
| category_id | int | 否 | 动物分类ID |
| breed | string | 否 | 品种 |
| gender | int | 否 | 性别 |
| health_status | string | 否 | 健康状态 |
| status | int | 否 | 动物状态 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "code": "PIG001",
        "name": "小猪001",
        "breed": "杜洛克猪",
        "gender": 1,
        "birth_date": "2023-06-15",
        "age_days": 219,
        "weight": 85.5,
        "health_status": "healthy",
        "status": 1,
        "farm": {
          "id": 1,
          "name": "张三养猪场",
          "user": {
            "id": 1,
            "real_name": "张三"
          }
        },
        "category": {
          "id": 1,
          "name": "猪",
          "code": "pig"
        },
        "purchase_price": 800.00,
        "current_value": 1200.00,
        "created_at": "2023-06-15 10:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 500,
      "total_pages": 25
    }
  }
}
```

### 6.2 动物详情

#### 6.2.1 获取动物详情
**接口地址**: `GET /animals/{id}`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 动物ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "code": "PIG001",
    "name": "小猪001",
    "breed": "杜洛克猪",
    "gender": 1,
    "birth_date": "2023-06-15",
    "age_days": 219,
    "weight": 85.5,
    "health_status": "healthy",
    "status": 1,
    "farm": {
      "id": 1,
      "name": "张三养猪场",
      "code": "FARM001",
      "user": {
        "id": 1,
        "username": "farmer001",
        "real_name": "张三"
      }
    },
    "category": {
      "id": 1,
      "name": "猪",
      "code": "pig"
    },
    "parents": {
      "father": {
        "id": 10,
        "code": "PIG010",
        "name": "种猪公001"
      },
      "mother": {
        "id": 11,
        "code": "PIG011",
        "name": "种猪母001"
      }
    },
    "purchase_info": {
      "price": 800.00,
      "date": "2023-06-15",
      "source": "本地养殖场"
    },
    "current_value": 1200.00,
    "notes": "生长良好，无疾病史",
    "health_records_count": 5,
    "vaccination_records_count": 3,
    "created_at": "2023-06-15 10:00:00",
    "updated_at": "2024-01-20 10:00:00"
  }
}
```

### 6.3 健康记录

#### 6.3.1 获取动物健康记录
**接口地址**: `GET /animals/{id}/health-records`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 动物ID |

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |
| record_type | string | 否 | 记录类型 |
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "record_type": "checkup",
        "record_date": "2024-01-15",
        "symptoms": null,
        "diagnosis": "健康状况良好",
        "treatment": null,
        "medicine": null,
        "dosage": null,
        "veterinarian": "李兽医",
        "cost": 50.00,
        "next_checkup_date": "2024-02-15",
        "notes": "定期健康检查",
        "images": [
          "https://example.com/health1.jpg"
        ],
        "created_by": {
          "id": 1,
          "real_name": "张三"
        },
        "created_at": "2024-01-15 14:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 5,
      "total_pages": 1
    }
  }
}
```

## 7. 订单管理

### 7.1 订单列表

#### 7.1.1 获取订单列表
**接口地址**: `GET /orders`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词(订单号) |
| order_type | string | 否 | 订单类型 |
| order_status | string | 否 | 订单状态 |
| payment_status | string | 否 | 支付状态 |
| buyer_id | int | 否 | 买家ID |
| seller_id | int | 否 | 卖家ID |
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "order_no": "ORD202401200001",
        "order_type": "animal",
        "total_amount": 2400.00,
        "discount_amount": 0.00,
        "shipping_fee": 100.00,
        "actual_amount": 2500.00,
        "payment_method": "alipay",
        "payment_status": "paid",
        "order_status": "confirmed",
        "buyer": {
          "id": 2,
          "username": "buyer001",
          "real_name": "李四"
        },
        "seller": {
          "id": 1,
          "username": "farmer001",
          "real_name": "张三"
        },
        "farm": {
          "id": 1,
          "name": "张三养猪场"
        },
        "item_count": 2,
        "paid_at": "2024-01-20 10:30:00",
        "created_at": "2024-01-20 10:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 100,
      "total_pages": 5
    }
  }
}
```

### 7.2 订单详情

#### 7.2.1 获取订单详情
**接口地址**: `GET /orders/{id}`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 订单ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "order_no": "ORD202401200001",
    "order_type": "animal",
    "total_amount": 2400.00,
    "discount_amount": 0.00,
    "shipping_fee": 100.00,
    "actual_amount": 2500.00,
    "payment_method": "alipay",
    "payment_status": "paid",
    "order_status": "confirmed",
    "buyer": {
      "id": 2,
      "username": "buyer001",
      "real_name": "李四",
      "phone": "139****9000"
    },
    "seller": {
      "id": 1,
      "username": "farmer001",
      "real_name": "张三",
      "phone": "138****8000"
    },
    "farm": {
      "id": 1,
      "name": "张三养猪场",
      "address": "北京市朝阳区某某村123号"
    },
    "shipping_address": {
      "name": "李四",
      "phone": "13900139000",
      "province": "上海市",
      "city": "上海市",
      "district": "浦东新区",
      "address": "张江镇某某路123号",
      "full_address": "上海市上海市浦东新区张江镇某某路123号"
    },
    "shipping_method": "express",
    "tracking_number": "SF1234567890",
    "items": [
      {
        "id": 1,
        "item_type": "animal",
        "item_id": 1,
        "item_name": "杜洛克猪",
        "item_code": "PIG001",
        "item_spec": "体重85kg，6月龄",
        "unit_price": 1200.00,
        "quantity": 2,
        "unit": "头",
        "subtotal": 2400.00,
        "notes": "健康状况良好"
      }
    ],
    "notes": "请尽快发货",
    "paid_at": "2024-01-20 10:30:00",
    "shipped_at": null,
    "delivered_at": null,
    "completed_at": null,
    "cancelled_at": null,
    "cancel_reason": null,
    "created_at": "2024-01-20 10:00:00",
    "updated_at": "2024-01-20 10:30:00"
  }
}
```

### 7.3 订单操作

#### 7.3.1 订单审核
**接口地址**: `POST /orders/{id}/audit`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 订单ID |

**请求参数**:
```json
{
  "action": "approve",
  "notes": "订单审核通过"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "审核成功",
  "data": {
    "id": 1,
    "order_status": "confirmed",
    "audit_notes": "订单审核通过",
    "audited_at": "2024-01-20 15:00:00"
  }
}
```

#### 7.3.2 订单退款
**接口地址**: `POST /orders/{id}/refund`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 订单ID |

**请求参数**:
```json
{
  "refund_amount": 2500.00,
  "refund_reason": "买家申请退款",
  "notes": "同意退款申请"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "退款成功",
  "data": {
    "id": 1,
    "payment_status": "refunded",
    "order_status": "cancelled",
    "refund_amount": 2500.00,
    "refund_reason": "买家申请退款",
    "refunded_at": "2024-01-20 15:30:00"
  }
}
```

## 8. 财务管理

### 8.1 财务记录

#### 8.1.1 获取财务记录列表
**接口地址**: `GET /financial-records`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |
| record_type | string | 否 | 记录类型：income,expense |
| category | string | 否 | 分类 |
| user_id | int | 否 | 用户ID |
| farm_id | int | 否 | 养殖场ID |
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |
| min_amount | decimal | 否 | 最小金额 |
| max_amount | decimal | 否 | 最大金额 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "record_type": "income",
        "category": "sale",
        "amount": 2400.00,
        "description": "销售杜洛克猪2头",
        "related_id": 1,
        "related_type": "order",
        "payment_method": "alipay",
        "receipt_image": "https://example.com/receipt1.jpg",
        "record_date": "2024-01-20",
        "user": {
          "id": 1,
          "username": "farmer001",
          "real_name": "张三"
        },
        "farm": {
          "id": 1,
          "name": "张三养猪场"
        },
        "notes": "订单收入",
        "created_by": {
          "id": 1,
          "real_name": "张三"
        },
        "created_at": "2024-01-20 16:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 200,
      "total_pages": 10
    },
    "summary": {
      "total_income": 50000.00,
      "total_expense": 30000.00,
      "net_profit": 20000.00
    }
  }
}
```

### 8.2 财务统计

#### 8.2.1 获取财务统计
**接口地址**: `GET /financial-records/statistics`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |
| user_id | int | 否 | 用户ID |
| farm_id | int | 否 | 养殖场ID |
| group_by | string | 否 | 分组方式：day,month,year |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "summary": {
      "total_income": 100000.00,
      "total_expense": 60000.00,
      "net_profit": 40000.00,
      "profit_margin": 40.0
    },
    "income_by_category": [
      {
        "category": "sale",
        "amount": 80000.00,
        "percentage": 80.0
      },
      {
        "category": "other",
        "amount": 20000.00,
        "percentage": 20.0
      }
    ],
    "expense_by_category": [
      {
        "category": "feed",
        "amount": 30000.00,
        "percentage": 50.0
      },
      {
        "category": "medicine",
        "amount": 15000.00,
        "percentage": 25.0
      },
      {
        "category": "labor",
        "amount": 15000.00,
        "percentage": 25.0
      }
    ],
    "trend_data": [
      {
        "date": "2024-01",
        "income": 25000.00,
        "expense": 15000.00,
        "profit": 10000.00
      },
      {
        "date": "2024-02",
        "income": 30000.00,
        "expense": 18000.00,
        "profit": 12000.00
      }
    ]
  }
}
```

## 9. 系统管理

### 9.1 系统配置

#### 9.1.1 获取系统配置
**接口地址**: `GET /system/configs`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| config_key | string | 否 | 配置键 |
| is_public | int | 否 | 是否公开 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "config_key": "site_name",
      "config_value": "畜牧养殖管理平台",
      "config_type": "string",
      "description": "网站名称",
      "is_public": 1,
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-15 10:00:00"
    }
  ]
}
```

#### 9.1.2 更新系统配置
**接口地址**: `PUT /system/configs/{id}`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 配置ID |

**请求参数**:
```json
{
  "config_value": "新的网站名称",
  "description": "更新后的网站名称"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "config_key": "site_name",
    "config_value": "新的网站名称",
    "description": "更新后的网站名称",
    "updated_at": "2024-01-20 16:30:00"
  }
}
```

### 9.2 操作日志

#### 9.2.1 获取操作日志
**接口地址**: `GET /system/operation-logs`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |
| user_id | int | 否 | 用户ID |
| module | string | 否 | 模块 |
| action | string | 否 | 操作 |
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |
| ip | string | 否 | IP地址 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "user": {
          "id": 1,
          "username": "admin",
          "real_name": "系统管理员"
        },
        "module": "user",
        "action": "create",
        "method": "POST",
        "url": "/admin/v1/users",
        "ip": "192.168.1.100",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
        "request_data": {
          "username": "farmer002",
          "real_name": "李四"
        },
        "response_data": {
          "success": true,
          "data": {
            "id": 2
          }
        },
        "status_code": 201,
        "execution_time": 150,
        "created_at": "2024-01-20 11:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 1000,
      "total_pages": 50
    }
  }
}
```

## 10. 数据统计

### 10.1 仪表板统计

#### 10.1.1 获取仪表板数据
**接口地址**: `GET /dashboard/statistics`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "overview": {
      "total_users": 1000,
      "total_farms": 200,
      "total_animals": 50000,
      "total_orders": 5000,
      "total_revenue": 5000000.00
    },
    "growth_stats": {
      "user_growth": {
        "current": 1000,
        "previous": 950,
        "growth_rate": 5.26
      },
      "farm_growth": {
        "current": 200,
        "previous": 180,
        "growth_rate": 11.11
      },
      "animal_growth": {
        "current": 50000,
        "previous": 48000,
        "growth_rate": 4.17
      },
      "order_growth": {
        "current": 5000,
        "previous": 4500,
        "growth_rate": 11.11
      }
    },
    "recent_activities": [
      {
        "type": "user_register",
        "message": "新用户 farmer003 注册成功",
        "time": "2024-01-20 16:30:00"
      },
      {
        "type": "order_created",
        "message": "订单 ORD202401200002 创建成功",
        "time": "2024-01-20 16:25:00"
      }
    ],
    "chart_data": {
      "user_trend": [
        {
          "date": "2024-01-01",
          "count": 900
        },
        {
          "date": "2024-01-20",
          "count": 1000
        }
      ],
      "order_trend": [
        {
          "date": "2024-01-01",
          "count": 4000,
          "amount": 4000000.00
        },
        {
          "date": "2024-01-20",
          "count": 5000,
          "amount": 5000000.00
        }
      ]
    }
  }
}
```

### 10.2 业务统计

#### 10.2.1 获取用户统计
**接口地址**: `GET /statistics/users`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |
| group_by | string | 否 | 分组方式：day,month,year |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "summary": {
      "total_users": 1000,
      "active_users": 800,
      "new_users": 50,
      "retention_rate": 80.0
    },
    "user_by_role": [
      {
        "role": "farmer",
        "count": 900,
        "percentage": 90.0
      },
      {
        "role": "buyer",
        "count": 100,
        "percentage": 10.0
      }
    ],
    "user_by_region": [
      {
        "province": "北京市",
        "count": 200,
        "percentage": 20.0
      },
      {
        "province": "上海市",
        "count": 150,
        "percentage": 15.0
      }
    ],
    "trend_data": [
      {
        "date": "2024-01-01",
        "total": 950,
        "new": 20,
        "active": 760
      },
      {
        "date": "2024-01-20",
        "total": 1000,
        "new": 50,
        "active": 800
      }
    ]
  }
}
```

## 11. 文件上传

### 11.1 文件上传

#### 11.1.1 上传单个文件
**接口地址**: `POST /upload/file`

**请求参数**:
- Content-Type: `multipart/form-data`
- file: 文件对象
- type: 文件类型 (avatar, license, receipt, health_record)
- category: 文件分类 (可选)

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "上传成功",
  "data": {
    "file_id": "file_123456",
    "file_name": "avatar.jpg",
    "file_size": 102400,
    "file_type": "image/jpeg",
    "file_url": "https://cdn.xlxumu.com/uploads/2024/01/20/avatar_123456.jpg",
    "thumbnail_url": "https://cdn.xlxumu.com/uploads/2024/01/20/thumb_avatar_123456.jpg",
    "uploaded_at": "2024-01-20 17:00:00"
  }
}
```

#### 11.1.2 批量上传文件
**接口地址**: `POST /upload/files`

**请求参数**:
- Content-Type: `multipart/form-data`
- files[]: 文件对象数组
- type: 文件类型
- category: 文件分类 (可选)

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "上传成功",
  "data": {
    "uploaded_files": [
      {
        "file_id": "file_123456",
        "file_name": "image1.jpg",
        "file_url": "https://cdn.xlxumu.com/uploads/2024/01/20/image1_123456.jpg"
      },
      {
        "file_id": "file_123457",
        "file_name": "image2.jpg",
        "file_url": "https://cdn.xlxumu.com/uploads/2024/01/20/image2_123457.jpg"
      }
    ],
    "failed_files": [],
    "total_count": 2,
    "success_count": 2,
    "failed_count": 0
  }
}
```

## 12. 导出功能

### 12.1 数据导出

#### 12.1.1 导出用户数据
**接口地址**: `POST /export/users`

**请求参数**:
```json
{
  "format": "excel",
  "filters": {
    "status": 1,
    "role_id": 2,
    "created_start": "2024-01-01",
    "created_end": "2024-01-20"
  },
  "fields": ["username", "real_name", "phone", "email", "created_at"]
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "导出任务创建成功",
  "data": {
    "task_id": "export_task_123456",
    "status": "processing",
    "estimated_time": 30
  }
}
```

#### 12.1.2 获取导出任务状态
**接口地址**: `GET /export/tasks/{task_id}`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| task_id | string | 是 | 任务ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "task_id": "export_task_123456",
    "status": "completed",
    "progress": 100,
    "file_url": "https://cdn.xlxumu.com/exports/users_20240120.xlsx",
    "file_size": 204800,
    "record_count": 1000,
    "created_at": "2024-01-20 17:30:00",
    "completed_at": "2024-01-20 17:31:00"
  }
}
```

## 13. 通知管理

### 13.1 系统通知

#### 13.1.1 获取通知列表
**接口地址**: `GET /notifications`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |
| type | string | 否 | 通知类型 |
| status | string | 否 | 通知状态 |
| is_read | int | 否 | 是否已读 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "type": "system",
        "title": "系统维护通知",
        "content": "系统将于今晚22:00-24:00进行维护",
        "is_read": 0,
        "created_at": "2024-01-20 18:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 50,
      "total_pages": 3
    },
    "unread_count": 5
  }
}
```

#### 13.1.2 标记通知已读
**接口地址**: `POST /notifications/{id}/read`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 通知ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "标记成功"
}
```

## 14. 错误处理

### 14.1 错误码定义

| 错误码 | HTTP状态码 | 错误信息 | 说明 |
|--------|------------|----------|------|
| 10001 | 400 | 参数错误 | 请求参数格式错误或缺失 |
| 10002 | 401 | 未授权 | Token无效或已过期 |
| 10003 | 403 | 禁止访问 | 权限不足 |
| 10004 | 404 | 资源不存在 | 请求的资源不存在 |
| 10005 | 409 | 资源冲突 | 资源已存在或状态冲突 |
| 10006 | 422 | 参数验证失败 | 参数格式正确但验证失败 |
| 10007 | 429 | 请求过于频繁 | 触发限流 |
| 10008 | 500 | 服务器内部错误 | 系统异常 |
| 20001 | 400 | 用户名已存在 | 用户注册时用户名重复 |
| 20002 | 400 | 手机号已存在 | 用户注册时手机号重复 |
| 20003 | 400 | 邮箱已存在 | 用户注册时邮箱重复 |
| 20004 | 400 | 用户名或密码错误 | 登录验证失败 |
| 20005 | 400 | 验证码错误 | 验证码验证失败 |
| 30001 | 400 | 养殖场名称已存在 | 养殖场创建时名称重复 |
| 30002 | 400 | 养殖场编码已存在 | 养殖场创建时编码重复 |
| 40001 | 400 | 动物编码已存在 | 动物创建时编码重复 |
| 50001 | 400 | 订单状态不允许此操作 | 订单状态错误 |
| 50002 | 400 | 库存不足 | 商品库存不足 |

### 14.2 错误响应示例

#### 14.2.1 参数验证错误
```json
{
  "success": false,
  "code": 10006,
  "message": "参数验证失败",
  "errors": [
    {
      "field": "username",
      "message": "用户名长度必须在3-20个字符之间"
    },
    {
      "field": "phone",
      "message": "手机号格式不正确"
    }
  ],
  "timestamp": 1705747200000,
  "request_id": "req_123456789"
}
```

#### 14.2.2 权限不足错误
```json
{
  "success": false,
  "code": 10003,
  "message": "权限不足，无法访问此资源",
  "timestamp": 1705747200000,
  "request_id": "req_123456789"
}
```

## 15. 接口版本管理

### 15.1 版本策略
- **URL版本控制**: 通过URL路径进行版本管理，如 `/admin/v1/users`
- **向后兼容**: 新版本保持向后兼容，旧版本逐步废弃
- **版本生命周期**: 每个版本至少维护12个月
- **废弃通知**: 版本废弃前3个月发出通知

### 15.2 版本信息
| 版本 | 发布日期 | 状态 | 废弃日期 | 说明 |
|------|----------|------|----------|------|
| v1.0 | 2024-01-01 | 当前版本 | - | 初始版本 |

## 16. 接口测试

### 16.1 测试环境
- **测试地址**: `https://test-api.xlxumu.com/admin/v1`
- **测试账号**: admin / test123456
- **测试数据**: 系统提供测试数据，每日凌晨重置

### 16.2 Postman集合
提供完整的Postman接口测试集合，包含：
- 环境变量配置
- 认证Token自动获取
- 完整的接口测试用例
- 测试数据和断言

### 16.3 接口文档
- **在线文档**: https://docs.xlxumu.com/admin-api
- **Swagger文档**: https://api.xlxumu.com/admin/docs
- **更新频率**: 随版本发布实时更新

## 17. 总结

本文档详细定义了畜牧养殖管理平台管理后台的所有API接口，包括：

### 17.1 核心特性
- **完整的RBAC权限体系**: 支持用户、角色、权限的灵活管理
- **全面的业务功能**: 覆盖用户、养殖场、动物、订单、财务等核心业务
- **统一的接口规范**: 标准化的请求响应格式和错误处理
- **完善的数据统计**: 多维度的数据分析和可视化支持
- **安全的认证机制**: 基于JWT的身份认证和权限控制

### 17.2 技术亮点
- **RESTful设计**: 遵循REST架构原则，接口语义清晰
- **分页查询**: 统一的分页参数和响应格式
- **条件筛选**: 灵活的查询条件和排序支持
- **批量操作**: 支持批量创建、更新、删除操作
- **文件上传**: 完善的文件上传和管理功能
- **数据导出**: 支持多格式数据导出功能

### 17.3 扩展性设计
- **模块化架构**: 按业务模块组织接口，便于维护和扩展
- **版本控制**: 完善的API版本管理策略
- **错误处理**: 统一的错误码和错误信息定义
- **监控日志**: 完整的操作日志和接口监控

### 17.4 后续优化
- **性能优化**: 接口响应时间优化，缓存策略完善
- **安全加固**: 接口安全防护，数据加密传输
- **功能扩展**: 根据业务需求持续迭代新功能
- **文档维护**: 保持文档与代码同步更新