# 物联网服务API设计文档

## 1. 概述

本文档详细描述了物联网服务(iot-service)提供的API接口，包括设备管理、传感器数据采集、设备控制、告警管理等核心功能。

## 2. 基础信息

- 基础路径: `/api/v1/iot`
- 版本: v1
- 通信协议: HTTP/HTTPS
- 数据格式: JSON
- 状态码: 遵循HTTP状态码规范

## 3. 全局Headers

| Header名称 | 是否必填 | 描述 |
|------------|----------|------|
| Authorization | 是 | Bearer Token认证信息 |
| Content-Type | 是 | application/json |

## 4. 全局响应格式

### 4.1 成功响应
```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

### 4.2 错误响应
```json
{
  "code": 40001,
  "message": "错误描述",
  "data": null
}
```

## 5. 设备管理接口

### 5.1 注册设备

**接口地址**: `POST /devices`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 是 | 设备唯一标识 |
| name | string | 是 | 设备名称 |
| type | string | 是 | 设备类型(传感器/控制器等) |
| model | string | 否 | 设备型号 |
| manufacturer | string | 否 | 制造商 |
| location | string | 否 | 设备位置 |
| description | string | 否 | 描述 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 设备ID |
| user_id | integer | 用户ID |
| device_id | string | 设备唯一标识 |
| name | string | 设备名称 |
| type | string | 设备类型 |
| model | string | 设备型号 |
| manufacturer | string | 制造商 |
| location | string | 设备位置 |
| status | string | 设备状态 |
| last_heartbeat | string | 最后心跳时间 |
| firmware_version | string | 固件版本 |
| description | string | 描述 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "device_id": "SENSOR001",
  "name": "温湿度传感器001",
  "type": "传感器",
  "model": "DHT22",
  "manufacturer": "某某电子",
  "location": "一号小麦田",
  "description": "用于监测农田环境温湿度"
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "user_id": 12345,
    "device_id": "SENSOR001",
    "name": "温湿度传感器001",
    "type": "传感器",
    "model": "DHT22",
    "manufacturer": "某某电子",
    "location": "一号小麦田",
    "status": "ACTIVE",
    "last_heartbeat": null,
    "firmware_version": null,
    "description": "用于监测农田环境温湿度",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 5.2 获取设备列表

**接口地址**: `GET /devices`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| type | string | 否 | 设备类型筛选 |
| status | string | 否 | 设备状态筛选 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 设备列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1001,
        "user_id": 12345,
        "device_id": "SENSOR001",
        "name": "温湿度传感器001",
        "type": "传感器",
        "model": "DHT22",
        "manufacturer": "某某电子",
        "location": "一号小麦田",
        "status": "ACTIVE",
        "last_heartbeat": null,
        "firmware_version": null,
        "description": "用于监测农田环境温湿度",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 5.3 获取设备详情

**接口地址**: `GET /devices/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 设备ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 设备ID |
| user_id | integer | 用户ID |
| device_id | string | 设备唯一标识 |
| name | string | 设备名称 |
| type | string | 设备类型 |
| model | string | 设备型号 |
| manufacturer | string | 制造商 |
| location | string | 设备位置 |
| status | string | 设备状态 |
| last_heartbeat | string | 最后心跳时间 |
| firmware_version | string | 固件版本 |
| description | string | 描述 |
| configs | array | 设备配置列表 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "user_id": 12345,
    "device_id": "SENSOR001",
    "name": "温湿度传感器001",
    "type": "传感器",
    "model": "DHT22",
    "manufacturer": "某某电子",
    "location": "一号小麦田",
    "status": "ACTIVE",
    "last_heartbeat": "2024-01-15T10:30:00Z",
    "firmware_version": "v1.0.0",
    "description": "用于监测农田环境温湿度",
    "configs": [
      {
        "config_key": "sampling_interval",
        "config_value": "300",
        "description": "采样间隔(秒)"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

### 5.4 更新设备信息

**接口地址**: `PUT /devices/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 设备ID |
| name | string | 否 | 设备名称 |
| location | string | 否 | 设备位置 |
| status | string | 否 | 设备状态 |
| description | string | 否 | 描述 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 设备ID |
| user_id | integer | 用户ID |
| device_id | string | 设备唯一标识 |
| name | string | 设备名称 |
| type | string | 设备类型 |
| model | string | 设备型号 |
| manufacturer | string | 制造商 |
| location | string | 设备位置 |
| status | string | 设备状态 |
| last_heartbeat | string | 最后心跳时间 |
| firmware_version | string | 固件版本 |
| description | string | 描述 |
| updated_at | string | 更新时间 |

**示例请求**:
```json
{
  "name": "温湿度传感器001",
  "location": "一号小麦田A区",
  "status": "ACTIVE",
  "description": "用于监测农田环境温湿度，位置已更新"
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "user_id": 12345,
    "device_id": "SENSOR001",
    "name": "温湿度传感器001",
    "type": "传感器",
    "model": "DHT22",
    "manufacturer": "某某电子",
    "location": "一号小麦田A区",
    "status": "ACTIVE",
    "last_heartbeat": "2024-01-15T10:30:00Z",
    "firmware_version": "v1.0.0",
    "description": "用于监测农田环境温湿度，位置已更新",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}
```

### 5.5 删除设备

**接口地址**: `DELETE /devices/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 设备ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| message | string | 删除结果信息 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "设备删除成功"
  }
}
```

## 6. 传感器数据接口

### 6.1 上报传感器数据

**接口地址**: `POST /sensor-data`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 是 | 设备ID |
| sensor_type | string | 是 | 传感器类型(温度/湿度/光照等) |
| value | number | 是 | 传感器数值 |
| unit | string | 是 | 单位 |
| timestamp | string | 否 | 数据时间戳(ISO8601格式)，默认为当前时间 |
| latitude | number | 否 | 纬度 |
| longitude | number | 否 | 经度 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 数据记录ID |
| device_id | string | 设备ID |
| sensor_type | string | 传感器类型 |
| value | number | 传感器数值 |
| unit | string | 单位 |
| timestamp | string | 数据时间戳 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "device_id": "SENSOR001",
  "sensor_type": "温度",
  "value": 25.6,
  "unit": "℃",
  "timestamp": "2024-01-15T10:30:00Z",
  "latitude": 39.9042,
  "longitude": 116.4074
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2001,
    "device_id": "SENSOR001",
    "sensor_type": "温度",
    "value": 25.6,
    "unit": "℃",
    "timestamp": "2024-01-15T10:30:00Z",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 6.2 获取传感器数据列表

**接口地址**: `GET /sensor-data`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 否 | 设备ID筛选 |
| sensor_type | string | 否 | 传感器类型筛选 |
| start_time | string | 否 | 开始时间(ISO8601格式) |
| end_time | string | 否 | 结束时间(ISO8601格式) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 传感器数据列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 2001,
        "device_id": "SENSOR001",
        "sensor_type": "温度",
        "value": 25.6,
        "unit": "℃",
        "timestamp": "2024-01-15T10:30:00Z",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 6.3 获取传感器数据统计

**接口地址**: `GET /sensor-data/statistics`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 是 | 设备ID |
| sensor_type | string | 是 | 传感器类型 |
| aggregation_type | string | 是 | 聚合类型(HOURLY/DAILY/WEEKLY/MONTHLY) |
| start_time | string | 否 | 开始时间(ISO8601格式) |
| end_time | string | 否 | 结束时间(ISO8601格式) |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| device_id | string | 设备ID |
| sensor_type | string | 传感器类型 |
| aggregation_type | string | 聚合类型 |
| data | array | 统计数据列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "device_id": "SENSOR001",
    "sensor_type": "温度",
    "aggregation_type": "DAILY",
    "data": [
      {
        "timestamp": "2024-01-15T00:00:00Z",
        "min_value": 22.1,
        "max_value": 26.8,
        "avg_value": 24.5,
        "count": 24
      }
    ]
  }
}
```

