aiotagro/nxxmdata
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e64866f2cc810b429657f6e6a09def2ad16c1385
nxxmdata/docs/API.md
ylweng 6b4e0c227f 修改文件结构，统一文档格式
2025-09-02 23:22:10 +08:00

15 KiB
Raw Blame History

API 文档

概述

宁夏智慧养殖监管平台提供全面的RESTful API，支持农场管理、设备监控、动物健康管理、用户管理、订单管理等核心功能。

基础信息

  • Base URL: http://localhost:5350/api (开发环境)
  • Authentication: JWT Bearer Token
  • Content-Type: application/json
  • API Version: v1.0

认证机制

JWT Token认证

所有需要认证的API都需要在请求头中包含JWT Token：

Authorization: Bearer <your_jwt_token>

Token获取

通过登录接口获取Token：

POST /api/auth/login
Content-Type: application/json

{
  "username": "your_username",
  "password": "your_password"
}

通用响应格式

成功响应

{
  "success": true,
  "data": {},
  "message": "操作成功",
  "timestamp": "2025-01-18T10:30:00Z"
}

错误响应

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述",
    "details": "详细错误信息"
  },
  "timestamp": "2025-01-18T10:30:00Z"
}

HTTP状态码

  • 200 - 请求成功
  • 201 - 创建成功
  • 400 - 请求参数错误
  • 401 - 未认证或Token过期
  • 403 - 权限不足
  • 404 - 资源不存在
  • 409 - 资源冲突
  • 500 - 服务器内部错误

认证相关API

用户登录

POST /api/auth/login

请求体:

{
  "username": "admin",
  "password": "password123"
}

响应:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "roles": ["admin"]
    }
  }
}

用户注册

POST /api/auth/register

请求体:

{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "password123",
  "phone": "13800138000"
}

用户登出

POST /api/auth/logout

需要认证: 是

验证Token

GET /api/auth/verify

需要认证: 是

用户管理API

获取用户列表

GET /api/users

需要认证: 是 权限要求: admin

查询参数:

  • page (int): 页码，默认1
  • limit (int): 每页数量，默认10
  • search (string): 搜索关键词
  • status (string): 用户状态 (active, inactive, banned)

响应:

{
  "success": true,
  "data": {
    "users": [
      {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com",
        "phone": "13800138000",
        "status": "active",
        "created_at": "2025-01-01T00:00:00Z",
        "roles": ["admin"]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "pages": 1
    }
  }
}

获取用户详情

GET /api/users/{id}

需要认证: 是

创建用户

POST /api/users

需要认证: 是 权限要求: admin

请求体:

{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "password123",
  "phone": "13800138000",
  "status": "active",
  "roles": ["user"]
}

更新用户

PUT /api/users/{id}

需要认证: 是

删除用户

DELETE /api/users/{id}

需要认证: 是 权限要求: admin

养殖场管理API

获取养殖场列表

GET /api/farms

需要认证: 是

查询参数:

  • page (int): 页码，默认1
  • limit (int): 每页数量，默认10
  • type (string): 养殖场类型
  • status (string): 状态 (active, inactive, maintenance)

响应:

{
  "success": true,
  "data": {
    "farms": [
      {
        "id": 1,
        "name": "宁夏示范养殖场",
        "type": "奶牛养殖",
        "location": {
          "lat": 38.46667,
          "lng": 106.26667
        },
        "address": "宁夏回族自治区银川市金凤区",
        "contact": "张经理",
        "phone": "13800138000",
        "status": "active",
        "created_at": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "pages": 1
    }
  }
}

获取公开养殖场数据

GET /api/farms/public

需要认证: 否

获取养殖场详情

GET /api/farms/{id}

需要认证: 是

创建养殖场

POST /api/farms

需要认证: 是 权限要求: manager

请求体:

{
  "name": "新养殖场",
  "type": "养猪场",
  "longitude": 106.26667,
  "latitude": 38.46667,
  "address": "详细地址",
  "owner": "联系人姓名",
  "phone": "13800138000",
  "status": "active"
}

更新养殖场

PUT /api/farms/{id}

需要认证: 是 权限要求: manager

删除养殖场

DELETE /api/farms/{id}

需要认证: 是 权限要求: admin

设备管理API

获取设备列表

GET /api/devices

需要认证: 是

查询参数:

  • page (int): 页码
  • limit (int): 每页数量
  • farm_id (int): 养殖场ID
  • type (string): 设备类型
  • status (string): 设备状态 (online, offline, maintenance)

获取设备详情

GET /api/devices/{id}

需要认证: 是

响应:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "温度传感器001",
    "type": "温度传感器",
    "status": "online",
    "farm_id": 1,
    "metrics": {
      "temperature": 25.5,
      "humidity": 60
    },
    "last_maintenance": "2025-01-01T00:00:00Z",
    "installation_date": "2024-01-01T00:00:00Z",
    "farm": {
      "id": 1,
      "name": "宁夏示范养殖场"
    }
  }
}

