# IoT设备API

<cite>
**本文引用的文件**
- [IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java)
- [IotDevicePropertyQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java)
- [IotDeviceStatusQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java)
- [IotDeviceServiceInvokeReqDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/IotDeviceServiceInvokeReqDTO.java)
- [ResetTrafficCounterReqDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/ResetTrafficCounterReqDTO.java)
- [DevicePropertyBatchQueryReqDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/property/DevicePropertyBatchQueryReqDTO.java)
- [DevicePropertyHistoryQueryReqDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/property/DevicePropertyHistoryQueryReqDTO.java)
- [DevicePropertyRespDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/property/DevicePropertyRespDTO.java)
- [DevicePropertyHistoryRespDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/property/DevicePropertyHistoryRespDTO.java)
- [DeviceStatusRespDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/status/DeviceStatusRespDTO.java)
- [ApiConstants.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ApiConstants.java)
- [IotDeviceMessageTypeEnum.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/device/IotDeviceMessageTypeEnum.java)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件为IoT设备管理模块的全面API接口文档，涵盖设备控制、属性查询、状态监控等核心功能。文档详细说明了设备连接认证机制、设备属性定义和数据格式规范，并提供了设备远程控制命令的接口规范、控制指令格式和响应处理方式。同时，文档还详细描述了设备属性查询接口（包括实时属性获取和历史数据查询）、设备状态监控接口（在线状态、运行状态和故障状态的查询方法），以及设备OTA升级接口和固件版本管理API。

## 项目结构
IoT模块采用分层架构设计，主要由以下部分组成：
- API接口层：定义对外暴露的Feign客户端接口
- DTO数据传输对象：定义请求和响应的数据结构
- 枚举类：定义设备消息类型、状态枚举等常量
- 核心业务逻辑：在IoT服务器中实现具体的业务处理

```mermaid
graph TB
subgraph "IoT模块"
API[API接口层]
DTO[DTO数据传输对象]
ENUM[枚举类]
CORE[核心业务逻辑]
end
subgraph "外部系统"
OPS[运维系统]
APP[移动端应用]
WEB[Web管理平台]
end
OPS --> API
APP --> API
WEB --> API
API --> DTO
API --> ENUM
API --> CORE
CORE --> DTO
CORE --> ENUM
```

