aiotagro/xlxumu

Fork 0

Files

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

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

9.2 KiB

Raw Blame History

xlxumu 畜牧管理系统 API 文档

概述

本文档描述了 xlxumu 畜牧管理系统的 RESTful API 接口。系统提供用户认证、牛只管理、财务管理、交易管理、商城管理和政府监管等功能。

基础信息

基础URL: http://localhost:8889/api/v1
认证方式: JWT Token
数据格式: JSON
字符编码: UTF-8

通用响应格式

成功响应

{
  "success": true,
  "data": {
    // 具体数据内容
  },
  "message": "操作成功"
}

错误响应

{
  "success": false,
  "message": "错误描述",
  "code": "ERROR_CODE"
}

认证接口 (/auth)

用户注册

URL: POST /auth/register
描述: 用户注册
请求体:

{
  "username": "string",
  "email": "string",
  "phone": "string",
  "password": "string",
  "real_name": "string",
  "user_type": "farmer|government|bank|insurance"
}

响应:

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "email": "test@example.com",
      "user_type": "farmer"
    },
    "token": "jwt_token_string"
  }
}

用户登录

URL: POST /auth/login
描述: 用户登录
请求体:

{
  "username": "string",
  "password": "string"
}

刷新Token

URL: POST /auth/refresh
描述: 刷新访问令牌
请求头: Authorization: Bearer <token>

用户登出

URL: POST /auth/logout
描述: 用户登出
请求头: Authorization: Bearer <token>

用户管理接口 (/users)

获取用户信息

URL: GET /users/profile
描述: 获取当前用户信息
请求头: Authorization: Bearer <token>

更新用户信息

URL: PUT /users/profile
描述: 更新用户信息
请求头: Authorization: Bearer <token>
请求体:

{
  "real_name": "string",
  "phone": "string",
  "avatar_url": "string"
}

修改密码

URL: PUT /users/password
描述: 修改用户密码
请求头: Authorization: Bearer <token>
请求体:

{
  "old_password": "string",
  "new_password": "string"
}

牛只管理接口 (/cattle)

获取牛只列表

URL: GET /cattle
描述: 获取牛只列表
请求头: Authorization: Bearer <token>
查询参数:
- page: 页码 (默认: 1)
- limit: 每页数量 (默认: 10)
- breed: 品种筛选
- status: 状态筛选
- health_status: 健康状态筛选

添加牛只

URL: POST /cattle
描述: 添加新牛只
请求头: Authorization: Bearer <token>
请求体:

{
  "ear_tag": "string",
  "name": "string",
  "breed": "string",
  "gender": "male|female",
  "birth_date": "YYYY-MM-DD",
  "color": "string",
  "weight": 500.5,
  "farm_location": "string",
  "notes": "string"
}

获取牛只详情

URL: GET /cattle/:id
描述: 获取指定牛只详情
请求头: Authorization: Bearer <token>

更新牛只信息

URL: PUT /cattle/:id
描述: 更新牛只信息
请求头: Authorization: Bearer <token>

删除牛只

URL: DELETE /cattle/:id
描述: 删除牛只记录
请求头: Authorization: Bearer <token>

牛只统计

URL: GET /cattle/statistics
描述: 获取牛只统计信息
请求头: Authorization: Bearer <token>

财务管理接口 (/finance)

获取财务记录

URL: GET /finance/records
描述: 获取财务记录列表
请求头: Authorization: Bearer <token>
查询参数:
- page: 页码
- limit: 每页数量
- type: 类型 (income|expense)
- category: 分类
- start_date: 开始日期
- end_date: 结束日期

添加财务记录

URL: POST /finance/records
描述: 添加财务记录
请求头: Authorization: Bearer <token>
请求体:

{
  "type": "income|expense",
  "category": "string",
  "amount": 1000.00,
  "description": "string",
  "record_date": "YYYY-MM-DD"
}

财务统计

URL: GET /finance/statistics
描述: 获取财务统计信息
请求头: Authorization: Bearer <token>
查询参数:
- period: 统计周期 (month|quarter|year)

交易管理接口 (/trading)

获取交易列表

URL: GET /trading/transactions
描述: 获取交易记录列表
请求头: Authorization: Bearer <token>
查询参数:
- page: 页码
- limit: 每页数量
- status: 交易状态
- product_type: 产品类型

创建交易

URL: POST /trading/transactions
描述: 创建新交易
请求头: Authorization: Bearer <token>
请求体:

{
  "seller_id": 1,
  "product_type": "cattle",
  "product_id": 1,
  "quantity": 10,
  "unit_price": 8500.00,
  "notes": "string"
}

获取交易详情

URL: GET /trading/transactions/:id
描述: 获取交易详情
请求头: Authorization: Bearer <token>

更新交易状态

