设备bug修改新增设备解绑功能

2026-08-25 16:18:34 +08:00
parent b789c1c07e
commit 509e760f3d
87 changed files with 4458 additions and 405 deletions
--- a/docs/mqtt-spec.md
+++ b/docs/mqtt-spec.md
@@ -89,17 +89,26 @@ long nextRetryAt;      // 下次重试时间戳
 }
 ```

+与用户绑定关系有关的命令（`switchDevice`、排程命令、`queryPower`、`otaUpgrade` 和自定义命令）还会携带当前关系的 `bindingId`。设备应在对应上报或 ACK 中原样返回 `bindingId`；服务端只接受与当前 ACTIVE 绑定一致的报文，旧绑定报文会被丢弃。`bindDevice` 使用命令自身携带的目标 `bindingId`，`initDevice` 不携带绑定标识。
+
 ### 3.2 上行 ACK 结构（DeviceCommandAck）

 ```json
 {
+  "deviceNo": "设备编号",
  "commandId": "对应下发命令的commandId",
-  "status": "1",
-  "message": "可选的文本消息"
+  "bindingId": "对应下发命令的绑定标识（有则原样返回）",
+  "ack": "receive",
+  "status": "兼容旧协议的确认标志",
+  "message": "可选的文本消息",
+  "powerLevel": 4,
+  "charging": 0
 }
 ```

-> 也支持非 JSON 格式的纯文本 ACK（当设备只有一条待确认命令时可自动匹配）。
+> - 设备确认标志优先使用 `ack` 字段（以 `"receive"` 开头即视为接受/成功，如 `"receive"`、`"receive deviceNo"`）；`status` 为兼容旧协议的字段。
+> - `powerLevel` / `charging` 仅在 `queryPower` 命令的 ACK 中返回，为**数字类型**，服务端会自动转为字符串后分别更新到设备表的 `power_level` 和 `power_status` 字段。
+> - 也支持非 JSON 格式的纯文本 ACK（当设备只有一条待确认命令时可自动匹配）。

 ---

@@ -116,6 +125,7 @@ long nextRetryAt;      // 下次重试时间戳
  "commandId": "xxx",
  "commandType": "switchDevice",
  "deviceNo": "01",
+  "bindingId": "当前绑定标识",
  "cmd": "1",
  "startTime": "2026-06-25 14:35:00",
  "durationMin": 20
@@ -214,6 +224,7 @@ long nextRetryAt;      // 下次重试时间戳
  "commandType": "bindSchedule",
  "cmd": -1,
  "deviceNo": "01",
+  "bindingId": "当前绑定标识",
  "schedule": {
    "id": 1,
    "name": "每日浇水",
@@ -258,6 +269,7 @@ long nextRetryAt;      // 下次重试时间戳
  "commandType": "unbindSchedule",
  "cmd": -1,
  "deviceNo": "01",
+  "bindingId": "当前绑定标识",
  "scheduleId": 1,
  "unbind": true
 }
@@ -285,6 +297,83 @@ long nextRetryAt;      // 下次重试时间戳

 ---

+### 4.8 电量查询命令 — `queryPower`
+
+**触发**: 用户在 APP 主动查询设备电量
+**接口**: `POST /app/v1/queryPower/{deviceNo}`
+**Topic**: `/{deviceNo}/subscriber/cmd`
+
+```json
+{
+  "commandId": "xxx",
+  "commandType": "queryPower",
+  "deviceNo": "01",
+  "bindingId": "当前绑定标识"
+}
+```
+
+**设备 ACK 回复**（`/{deviceNo}/publish/ack`）：
+
+```json
+{
+  "deviceNo": "2074069050702561282",
+  "commandId": "xxx",
+  "bindingId": "当前绑定标识",
+  "powerLevel": 4,
+  "charging": 0,
+  "ack": "receive"
+}
+```
+
+**附加行为**: 服务端收到 ACK 后，将 `powerLevel` 更新到设备表的 `power_level` 字段、`charging` 更新到 `power_status` 字段，并刷新 `power_level_updatatime`。`powerLevel`/`charging` 为数字类型（服务端自动转字符串入库），电量查询 ACK 不依赖 `status` 字段。
+
+---
+
+### 4.9 设备 OTA 升级命令 — `otaUpgrade`
+
+**触发**: 管理员在设备列表选择设备（或全部在线设备）下发固件升级
+**接口**: `POST /app/firmware/upgrade` · `POST /app/firmware/upgradeAll`
+**Topic**: `/{deviceNo}/subscriber/cmd`
+
+```json
+{
+  "commandId": "xxx",
+  "commandType": "otaUpgrade",
+  "deviceNo": "01",
+  "firmwareUrl": "https://api.example.com/app/firmware/download/0123456789abcdef0123456789abcdef.bin",
+  "firmwareVersion": "1.0.0",
+  "md5": "可选，固件 MD5 校验值"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `firmwareUrl` | String | 服务器固件下载地址 |
+| `firmwareVersion` | String | 目标固件版本号 |
+| `md5` | String | 固件 MD5 校验值（可选） |
+
+**升级结果回报**: 设备收到命令后回 ACK 确认，下载固件并升级，重启后重新走 `/publish/register` 上报新 `version`，服务端据此更新设备表的 `fw_ver` 字段。
+
+---
+
+### 4.10 设备恢复出厂命令 — `factoryReset`
+
+**触发**: 管理员在设备列表控制设备恢复出厂
+**接口**: `POST /app/device/factory-reset/{deviceNo}`
+**Topic**: `/{deviceNo}/subscriber/cmd`
+
+```json
+{
+  "commandId": "xxx",
+  "commandType": "factoryReset",
+  "deviceNo": "01"
+}
+```
+
+服务端只下发 MQTT 命令并等待设备 ACK，不清理服务端的用户绑定、排程或浇水日志。
+
+---
+
 ## 5. 上行消息类型详解

 ### 5.1 设备注册 — `/{identity}/publish/register`
@@ -315,7 +404,8 @@ long nextRetryAt;      // 下次重试时间戳

 ```json
 {
-  "powerLevel": "78"
+  "powerLevel": "78",
+  "bindingId": "当前绑定标识"
 }
 ```

@@ -354,6 +444,7 @@ long nextRetryAt;      // 下次重试时间戳
 {
  "deviceNo": "01",
  "commandId": "对应的命令ID",
+  "bindingId": "当前绑定标识",
  "startTime": "2026-06-25 08:00:00",
  "endTime": "2026-06-25 08:15:00",
  "durationMin": 15,
@@ -373,6 +464,7 @@ long nextRetryAt;      // 下次重试时间戳
 {
  "deviceNo": "01",
  "commandId": "对应的命令ID",
+  "bindingId": "当前绑定标识",
  "startTime": "2026-06-25 08:00:00",
  "endTime": "2026-06-25 08:15:00",
  "durationMin": 15,
@@ -390,7 +482,8 @@ long nextRetryAt;      // 下次重试时间戳
 ```json
 {
  "errorCode": "E001",
-  "message": "水泵故障"
+  "message": "水泵故障",
+  "bindingId": "当前绑定标识"
 }
 ```

@@ -468,6 +561,9 @@ long nextRetryAt;      // 下次重试时间戳
 | 绑定设备 | `POST /addDevice` | `bindDevice` | Service 层下发 |
 | 解绑设备 | `DELETE /deleteDevice/{deviceNos}` | `initDevice` | Service 层下发（每台设备） |
 | 开关设备 | `PUT /switchDevice` | `switchDevice` | Service 层下发 + 浇水日志 |
+| 查询电量 | `POST /queryPower/{deviceNo}` | `queryPower` | Service 层下发，ACK 回复电量 |
+| OTA 升级 | `POST /firmware/upgrade` · `POST /firmware/upgradeAll` | `otaUpgrade` | Service 层下发，重启注册后更新 fw_ver |
+| 恢复出厂 | `POST /device/factory-reset/{deviceNo}` | `factoryReset` | 仅下发 MQTT 命令，不修改服务端关系数据 |
 | 绑定排程设备 | `POST /addScheduleDevice` | `bindSchedule` | Controller 层下发 |
 | 解绑排程设备 | `DELETE /deleteScheduleDevice` | `unbindSchedule` | Controller 层下发 |
 | 修改排程状态 | `PUT /editScheduleStatus` | `bindSchedule` | 向所有绑定设备重新下发 |