**图表来源**
- [IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java#L1-L53)
- [IotDevicePropertyQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java#L1-L64)
- [IotDeviceStatusQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java#L1-L37)

**章节来源**
- [IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java#L1-L53)
- [IotDevicePropertyQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java#L1-L64)
- [IotDeviceStatusQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java#L1-L37)

## 核心组件
IoT设备管理模块的核心组件包括三个主要的Feign客户端接口：

### 设备控制API接口
提供设备远程控制能力，支持服务调用、批量服务调用和客流计数器重置功能。

### 设备属性查询API接口  
提供设备属性的实时查询和历史数据查询功能，支持单个属性查询、批量属性查询和历史数据查询。

### 设备状态查询API接口
提供设备在线状态和设备状态信息的查询功能。

**章节来源**
- [IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java#L18-L52)
- [IotDevicePropertyQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java#L22-L63)
- [IotDeviceStatusQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java#L13-L36)

## 架构概览
IoT设备管理模块采用微服务架构，通过Feign客户端进行服务间通信。整体架构分为三层：

```mermaid
graph TB
subgraph "表现层"
CLIENT[客户端应用]
end
subgraph "网关层"
GATEWAY[API网关]
end
subgraph "服务层"
IOT_SERVER[IoT服务器]
DEVICE_SERVICE[设备服务]
DATA_SERVICE[数据服务]
end
subgraph "基础设施层"
DATABASE[(数据库)]
REDIS[(Redis缓存)]
MQ[(消息队列)]
end
CLIENT --> GATEWAY
GATEWAY --> IOT_SERVER
IOT_SERVER --> DEVICE_SERVICE
IOT_SERVER --> DATA_SERVICE
DEVICE_SERVICE --> DATABASE
DEVICE_SERVICE --> REDIS
DEVICE_SERVICE --> MQ
DATA_SERVICE --> DATABASE
DATA_SERVICE --> REDIS
```

**图表来源**
- [ApiConstants.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ApiConstants.java#L10-L23)

## 详细组件分析

### 设备控制API组件

#### 控制接口定义
设备控制API提供以下核心功能：

```mermaid
sequenceDiagram
participant Client as 客户端
participant API as 设备控制API
participant Server as IoT服务器
participant Device as 设备
Client->>API : 调用设备服务
API->>Server : RPC调用
Server->>Device : 发送控制指令
Device-->>Server : 返回执行结果
Server-->>API : 返回响应
API-->>Client : 返回控制结果
```

**图表来源**
- [IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java#L38-L44)

#### 服务调用请求DTO
服务调用请求包含以下关键字段：
- 设备ID：唯一标识目标设备
- 服务标识符：指定要调用的服务类型
- 服务参数：服务执行所需的参数
- 超时时间：服务执行的超时设置

#### 批量服务调用
支持一次性对多个设备执行相同的服务调用，提高操作效率。

#### 客流计数器重置
提供客流计数器的基准值重置功能，支持工单创建后的计数器调整。

**章节来源**
- [IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java#L18-L52)
- [IotDeviceServiceInvokeReqDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/IotDeviceServiceInvokeReqDTO.java#L13-L41)
- [ResetTrafficCounterReqDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/ResetTrafficCounterReqDTO.java#L10-L37)

### 设备属性查询API组件

#### 实时属性查询
提供设备属性的实时查询能力，支持单个属性查询和批量属性查询：

```mermaid
flowchart TD
Start([开始查询]) --> CheckType{查询类型}
CheckType --> |单个属性| SingleQuery[单个属性查询]
CheckType --> |批量属性| BatchQuery[批量属性查询]
CheckType --> |最新属性| LatestQuery[最新属性查询]
SingleQuery --> GetDevice[获取设备信息]
BatchQuery --> GetDevices[获取设备列表]
LatestQuery --> GetCache[获取缓存数据]
GetDevice --> QueryDB[查询数据库]
GetDevices --> QueryDB
QueryDB --> ProcessData[处理查询结果]
GetCache --> ProcessData
ProcessData --> ReturnResult[返回查询结果]
ReturnResult --> End([结束])
```

**图表来源**
- [IotDevicePropertyQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java#L37-L61)

#### 历史数据查询
支持按时间范围查询设备属性的历史数据，包含以下查询条件：
- 设备ID：指定查询的目标设备
- 属性标识符：指定查询的属性类型
- 开始时间和结束时间：限定查询的时间范围
- 限制条数：控制返回数据的最大数量

#### 属性数据格式
属性查询返回的数据包含以下字段：
- 属性标识符：属性的唯一标识
- 属性值：当前或历史的属性数值
- 更新时间：数据的更新时间戳

**章节来源**
- [IotDevicePropertyQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java#L22-L63)
- [DevicePropertyBatchQueryReqDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/property/DevicePropertyBatchQueryReqDTO.java#L9-L25)
- [DevicePropertyHistoryQueryReqDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/property/DevicePropertyHistoryQueryReqDTO.java#L12-L40)
- [DevicePropertyRespDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/property/DevicePropertyRespDTO.java#L9-L30)
- [DevicePropertyHistoryRespDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/property/DevicePropertyHistoryRespDTO.java#L9-L30)

### 设备状态查询API组件

#### 在线状态检测
提供设备在线状态的实时检测功能，通过以下方式判断设备状态：
- 心跳检测：基于设备的心跳包判断在线状态
- 缓存查询：从Redis缓存中获取最新的设备状态
- 最近活动时间：根据设备最近的消息活动时间判断状态

#### 设备状态信息
状态查询返回的设备状态信息包含：
- 设备ID：唯一标识设备
- 设备编码：设备的业务编码
- 设备状态：设备的当前状态（激活、在线、离线）
- 状态变更时间：状态最后一次变更的时间

```mermaid
stateDiagram-v2
[*] --> INACTIVE
INACTIVE --> ONLINE : 设备上线
INACTIVE --> OFFLINE : 设备离线
ONLINE --> OFFLINE : 设备下线
OFFLINE --> ONLINE : 设备重新上线
ONLINE --> INACTIVE : 设备注销
OFFLINE --> INACTIVE : 设备注销
```

**图表来源**
- [DeviceStatusRespDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/status/DeviceStatusRespDTO.java#L29-L30)

**章节来源**
- [IotDeviceStatusQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java#L13-L36)
- [DeviceStatusRespDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/status/DeviceStatusRespDTO.java#L11-L35)

### 设备消息类型定义

#### 消息类型枚举
IoT设备支持多种消息类型，每种类型对应不同的业务场景：

| 消息类型 | 描述 | 用途 |
|---------|------|------|
| STATE | 设备状态 | 设备运行状态的上报和查询 |
| PROPERTY | 设备属性 | 设备属性值的上报和查询 |
| EVENT | 设备事件 | 设备事件的上报和订阅 |
| SERVICE | 设备服务 | 设备服务的调用和执行 |
| CONFIG | 设备配置 | 设备配置的远程下发 |
| OTA | 设备OTA | 设备固件的远程升级 |
| REGISTER | 设备注册 | 设备的身份注册和认证 |
| TOPOLOGY | 设备拓扑 | 设备间的拓扑关系管理 |

**章节来源**
- [IotDeviceMessageTypeEnum.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/device/IotDeviceMessageTypeEnum.java#L9-L38)

## 依赖关系分析

### 组件依赖图
IoT设备管理模块的组件间依赖关系如下：

```mermaid
graph TB
subgraph "API层"
CONTROL_API[IotDeviceControlApi]
PROPERTY_API[IotDevicePropertyQueryApi]
STATUS_API[IotDeviceStatusQueryApi]
end
subgraph "DTO层"
SERVICE_REQ[IotDeviceServiceInvokeReqDTO]
RESET_REQ[ResetTrafficCounterReqDTO]
BATCH_REQ[DevicePropertyBatchQueryReqDTO]
HISTORY_REQ[DevicePropertyHistoryQueryReqDTO]
PROPERTY_RESP[DevicePropertyRespDTO]
HISTORY_RESP[DevicePropertyHistoryRespDTO]
STATUS_RESP[DeviceStatusRespDTO]
end
subgraph "枚举层"
API_CONST[ApiConstants]
MSG_TYPE[IotDeviceMessageTypeEnum]
end
CONTROL_API --> SERVICE_REQ
CONTROL_API --> RESET_REQ
PROPERTY_API --> BATCH_REQ
PROPERTY_API --> HISTORY_REQ
PROPERTY_API --> PROPERTY_RESP
PROPERTY_API --> HISTORY_RESP
STATUS_API --> STATUS_RESP
CONTROL_API --> API_CONST
PROPERTY_API --> API_CONST
STATUS_API --> API_CONST
CONTROL_API --> MSG_TYPE
PROPERTY_API --> MSG_TYPE
STATUS_API --> MSG_TYPE
```

**图表来源**
- [IotDeviceControlApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceControlApi.java#L3-L16)
- [IotDevicePropertyQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java#L3-L18)
- [IotDeviceStatusQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDeviceStatusQueryApi.java#L3-L11)

### 服务间通信流程
设备控制、属性查询、状态查询三类API通过统一的RPC前缀进行通信：

```mermaid
sequenceDiagram
participant Client as 客户端
participant ControlAPI as 设备控制API
participant PropertyAPI as 属性查询API
participant StatusAPI as 状态查询API
participant Server as IoT服务器
Client->>ControlAPI : 设备控制请求
ControlAPI->>Server : RPC调用
Server-->>ControlAPI : 控制结果
Client->>PropertyAPI : 属性查询请求
PropertyAPI->>Server : RPC调用
Server-->>PropertyAPI : 查询结果
Client->>StatusAPI : 状态查询请求
StatusAPI->>Server : RPC调用
Server-->>StatusAPI : 状态信息
```

**图表来源**
- [ApiConstants.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ApiConstants.java#L19-L21)

**章节来源**
- [ApiConstants.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/ApiConstants.java#L10-L23)

## 性能考虑
IoT设备管理模块在设计时充分考虑了性能优化：

### 缓存策略
- 实时属性查询优先从Redis缓存获取，减少数据库访问压力
- 设备状态信息使用缓存机制，提高查询响应速度
- 历史数据查询支持分页和时间范围限制，避免大数据量查询

### 批量操作优化
- 批量属性查询支持多设备、多属性的并行处理
- 批量服务调用减少网络往返次数
- 批量重置客流计数器支持事务性操作

### 连接池管理
- 使用连接池管理数据库连接，提高连接复用率
- 消息队列采用异步处理机制，提升系统吞吐量
- 缓存操作使用连接池，减少连接建立开销

## 故障排除指南

### 常见问题及解决方案

#### 设备不在线
**问题现象**：调用设备服务时返回失败
**可能原因**：
- 设备未正确注册到平台
- 设备网络连接异常
- 设备心跳包丢失

**解决步骤**：
1. 检查设备状态查询接口返回的状态
2. 验证设备的网络连接情况
3. 确认设备是否正常发送心跳包

#### 属性查询超时
**问题现象**：属性查询请求超时
**可能原因**：
- 设备离线或无响应
- 数据库查询性能问题
- 缓存未命中导致的延迟

**解决步骤**：
1. 检查设备在线状态
2. 优化数据库查询索引
3. 调整缓存策略和超时时间

#### 批量操作失败
**问题现象**：批量操作中部分设备执行失败
**可能原因**：
- 某些设备网络异常
- 设备服务调用超时
- 数据格式不匹配

**解决步骤**：
1. 分析批量操作的错误日志
2. 对失败的设备单独重试
3. 验证设备服务的可用性

**章节来源**
- [DeviceStatusRespDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/status/DeviceStatusRespDTO.java#L29-L30)
- [IotDevicePropertyQueryApi.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/IotDevicePropertyQueryApi.java#L58-L61)

## 结论
IoT设备管理模块提供了完整的设备生命周期管理能力，包括设备控制、属性查询、状态监控等功能。通过标准化的API接口和数据传输对象，实现了设备与系统的解耦，提高了系统的可扩展性和可维护性。模块采用微服务架构设计，支持高并发场景下的稳定运行，为IoT应用场景提供了可靠的技术支撑。

## 附录

### API接口规范汇总

#### 设备控制接口
- **服务调用**：POST `/rpc/iot/device/control/invoke-service`
- **批量服务调用**：POST `/rpc/iot/device/control/invoke-service-batch`
- **重置客流计数器**：POST `/rpc/iot/device/control/reset-traffic-counter`

#### 设备属性查询接口
- **单个属性查询**：GET `/rpc/iot/device/property/get`
- **最新属性查询**：GET `/rpc/iot/device/property/get-latest`
- **批量属性查询**：POST `/rpc/iot/device/property/batch-get`
- **属性历史查询**：POST `/rpc/iot/device/property/history`

#### 设备状态查询接口
- **在线状态检测**：GET `/rpc/iot/device/status/is-online`
- **设备状态查询**：GET `/rpc/iot/device/status/get-status`

### 数据模型定义

#### 设备状态枚举
- INACTIVE：设备未激活
- ONLINE：设备在线
- OFFLINE：设备离线

#### 设备消息类型
- STATE：设备状态消息
- PROPERTY：设备属性消息
- EVENT：设备事件消息
- SERVICE：设备服务消息
- CONFIG：设备配置消息
- OTA：设备OTA消息
- REGISTER：设备注册消息
- TOPOLOGY：设备拓扑消息

**章节来源**
- [IotDeviceMessageTypeEnum.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/enums/device/IotDeviceMessageTypeEnum.java#L15-L24)
- [DeviceStatusRespDTO.java](file://viewsh-module-iot/viewsh-module-iot-api/src/main/java/com/viewsh/module/iot/api/device/dto/status/DeviceStatusRespDTO.java#L29-L30)