URL: PUT /trading/transactions/:id/status
描述: 更新交易状态
请求头: Authorization: Bearer <token>
请求体:

{
  "status": "pending|confirmed|completed|cancelled",
  "payment_status": "pending|paid|refunded",
  "delivery_status": "pending|shipped|delivered"
}

商城管理接口 (/mall)

获取产品列表

URL: GET /mall/products
描述: 获取商城产品列表
查询参数:
- page: 页码
- limit: 每页数量
- category_id: 分类ID
- keyword: 搜索关键词
- min_price: 最低价格
- max_price: 最高价格

获取产品详情

URL: GET /mall/products/:id
描述: 获取产品详情

添加产品

URL: POST /mall/products
描述: 添加新产品
请求头: Authorization: Bearer <token>
请求体:

{
  "name": "string",
  "description": "string",
  "category_id": 1,
  "price": 100.00,
  "stock_quantity": 50,
  "images": ["url1", "url2"],
  "specifications": {}
}

获取订单列表

URL: GET /mall/orders
描述: 获取订单列表
请求头: Authorization: Bearer <token>

创建订单

URL: POST /mall/orders
描述: 创建新订单
请求头: Authorization: Bearer <token>
请求体:

{
  "items": [
    {
      "product_id": 1,
      "quantity": 2,
      "price": 100.00
    }
  ],
  "shipping_address": "string",
  "notes": "string"
}

政府监管接口 (/government)

获取农场监管列表

URL: GET /government/farms/supervision
描述: 获取农场监管信息
请求头: Authorization: Bearer <token>
查询参数:
- page: 页码
- limit: 每页数量
- region: 地区
- status: 监管状态

获取监管统计

URL: GET /government/statistics
描述: 获取监管统计数据
请求头: Authorization: Bearer <token>
响应示例:

{
  "success": true,
  "data": {
    "overview": {
      "total_farms": 1250,
      "total_cattle": 45680,
      "active_farms": 1180,
      "compliance_rate": 94.4
    },
    "by_region": [
      {
        "region": "华北地区",
        "farms": 320,
        "cattle": 12500,
        "compliance_rate": 96.2
      }
    ],
    "by_type": [
      {
        "type": "肉牛养殖",
        "count": 680,
        "percentage": 54.4
      }
    ],
    "monthly_trend": [
      {
        "month": "2024-01",
        "new_registrations": 25,
        "inspections": 156,
        "violations": 8
      }
    ]
  }
}

系统接口

健康检查

URL: GET /health
描述: 系统健康检查
响应:

{
  "status": "ok",
  "timestamp": "2024-01-20T10:30:00Z",
  "database": "connected",
  "version": "1.0.0"
}

数据库状态

URL: GET /database/status
描述: 数据库连接状态

数据库表信息

URL: GET /database/tables
描述: 获取数据库表信息

错误码说明

错误码	描述
VALIDATION_ERROR	请求参数验证失败
UNAUTHORIZED	未授权访问
FORBIDDEN	禁止访问
NOT_FOUND	资源未找到
DATABASE_ERROR	数据库操作失败
INTERNAL_SERVER_ERROR	服务器内部错误

认证说明

大部分API接口需要在请求头中包含JWT Token：

Authorization: Bearer <your_jwt_token>

Token可通过登录接口获取，有效期为24小时。

分页说明

支持分页的接口使用以下参数：

page: 页码，从1开始
limit: 每页数量，默认10，最大100

分页响应格式：

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 10,
      "pages": 10
    }
  }
}

开发环境

服务器地址: http://localhost:8889
数据库: SQLite (开发环境)
日志级别: DEBUG

注意事项

所有时间格式使用 ISO 8601 标准
金额字段使用 DECIMAL 类型，保留2位小数
文件上传大小限制为 10MB
API请求频率限制：每15分钟100次请求
开发环境下会返回详细的错误信息，生产环境下会隐藏敏感信息

9.2 KiB Raw Blame History Unescape Escape

xlxumu 畜牧管理系统 API 文档

概述

基础信息

通用响应格式

成功响应

错误响应

认证接口 (/auth)

用户注册

用户登录

刷新Token

用户登出

用户管理接口 (/users)

获取用户信息

更新用户信息

修改密码

牛只管理接口 (/cattle)

获取牛只列表

添加牛只

获取牛只详情

更新牛只信息

删除牛只

牛只统计

财务管理接口 (/finance)

获取财务记录

添加财务记录

财务统计

交易管理接口 (/trading)

获取交易列表

创建交易

获取交易详情

更新交易状态

商城管理接口 (/mall)

获取产品列表

获取产品详情

添加产品

获取订单列表

创建订单

政府监管接口 (/government)

获取农场监管列表

获取监管统计

系统接口

健康检查

数据库状态

数据库表信息

错误码说明

认证说明

分页说明

开发环境

注意事项

9.2 KiB

Raw Blame History