创建设备

POST /api/devices

需要认证: 是 权限要求: manager

请求体:

{
  "name": "新设备",
  "type": "传感器",
  "farm_id": 1,
  "installation_date": "2025-01-18",
  "metrics": {
    "temperature": 25.0
  }
}

更新设备

PUT /api/devices/{id}

需要认证: 是 权限要求: manager

删除设备

DELETE /api/devices/{id}

需要认证: 是 权限要求: admin

动物管理API

获取动物列表

GET /api/animals

需要认证: 是

查询参数:

  • page (int): 页码
  • limit (int): 每页数量
  • farm_id (int): 养殖场ID
  • type (string): 动物类型
  • health_status (string): 健康状态 (healthy, sick, quarantine)

获取动物详情

GET /api/animals/{id}

需要认证: 是

创建动物记录

POST /api/animals

需要认证: 是 权限要求: manager

请求体:

{
  "type": "奶牛",
  "count": 100,
  "farm_id": 1,
  "health_status": "healthy",
  "notes": "备注信息"
}

更新动物记录

PUT /api/animals/{id}

需要认证: 是 权限要求: manager

删除动物记录

DELETE /api/animals/{id}

需要认证: 是 权限要求: admin

预警管理API

获取预警列表

GET /api/alerts

需要认证: 是

查询参数:

  • page (int): 页码
  • limit (int): 每页数量
  • farm_id (int): 养殖场ID
  • level (string): 预警级别 (low, medium, high, critical)
  • status (string): 预警状态 (active, acknowledged, resolved)

响应:

{
  "success": true,
  "data": {
    "alerts": [
      {
        "id": 1,
        "type": "temperature_high",
        "level": "high",
        "message": "温度过高警报",
        "status": "active",
        "farm_id": 1,
        "device_id": 1,
        "created_at": "2025-01-18T10:00:00Z",
        "farm": {
          "name": "宁夏示范养殖场"
        },
        "device": {
          "name": "温度传感器001"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "pages": 1
    }
  }
}

确认预警

PUT /api/alerts/{id}/acknowledge

需要认证: 是 权限要求: manager

解决预警

PUT /api/alerts/{id}/resolve

需要认证: 是 权限要求: manager

请求体:

{
  "resolution_notes": "问题已解决，温度已恢复正常"
}

产品管理API

获取产品列表

GET /api/products

需要认证: 是

查询参数:

  • page (int): 页码
  • limit (int): 每页数量
  • search (string): 搜索关键词
  • is_active (boolean): 是否激活

获取产品详情

GET /api/products/{id}

需要认证: 是

创建产品

POST /api/products

需要认证: 是 权限要求: manager

请求体:

{
  "name": "优质鲜牛奶",
  "description": "新鲜优质牛奶，富含营养",
  "price": 5000,
  "stock": 1000,
  "image_url": "/uploads/products/milk.jpg",
  "is_active": true
}

更新产品

PUT /api/products/{id}

需要认证: 是 权限要求: manager

删除产品

DELETE /api/products/{id}

需要认证: 是 权限要求: admin

订单管理API

获取订单列表

GET /api/orders

需要认证: 是

查询参数:

  • page (int): 页码
  • limit (int): 每页数量
  • user_id (int): 用户ID
  • status (string): 订单状态 (pending, processing, shipped, delivered, cancelled)
  • payment_status (string): 支付状态 (unpaid, paid, refunded)

获取订单详情

GET /api/orders/{id}

需要认证: 是

响应:

{
  "success": true,
  "data": {
    "id": 1,
    "user_id": 1,
    "total_amount": 10000,
    "status": "pending",
    "payment_status": "unpaid",
    "shipping_address": "收货地址",
    "created_at": "2025-01-18T10:00:00Z",
    "user": {
      "username": "用户名",
      "email": "user@example.com"
    },
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "quantity": 2,
        "price": 5000,
        "product": {
          "name": "优质鲜牛奶",
          "image_url": "/uploads/products/milk.jpg"
        }
      }
    ]
  }
}

创建订单

POST /api/orders

需要认证: 是

请求体:

{
  "items": [
    {
      "product_id": 1,
      "quantity": 2
    }
  ],
  "shipping_address": "收货地址"
}

