# 08-API 契约与枚举汇总

> 模块路径：`viewsh-module-iot-api` | 服务名：`iot-server` | RPC 前缀：`/rpc-api/iot`

---

## 一、Feign RPC 接口

### 1.1 IotDeviceQueryApi（设备查询）

| 方法 | HTTP | URL | 参数 | 返回 |
|------|------|-----|------|------|
| `getDeviceSimpleList` | GET | `/device/simple-list` | deviceType?, productId? | `List<IotDeviceSimpleRespDTO>` |
| `getDevice` | GET | `/device/get` | id | `IotDeviceSimpleRespDTO` |
| `batchGetDevices` | GET | `/device/batch-get` | ids | `List<IotDeviceSimpleRespDTO>` |

### 1.2 IotDeviceControlApi（设备控制）

| 方法 | HTTP | URL | 请求体 | 返回 |
|------|------|-----|--------|------|
| `invokeService` | POST | `/device/control/invoke-service` | `IotDeviceServiceInvokeReqDTO` | `IotDeviceServiceInvokeRespDTO` |
| `invokeServiceBatch` | POST | `/device/control/invoke-service-batch` | `List<...ReqDTO>` | `List<...RespDTO>` |
| `resetTrafficCounter` | POST | `/device/control/reset-traffic-counter` | `ResetTrafficCounterReqDTO` | Boolean |

### 1.3 IotDevicePropertyQueryApi（属性查询）

| 方法 | HTTP | URL | 参数 | 返回 |
|------|------|-----|------|------|
| `getProperty` | GET | `/device/property/get` | deviceId, identifier | `DevicePropertyRespDTO` |
| `getLatestProperties` | GET | `/device/property/get-latest` | deviceId | `Map<String, Object>` |
| `batchGetProperties` | POST | `/device/property/batch-get` | `DevicePropertyBatchQueryReqDTO` | `Map<Long, Map<String, Object>>` |
| `getPropertyHistory` | POST | `/device/property/history` | `DevicePropertyHistoryQueryReqDTO` | `List<DevicePropertyHistoryRespDTO>` |

### 1.4 IotDeviceStatusQueryApi（状态查询）

| 方法 | HTTP | URL | 参数 | 返回 |
|------|------|-----|------|------|
| `isDeviceOnline` | GET | `/device/status/is-online` | deviceId | Boolean |
| `getDeviceStatus` | GET | `/device/status/get-status` | deviceId | `DeviceStatusRespDTO` |
| `batchGetDeviceStatus` | GET | `/device/status/batch-get-status` | deviceIds | `List<DeviceStatusRespDTO>` |

### 1.5 TrajectoryStateApi（轨迹状态）

| 方法 | HTTP | URL | 参数 | 返回 |
|------|------|-----|------|------|
| `getCurrentLocation` | GET | `/trajectory/current-location` | deviceId | `DeviceLocationDTO` |

---

## 二、DTO 汇总

### 2.1 IotDeviceSimpleRespDTO

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 设备 ID |
| `deviceName` | String | 设备名称 |
| `productId` | Long | 产品 ID |
| `productKey` | String | 产品标识 |
| `productName` | String | 产品名称 |
| `nickname` | String | 备注名 |
| `serialNumber` | String | 序列号 |
| `state` | Integer | 0=未激活, 1=在线, 2=离线 |
| `deviceType` | Integer | 设备类型 |

### 2.2 IotDeviceServiceInvokeReqDTO

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `deviceId` | Long | 是 | 目标设备 |
| `identifier` | String | 是 | 服务标识 |
| `params` | Map\<String, Object\> | 否 | 服务参数 |
| `timeoutSeconds` | Integer | 否 | 超时秒数（默认 30） |

### 2.3 IotDeviceServiceInvokeRespDTO

| 字段 | 类型 | 说明 |
|------|------|------|
| `messageId` | String | 消息追踪 ID |
| `success` | Boolean | 是否成功 |
| `data` | Object | 响应数据 |
| `code` | Integer | 错误码 |
| `errorMsg` | String | 错误信息 |
| `responseTime` | LocalDateTime | 响应时间 |

### 2.4 DevicePropertyRespDTO

| 字段 | 类型 | 说明 |
|------|------|------|
| `identifier` | String | 属性标识 |
| `value` | Object | 当前值（动态类型） |
| `updateTime` | Long | 更新时间戳(ms) |

### 2.5 DevicePropertyBatchQueryReqDTO

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `deviceIds` | List\<Long\> | 是 | 设备 ID 列表 |
| `identifiers` | List\<String\> | 否 | 属性标识列表（空=全部） |

### 2.6 DevicePropertyHistoryQueryReqDTO

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `deviceId` | Long | 是 | 设备 ID |
| `identifier` | String | 是 | 属性标识 |
| `startTime` | LocalDateTime | 否 | 起始时间 |
| `endTime` | LocalDateTime | 否 | 截止时间 |
| `limit` | Integer | 否 | 最大条数（1-1000，默认 100） |

### 2.7 DeviceStatusRespDTO

| 字段 | 类型 | 说明 |
|------|------|------|
| `deviceId` | Long | 设备 ID |
| `deviceCode` | String | 设备编码 |
| `status` | Integer | 0/1/2 |
| `statusChangeTime` | LocalDateTime | 状态变更时间 |

### 2.8 DeviceLocationDTO

| 字段 | 类型 | 说明 |
|------|------|------|
| `deviceId` | Long | 设备 ID |
| `areaId` | Long | 区域 ID |
| `enterTime` | Long | 进入时间戳(ms) |
| `beaconMac` | String | Beacon MAC |
| `inArea` | Boolean | 是否在区域内 |

