Files

aiotagro 3c8648a635 refactor: 重构数据库配置为SQLite开发环境并移除冗余文档

2025-09-21 15:16:48 +08:00

44 KiB

Raw Permalink Blame History

管理后台接口设计文档

版本历史

版本	日期	作者	变更说明
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 通用响应格式

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": 1705747200000,
  "request_id": "req_123456789"
}

1.4 错误响应格式

{
  "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

请求参数:

{
  "username": "admin",
  "password": "password123",
  "captcha": "ABCD",
  "captcha_key": "captcha_key_123"
}

响应数据:

{
  "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

请求参数:

{
  "refresh_token": "refresh_token_123"
}

响应数据:

{
  "success": true,
  "code": 200,
  "message": "刷新成功",
  "data": {
    "token": "new_jwt_token",
    "expires_in": 7200
  }
}

2.1.3 退出登录

接口地址: POST /auth/logout

请求头:

Authorization: Bearer {token}

响应数据:

{
  "success": true,
  "code": 200,
  "message": "退出成功"
}

2.2 权限验证

2.2.1 获取用户信息

接口地址: GET /auth/user

请求头:

Authorization: Bearer {token}

响应数据:

{
  "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}

响应数据:

{
  "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	否	创建结束时间

响应数据:

{
  "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

响应数据:

{
  "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

请求参数:

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

响应数据:

{
  "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

请求参数:

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

响应数据:

{
  "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

响应数据:

{
  "success": true,
  "code": 200,
  "message": "删除成功"
}

3.3.4 批量删除用户

接口地址: DELETE /users

请求参数:

{
  "ids": [1, 2, 3]
}

响应数据:

{
  "success": true,
  "code": 200,
  "message": "批量删除成功",
  "data": {
    "deleted_count": 3
  }
}

3.3.5 重置用户密码

接口地址: POST /users/{id}/reset-password

路径参数:

参数	类型	必填	说明
id	int	是	用户ID

请求参数:

{
  "new_password": "newpassword123"
}

响应数据:

{
  "success": true,
  "code": 200,
  "message": "密码重置成功"
}

3.3.6 启用/禁用用户

接口地址: POST /users/{id}/toggle-status

路径参数:

参数	类型	必填	说明
id	int	是	用户ID

请求参数:

{
  "status": 0
}

响应数据:

{
  "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	否	角色状态

响应数据:

{
  "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

响应数据:

{
  "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

请求参数:

{
  "name": "运营管理员",
  "code": "operator",
  "description": "负责平台运营管理",
  "permission_ids": [10, 11, 12, 13]
}

响应数据:

{
  "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

请求参数:

{
  "name": "高级运营管理员",
  "description": "负责平台高级运营管理",
  "permission_ids": [10, 11, 12, 13, 14, 15]
}

响应数据:

{
  "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

响应数据:

{
  "success": true,
  "code": 200,
  "message": "删除成功"
}

4.2 权限管理

4.2.1 获取权限树

接口地址: GET /permissions/tree

响应数据:

{
  "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	否	权限状态

响应数据:

{
  "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

请求参数:

{
  "name": "财务管理",
  "code": "finance",
  "type": "menu",
  "parent_id": null,
  "path": "/finance",
  "icon": "finance",
  "sort_order": 3
}

响应数据:

{
  "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

响应数据:

{
  "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

响应数据:

{
  "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

请求参数:

{
  "status": 1,
  "audit_notes": "审核通过，符合养殖标准"
}

响应数据:

{
  "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	否	结束日期

响应数据:

{
  "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	否	动物状态

响应数据:

{
  "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

响应数据:

{
  "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	否	结束日期

响应数据:

{
  "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	否	结束日期

响应数据:

{
  "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

响应数据:

{
  "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

请求参数:

{
  "action": "approve",
  "notes": "订单审核通过"
}

响应数据:

{
  "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

请求参数:

{
  "refund_amount": 2500.00,
  "refund_reason": "买家申请退款",
  "notes": "同意退款申请"
}

响应数据:

{
  "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	否	最大金额

响应数据:

{
  "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

响应数据:

{
  "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	否	是否公开

响应数据:

{
  "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

请求参数:

{
  "config_value": "新的网站名称",
  "description": "更新后的网站名称"
}

响应数据:

{
  "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地址

响应数据:

{
  "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	否	结束日期

响应数据:

{
  "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

响应数据:

{
  "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: 文件分类 (可选)

响应数据:

{
  "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: 文件分类 (可选)

响应数据:

{
  "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

请求参数:

{
  "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"]
}

响应数据:

{
  "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

响应数据:

{
  "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	否	是否已读

响应数据:

{
  "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

响应数据:

{
  "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 参数验证错误

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

14.2.2 权限不足错误

{
  "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 后续优化

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

44 KiB Raw Permalink Blame History Unescape Escape

管理后台接口设计文档

版本历史

1. 接口概述

1.1 设计原则

1.2 基础信息

1.3 通用响应格式

1.4 错误响应格式

1.5 状态码说明

2. 认证授权

2.1 登录认证

2.1.1 管理员登录

2.1.2 刷新Token

2.1.3 退出登录

2.2 权限验证

2.2.1 获取用户信息

2.2.2 获取用户菜单

3. 用户管理

3.1 用户列表

3.1.1 获取用户列表

3.2 用户详情

3.2.1 获取用户详情

3.3 用户操作

3.3.1 创建用户

3.3.2 更新用户

3.3.3 删除用户

3.3.4 批量删除用户

3.3.5 重置用户密码

3.3.6 启用/禁用用户

4. 角色权限管理

4.1 角色管理

4.1.1 获取角色列表

4.1.2 获取角色详情

4.1.3 创建角色

4.1.4 更新角色

4.1.5 删除角色

4.2 权限管理

4.2.1 获取权限树

4.2.2 获取权限列表

4.2.3 创建权限

5. 养殖场管理

5.1 养殖场列表

5.1.1 获取养殖场列表

5.2 养殖场详情

5.2.1 获取养殖场详情

5.3 养殖场操作

5.3.1 审核养殖场

5.3.2 获取养殖场统计

6. 动物管理

6.1 动物列表

6.1.1 获取动物列表

6.2 动物详情

6.2.1 获取动物详情

6.3 健康记录

6.3.1 获取动物健康记录

7. 订单管理

7.1 订单列表

7.1.1 获取订单列表

7.2 订单详情

7.2.1 获取订单详情

7.3 订单操作

7.3.1 订单审核

7.3.2 订单退款

8. 财务管理

8.1 财务记录

8.1.1 获取财务记录列表

8.2 财务统计

8.2.1 获取财务统计

9. 系统管理

9.1 系统配置

9.1.1 获取系统配置

9.1.2 更新系统配置

9.2 操作日志

9.2.1 获取操作日志

10. 数据统计

10.1 仪表板统计

10.1.1 获取仪表板数据

10.2 业务统计

10.2.1 获取用户统计

11. 文件上传

44 KiB

Raw Permalink Blame History