更新订单状态

PUT /api/orders/{id}/status

需要认证: 是 权限要求: manager

请求体:

{
  "status": "processing"
}

统计分析API

系统概览统计

GET /api/stats/overview

需要认证: 是

响应:

{
  "success": true,
  "data": {
    "farms": {
      "total": 10,
      "active": 8,
      "inactive": 2
    },
    "devices": {
      "total": 50,
      "online": 45,
      "offline": 3,
      "maintenance": 2
    },
    "animals": {
      "total": 5000,
      "healthy": 4800,
      "sick": 150,
      "quarantine": 50
    },
    "alerts": {
      "active": 5,
      "resolved_today": 12
    }
  }
}

养殖场统计

GET /api/stats/farms/{id}

需要认证: 是

预警统计

GET /api/stats/alerts

需要认证: 是

查询参数:

  • timeRange (string): 时间范围 (today, week, month)

动物健康统计

GET /api/stats/animals

需要认证: 是

查询参数:

  • farm_id (int): 养殖场ID

地图服务API

获取地图数据

GET /api/map/data

需要认证: 是

响应:

{
  "success": true,
  "data": {
    "farms": [
      {
        "id": 1,
        "name": "宁夏示范养殖场",
        "location": {
          "lat": 38.46667,
          "lng": 106.26667
        },
        "type": "奶牛养殖",
        "status": "active",
        "devices_count": 5,
        "animals_count": 500
      }
    ]
  }
}

性能监控API

获取性能指标

GET /api/performance/metrics

需要认证: 是 权限要求: admin

获取系统资源信息

GET /api/performance/system

需要认证: 是 权限要求: admin

获取数据库性能信息

GET /api/performance/database

需要认证: 是 权限要求: admin

获取API性能统计

GET /api/performance/api

需要认证: 是 权限要求: admin

文件上传API

上传头像

POST /api/upload/avatar

需要认证: 是 Content-Type: multipart/form-data

请求:

Content-Type: multipart/form-data

avatar: [文件]

上传产品图片

POST /api/upload/product

需要认证: 是 权限要求: manager Content-Type: multipart/form-data

错误代码参考

错误代码 描述 HTTP状态码
INVALID_CREDENTIALS 用户名或密码错误 401
TOKEN_EXPIRED Token已过期 401
TOKEN_INVALID Token无效 401
INSUFFICIENT_PERMISSIONS 权限不足 403
RESOURCE_NOT_FOUND 资源不存在 404
VALIDATION_ERROR 参数验证失败 400
DUPLICATE_RESOURCE 资源重复 409
DATABASE_ERROR 数据库错误 500
INTERNAL_SERVER_ERROR 服务器内部错误 500

API限制

频率限制

  • 登录接口：每分钟最多5次尝试
  • 普通API：每分钟最多1000次请求
  • 上传接口：每分钟最多10次请求

文件上传限制

  • 头像：最大2MB，支持jpg、png格式
  • 产品图片：最大5MB，支持jpg、png、webp格式

SDK示例

JavaScript/Node.js

// 安装: npm install axios

const axios = require('axios');

class NxxmdataAPI {
  constructor(baseURL, token) {
    this.client = axios.create({
      baseURL: baseURL,
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });
  }

  async getFarms(params = {}) {
    const response = await this.client.get('/farms', { params });
    return response.data;
  }

  async createFarm(farmData) {
    const response = await this.client.post('/farms', farmData);
    return response.data;
  }
}

// 使用示例
const api = new NxxmdataAPI('http://localhost:5350/api', 'your_token');
const farms = await api.getFarms({ page: 1, limit: 10 });

Python

import requests

class NxxmdataAPI:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }

    def get_farms(self, params=None):
        response = requests.get(f'{self.base_url}/farms', 
                              headers=self.headers, params=params)
        return response.json()

    def create_farm(self, farm_data):
        response = requests.post(f'{self.base_url}/farms', 
                               headers=self.headers, json=farm_data)
        return response.json()

# 使用示例
api = NxxmdataAPI('http://localhost:5350/api', 'your_token')
farms = api.get_farms({'page': 1, 'limit': 10})

测试环境

Swagger文档

访问 http://localhost:5350/api-docs 查看交互式API文档。

Postman集合

提供完整的Postman集合文件，包含所有API的示例请求。

更新记录

  • v1.0 (2025-01-18): 初始版本，包含所有核心API
  • 定期更新，请关注CHANGELOG.md

联系方式

如有API相关问题，请联系：

最后更新: 2025年1月