### 2.9 ResetTrafficCounterReqDTO

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `deviceId` | Long | 是 | 设备 ID |
| `newBaseValue` | Long | 否 | @Deprecated 已废弃 |
| `orderId` | Long | 否 | 关联工单 ID |
| `remark` | String | 否 | 操作说明 |

---

## 三、全量枚举汇总

### 3.1 产品枚举

| 枚举 | 值 | 说明 |
|------|----|------|
| **IotProductStatusEnum** | UNPUBLISHED(0), PUBLISHED(1) | 产品状态 |
| **IotProductDeviceTypeEnum** | DIRECT(0), GATEWAY_SUB(1), GATEWAY(2) | 设备拓扑类型 |
| **IotNetTypeEnum** | WIFI(0), CELLULAR(1), ETHERNET(2), OTHER(3) | 联网方式 |
| **IotLocationTypeEnum** | IP(1), DEVICE(2), MANUAL(3) | 定位方式 |

### 3.2 设备枚举

| 枚举 | 值 | 说明 |
|------|----|------|
| **IotDeviceStateEnum** | INACTIVE(0), ONLINE(1), OFFLINE(2) | 设备状态 |

### 3.3 物模型枚举

| 枚举 | 值 | 说明 |
|------|----|------|
| **IotThingModelTypeEnum** | PROPERTY(1), SERVICE(2), EVENT(3) | 功能类型 |
| **IotDataSpecsDataTypeEnum** | int, float, double, enum, bool, text, date, struct, array | 数据类型 |
| **IotThingModelAccessModeEnum** | READ_ONLY("r"), READ_WRITE("rw") | 访问模式 |
| **IotThingModelServiceCallTypeEnum** | ASYNC("async"), SYNC("sync") | 服务调用类型 |
| **IotThingModelServiceEventTypeEnum** | INFO("info"), ALERT("alert"), ERROR("error") | 事件级别 |
| **IotThingModelParamDirectionEnum** | INPUT("input"), OUTPUT("output") | 参数方向 |

### 3.4 OTA 枚举

| 枚举 | 值 | 说明 |
|------|----|------|
| **IotOtaTaskStatusEnum** | IN_PROGRESS(10), END(20), CANCELED(30) | 任务状态 |
| **IotOtaTaskRecordStatusEnum** | PENDING(0), PUSHED(10), UPGRADING(20), SUCCESS(30), FAILURE(40), CANCELED(50) | 记录状态 |
| **IotOtaTaskDeviceScopeEnum** | ALL(1), SELECT(2) | 设备范围 |

### 3.5 告警枚举

| 枚举 | 值 | 说明 |
|------|----|------|
| **IotAlertReceiveTypeEnum** | SMS(1), MAIL(2), NOTIFY(3) | 通知方式 |

### 3.6 规则引擎枚举

| 枚举 | 值 | 说明 |
|------|----|------|
| **IotDataSinkTypeEnum** | HTTP(1), TCP(2), WS(3), MQTT(10), DB(20), Redis(21), RocketMQ(30), RabbitMQ(31), Kafka(32) | 数据目的类型 |
| **IotRedisDataStructureEnum** | STREAM(1), HASH(2), LIST(3), SET(4), ZSET(5), STRING(6) | Redis 结构 |
| **IotSceneRuleTriggerTypeEnum** | STATE(1), PROPERTY(2), EVENT(3), SERVICE(4), TIMER(100) | 触发类型 |
| **IotSceneRuleConditionTypeEnum** | DEVICE_STATE(1), DEVICE_PROPERTY(2), CURRENT_TIME(100) | 条件类型 |
| **IotSceneRuleConditionOperatorEnum** | =, !=, >, >=, <, <=, in, not in, between, like, not null, time_>, time_<, ... | 操作符 |
| **IotSceneRuleActionTypeEnum** | PROPERTY_SET(1), SERVICE_INVOKE(2), ALERT_TRIGGER(100), ALERT_RECOVER(101) | 动作类型 |

### 3.7 Core 层枚举

| 枚举 | 值 | 说明 |
|------|----|------|
| **IotAuthTypeEnum** | SECRET, PRODUCT_SECRET, DYNAMIC, NONE | 认证类型 |
| **IotDeviceMessageMethodEnum** | thing.state.update, thing.property.post/set, thing.event.post, thing.service.invoke, thing.config.push, thing.ota.upgrade/progress | 消息方法 |
| **IotDeviceMessageTypeEnum** | state, event, service, config, ota, register, topology | 消息类型 |

### 3.8 字典类型常量

| 常量 | 字典值 | 说明 |
|------|--------|------|
| NET_TYPE | `iot_net_type` | 联网方式 |
| LOCATION_TYPE | `iot_location_type` | 定位方式 |
| CODEC_TYPE | `iot_codec_type` | 编解码类型 |
| PRODUCT_STATUS | `iot_product_status` | 产品状态 |
| PRODUCT_DEVICE_TYPE | `iot_product_device_type` | 产品设备类型 |
| DEVICE_STATE | `iot_device_state` | 设备状态 |
| ALERT_LEVEL | `iot_alert_level` | 告警级别 |
| OTA_TASK_DEVICE_SCOPE | `iot_ota_task_device_scope` | OTA 设备范围 |
| OTA_TASK_STATUS | `iot_ota_task_status` | OTA 任务状态 |
| OTA_TASK_RECORD_STATUS | `iot_ota_task_record_status` | OTA 记录状态 |