nxxmdata/docs/API.md

# 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 <your_jwt_token>
```

### 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月*