## 7. 设备控制接口

### 7.1 发送控制命令

**接口地址**: `POST /commands`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 是 | 设备ID |
| command | string | 是 | 命令名称 |
| parameters | object | 否 | 命令参数 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 命令ID |
| device_id | string | 设备ID |
| command | string | 命令名称 |
| parameters | object | 命令参数 |
| status | string | 命令状态 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "device_id": "CTRL001",
  "command": "开启灌溉",
  "parameters": {
    "duration": 300,
    "flow_rate": 10
  }
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 3001,
    "device_id": "CTRL001",
    "command": "开启灌溉",
    "parameters": {
      "duration": 300,
      "flow_rate": 10
    },
    "status": "PENDING",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 7.2 获取命令执行状态

**接口地址**: `GET /commands/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 命令ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 命令ID |
| device_id | string | 设备ID |
| command | string | 命令名称 |
| parameters | object | 命令参数 |
| status | string | 命令状态 |
| result | string | 执行结果 |
| sent_at | string | 发送时间 |
| executed_at | string | 执行时间 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 3001,
    "device_id": "CTRL001",
    "command": "开启灌溉",
    "parameters": {
      "duration": 300,
      "flow_rate": 10
    },
    "status": "EXECUTED",
    "result": "灌溉系统已开启，将持续300秒",
    "sent_at": "2024-01-15T10:30:00Z",
    "executed_at": "2024-01-15T10:30:05Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:05Z"
  }
}
```

