# 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： ```http Authorization: Bearer ``` ### Token获取 通过登录接口获取Token： ```http POST /api/auth/login Content-Type: application/json { "username": "your_username", "password": "your_password" } ``` ## 通用响应格式 ### 成功响应 ```json { "success": true, "data": {}, "message": "操作成功", "timestamp": "2025-01-18T10:30:00Z" } ``` ### 错误响应 ```json { "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 ### 用户登录 ```http POST /api/auth/login ``` **请求体:** ```json { "username": "admin", "password": "password123" } ``` **响应:** ```json { "success": true, "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "user": { "id": 1, "username": "admin", "email": "admin@example.com", "roles": ["admin"] } } } ``` ### 用户注册 ```http POST /api/auth/register ``` **请求体:** ```json { "username": "newuser", "email": "newuser@example.com", "password": "password123", "phone": "13800138000" } ``` ### 用户登出 ```http POST /api/auth/logout ``` **需要认证**: 是 ### 验证Token ```http GET /api/auth/verify ``` **需要认证**: 是 ## 用户管理API ### 获取用户列表 ```http GET /api/users ``` **需要认证**: 是 **权限要求**: admin **查询参数:** - `page` (int): 页码，默认1 - `limit` (int): 每页数量，默认10 - `search` (string): 搜索关键词 - `status` (string): 用户状态 (`active`, `inactive`, `banned`) **响应:** ```json { "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 } } } ``` ### 获取用户详情 ```http GET /api/users/{id} ``` **需要认证**: 是 ### 创建用户 ```http POST /api/users ``` **需要认证**: 是 **权限要求**: admin **请求体:** ```json { "username": "newuser", "email": "newuser@example.com", "password": "password123", "phone": "13800138000", "status": "active", "roles": ["user"] } ``` ### 更新用户 ```http PUT /api/users/{id} ``` **需要认证**: 是 ### 删除用户 ```http DELETE /api/users/{id} ``` **需要认证**: 是 **权限要求**: admin ## 养殖场管理API ### 获取养殖场列表 ```http GET /api/farms ``` **需要认证**: 是 **查询参数:** - `page` (int): 页码，默认1 - `limit` (int): 每页数量，默认10 - `type` (string): 养殖场类型 - `status` (string): 状态 (`active`, `inactive`, `maintenance`) **响应:** ```json { "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 } } } ``` ### 获取公开养殖场数据 ```http GET /api/farms/public ``` **需要认证**: 否 ### 获取养殖场详情 ```http GET /api/farms/{id} ``` **需要认证**: 是 ### 创建养殖场 ```http POST /api/farms ``` **需要认证**: 是 **权限要求**: manager **请求体:** ```json { "name": "新养殖场", "type": "养猪场", "longitude": 106.26667, "latitude": 38.46667, "address": "详细地址", "owner": "联系人姓名", "phone": "13800138000", "status": "active" } ``` ### 更新养殖场 ```http PUT /api/farms/{id} ``` **需要认证**: 是 **权限要求**: manager ### 删除养殖场 ```http DELETE /api/farms/{id} ``` **需要认证**: 是 **权限要求**: admin ## 设备管理API ### 获取设备列表 ```http GET /api/devices ``` **需要认证**: 是 **查询参数:** - `page` (int): 页码 - `limit` (int): 每页数量 - `farm_id` (int): 养殖场ID - `type` (string): 设备类型 - `status` (string): 设备状态 (`online`, `offline`, `maintenance`) ### 获取设备详情 ```http GET /api/devices/{id} ``` **需要认证**: 是 **响应:** ```json { "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": "宁夏示范养殖场" } } } ``` ### 创建设备 ```http POST /api/devices ``` **需要认证**: 是 **权限要求**: manager **请求体:** ```json { "name": "新设备", "type": "传感器", "farm_id": 1, "installation_date": "2025-01-18", "metrics": { "temperature": 25.0 } } ``` ### 更新设备 ```http PUT /api/devices/{id} ``` **需要认证**: 是 **权限要求**: manager ### 删除设备 ```http DELETE /api/devices/{id} ``` **需要认证**: 是 **权限要求**: admin ## 动物管理API ### 获取动物列表 ```http GET /api/animals ``` **需要认证**: 是 **查询参数:** - `page` (int): 页码 - `limit` (int): 每页数量 - `farm_id` (int): 养殖场ID - `type` (string): 动物类型 - `health_status` (string): 健康状态 (`healthy`, `sick`, `quarantine`) ### 获取动物详情 ```http GET /api/animals/{id} ``` **需要认证**: 是 ### 创建动物记录 ```http POST /api/animals ``` **需要认证**: 是 **权限要求**: manager **请求体:** ```json { "type": "奶牛", "count": 100, "farm_id": 1, "health_status": "healthy", "notes": "备注信息" } ``` ### 更新动物记录 ```http PUT /api/animals/{id} ``` **需要认证**: 是 **权限要求**: manager ### 删除动物记录 ```http DELETE /api/animals/{id} ``` **需要认证**: 是 **权限要求**: admin ## 预警管理API ### 获取预警列表 ```http GET /api/alerts ``` **需要认证**: 是 **查询参数:** - `page` (int): 页码 - `limit` (int): 每页数量 - `farm_id` (int): 养殖场ID - `level` (string): 预警级别 (`low`, `medium`, `high`, `critical`) - `status` (string): 预警状态 (`active`, `acknowledged`, `resolved`) **响应:** ```json { "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 } } } ``` ### 确认预警 ```http PUT /api/alerts/{id}/acknowledge ``` **需要认证**: 是 **权限要求**: manager ### 解决预警 ```http PUT /api/alerts/{id}/resolve ``` **需要认证**: 是 **权限要求**: manager **请求体:** ```json { "resolution_notes": "问题已解决，温度已恢复正常" } ``` ## 产品管理API ### 获取产品列表 ```http GET /api/products ``` **需要认证**: 是 **查询参数:** - `page` (int): 页码 - `limit` (int): 每页数量 - `search` (string): 搜索关键词 - `is_active` (boolean): 是否激活 ### 获取产品详情 ```http GET /api/products/{id} ``` **需要认证**: 是 ### 创建产品 ```http POST /api/products ``` **需要认证**: 是 **权限要求**: manager **请求体:** ```json { "name": "优质鲜牛奶", "description": "新鲜优质牛奶，富含营养", "price": 5000, "stock": 1000, "image_url": "/uploads/products/milk.jpg", "is_active": true } ``` ### 更新产品 ```http PUT /api/products/{id} ``` **需要认证**: 是 **权限要求**: manager ### 删除产品 ```http DELETE /api/products/{id} ``` **需要认证**: 是 **权限要求**: admin ## 订单管理API ### 获取订单列表 ```http GET /api/orders ``` **需要认证**: 是 **查询参数:** - `page` (int): 页码 - `limit` (int): 每页数量 - `user_id` (int): 用户ID - `status` (string): 订单状态 (`pending`, `processing`, `shipped`, `delivered`, `cancelled`) - `payment_status` (string): 支付状态 (`unpaid`, `paid`, `refunded`) ### 获取订单详情 ```http GET /api/orders/{id} ``` **需要认证**: 是 **响应:** ```json { "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" } } ] } } ``` ### 创建订单 ```http POST /api/orders ``` **需要认证**: 是 **请求体:** ```json { "items": [ { "product_id": 1, "quantity": 2 } ], "shipping_address": "收货地址" } ``` ### 更新订单状态 ```http PUT /api/orders/{id}/status ``` **需要认证**: 是 **权限要求**: manager **请求体:** ```json { "status": "processing" } ``` ## 统计分析API ### 系统概览统计 ```http GET /api/stats/overview ``` **需要认证**: 是 **响应:** ```json { "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 } } } ``` ### 养殖场统计 ```http GET /api/stats/farms/{id} ``` **需要认证**: 是 ### 预警统计 ```http GET /api/stats/alerts ``` **需要认证**: 是 **查询参数:** - `timeRange` (string): 时间范围 (`today`, `week`, `month`) ### 动物健康统计 ```http GET /api/stats/animals ``` **需要认证**: 是 **查询参数:** - `farm_id` (int): 养殖场ID ## 地图服务API ### 获取地图数据 ```http GET /api/map/data ``` **需要认证**: 是 **响应:** ```json { "success": true, "data": { "farms": [ { "id": 1, "name": "宁夏示范养殖场", "location": { "lat": 38.46667, "lng": 106.26667 }, "type": "奶牛养殖", "status": "active", "devices_count": 5, "animals_count": 500 } ] } } ``` ## 性能监控API ### 获取性能指标 ```http GET /api/performance/metrics ``` **需要认证**: 是 **权限要求**: admin ### 获取系统资源信息 ```http GET /api/performance/system ``` **需要认证**: 是 **权限要求**: admin ### 获取数据库性能信息 ```http GET /api/performance/database ``` **需要认证**: 是 **权限要求**: admin ### 获取API性能统计 ```http GET /api/performance/api ``` **需要认证**: 是 **权限要求**: admin ## 文件上传API ### 上传头像 ```http POST /api/upload/avatar ``` **需要认证**: 是 **Content-Type**: `multipart/form-data` **请求:** ``` Content-Type: multipart/form-data avatar: [文件] ``` ### 上传产品图片 ```http 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 ```javascript // 安装: 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 ```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相关问题，请联系： - 技术支持: api-support@nxxmdata.com - 文档反馈: docs@nxxmdata.com *最后更新: 2025年1月*