aiotagro/xlxumu

Fork 0

Files

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

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

9.2 KiB

Raw Permalink 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 Permalink Blame History Unescape Escape

xlxumu 畜牧管理系统 API 文档

概述

基础信息

通用响应格式

成功响应

错误响应

认证接口 (/auth)

用户注册

用户登录

刷新Token

用户登出

用户管理接口 (/users)

获取用户信息

更新用户信息

修改密码

牛只管理接口 (/cattle)

获取牛只列表

添加牛只

获取牛只详情

更新牛只信息

删除牛只

牛只统计

财务管理接口 (/finance)

获取财务记录

添加财务记录

财务统计

交易管理接口 (/trading)

获取交易列表

创建交易

获取交易详情

更新交易状态

商城管理接口 (/mall)

获取产品列表

获取产品详情

添加产品

获取订单列表

创建订单

政府监管接口 (/government)

获取农场监管列表

获取监管统计

系统接口

健康检查

数据库状态

数据库表信息

错误码说明

认证说明

分页说明

开发环境

注意事项

9.2 KiB

Raw Permalink Blame History