### 7.3 获取命令历史列表

**接口地址**: `GET /commands`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 否 | 设备ID筛选 |
| command | string | 否 | 命令名称筛选 |
| status | string | 否 | 命令状态筛选 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 命令列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 3001,
        "device_id": "CTRL001",
        "command": "开启灌溉",
        "parameters": {
          "duration": 300,
          "flow_rate": 10
        },
        "status": "EXECUTED",
        "result": "灌溉系统已开启，将持续300秒",
        "sent_at": "2024-01-15T10:30:00Z",
        "executed_at": "2024-01-15T10:30:05Z",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

## 8. 告警管理接口

### 8.1 获取告警列表

**接口地址**: `GET /alerts`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 否 | 设备ID筛选 |
| alert_type | string | 否 | 告警类型筛选 |
| alert_level | string | 否 | 告警级别筛选 |
| resolved | boolean | 否 | 是否已解决筛选 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 告警列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 4001,
        "device_id": "SENSOR001",
        "alert_type": "阈值超限",
        "alert_level": "WARNING",
        "message": "温度超过阈值35℃",
        "value": 36.5,
        "threshold": 35.0,
        "resolved": false,
        "timestamp": "2024-01-15T10:30:00Z",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 8.2 标记告警为已解决

**接口地址**: `PUT /alerts/{id}/resolve`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 告警ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 告警ID |
| resolved | boolean | 是否已解决 |
| resolved_at | string | 解决时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 4001,
    "resolved": true,
    "resolved_at": "2024-01-15T11:00:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}
```

## 9. 设备配置接口

### 9.1 获取设备配置

**接口地址**: `GET /devices/{id}/configs`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 设备ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| items | array | 配置列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "config_key": "sampling_interval",
        "config_value": "300",
        "description": "采样间隔(秒)"
      }
    ]
  }
}
```

### 9.2 更新设备配置

**接口地址**: `PUT /devices/{id}/configs`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 设备ID |
| configs | array | 是 | 配置列表 |

**configs元素结构**:

| 字段名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| config_key | string | 是 | 配置键 |
| config_value | string | 是 | 配置值 |
| description | string | 否 | 配置描述 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| message | string | 更新结果信息 |

**示例请求**:
```json
{
  "configs": [
    {
      "config_key": "sampling_interval",
      "config_value": "600",
      "description": "采样间隔(秒)"
    }
  ]
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "设备配置更新成功"
  }
}
```

## 10. 错误码定义

| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 40001 | 参数错误 | 请求参数不合法 |
| 40002 | 设备不存在 | 指定的设备不存在 |
| 40003 | 设备状态不允许此操作 | 当前设备状态不允许执行该操作 |
| 40004 | 传感器数据记录不存在 | 指定的传感器数据记录不存在 |
| 40005 | 设备命令不存在 | 指定的设备命令不存在 |
| 40006 | 命令状态不允许此操作 | 当前命令状态不允许执行该操作 |
| 40007 | 告警记录不存在 | 指定的告警记录不存在 |
| 50001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 50002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |