Files

lzh c71e8d31cf docs: 基于源码分析重建 IoT 领域技术文档（8 篇）

删除旧的规划性文档（01/02/03），替换为基于 viewsh-module-iot 模块
419 个 Java 文件全面分析生成的技术现状文档，覆盖：
- 模块架构全景、数据流、存储架构、Redis Key 清单
- 设备接入网关（MQTT/EMQX/HTTP/TCP + 7 种编解码器）
- 产品与设备管理（CRUD/状态机/认证/TDengine 双写）
- 物模型管理（9 种数据类型体系、TSL、DDL 联动）
- 规则引擎（数据转发/场景联动/数据清洗三链路）
- 告警与 OTA 升级（状态机、Quartz 调度）
- 消息总线与集成事件（Local/Redis/RocketMQ 三实现）
- API 契约与枚举汇总（5 Feign 接口、30+ 枚举）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-09 23:20:31 +08:00

8.5 KiB

Raw Blame History

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 记录状态

8.5 KiB Raw Blame History Unescape Escape

08-API 契约与枚举汇总

一、Feign RPC 接口

1.1 IotDeviceQueryApi（设备查询）

1.2 IotDeviceControlApi（设备控制）

1.3 IotDevicePropertyQueryApi（属性查询）

1.4 IotDeviceStatusQueryApi（状态查询）

1.5 TrajectoryStateApi（轨迹状态）

二、DTO 汇总

2.1 IotDeviceSimpleRespDTO

2.2 IotDeviceServiceInvokeReqDTO

2.3 IotDeviceServiceInvokeRespDTO

2.4 DevicePropertyRespDTO

2.5 DevicePropertyBatchQueryReqDTO

2.6 DevicePropertyHistoryQueryReqDTO

2.7 DeviceStatusRespDTO

2.8 DeviceLocationDTO

2.9 ResetTrafficCounterReqDTO

三、全量枚举汇总

3.1 产品枚举

3.2 设备枚举

3.3 物模型枚举

3.4 OTA 枚举

3.5 告警枚举

3.6 规则引擎枚举

3.7 Core 层枚举

3.8 字典类型常量

8.5 KiB

Raw Blame History