MQTT通信修改 使用服务器数据库

docs/mqtt-embedded-communication.md

@@ -2,6 +2,8 @@
 
 本文档说明后端服务与嵌入式设备之间的 MQTT Topic、通信方向、Payload 类型和 JSON 数据格式。
 
+> **Topic 标识变更（v5.6 起）**：除首次注册回复 `registerDeviceNo` 仍按 **MAC 地址** 下发外，其余 MQTT 下行命令 Topic 第一段统一使用**设备编号 deviceNo**。后端上行处理通过 `DeviceIdentityResolver` 兼容 MAC / 设备编号两种入参；下行命令请按 `deviceNo` 订阅 `subscriber/cmd` 或 `subscriber/schedule`。业务字段（payload 中的 `deviceNo`、数据库主键、API 入参）仍是设备编号，未变更。
+
 当前配置位置：
 
 - 后端订阅配置：`water-admin/src/main/resources/application.yml`
@@ -14,8 +16,8 @@
 | --- | --- |
 | Broker | `mqtt.broker-url` |
 | QoS | `mqtt.qos`，当前默认 `1` |
-| 设备编号 | Topic 第一段 `{deviceNo}` |
-| Topic 变量 | 文档中的 `{deviceNo}` 替换为真实设备编号，例如 `/01/publish/register` |
+| 设备标识 | 上行 Topic 第一段可为设备 **MAC** 或 `deviceNo`；下行命令 Topic 第一段统一使用 `deviceNo`，仅 `registerDeviceNo` 例外仍使用 MAC |
+| Topic 变量 | 上行文档中的 `{deviceNo}` 表示设备标识占位符；下行文档中的 `{deviceNo}` 即设备编号 |
 | JSON 编码 | UTF-8 |
 | 时间格式 | `yyyy-MM-dd HH:mm:ss` |
 
@@ -52,22 +54,19 @@
 | Topic | `/{deviceNo}/publish/register` |
 | Payload 类型 | JSON |
 
-后端以 Topic 中的 `{deviceNo}` 作为设备编号，payload 中的 `deviceNo` 即使传入也会被 Topic 覆盖。
+后端以 Topic 中的设备标识作为解析入口，payload 中的 `deviceNo` 即使传入也会被 Topic 覆盖。
 
 示例：
 
 ```json
 {
   "deviceName": "一号浇水设备",
-  "status": "1",
-  "workStatus": "0",
   "powerLevel": "86",
-  "wifiName": "office-wifi",
   "deviceEm": "WATER-EM-01",
   "deviceSn": "SN202606100001",
   "fwVer": "1.0.0",
-  "macAddress": "AA:BB:CC:DD:EE:FF",
-  "bindToken": "123456"
+  "macAddress": "AA:BB:CC:DD:EE:FF"
+ 
 }
 ```
 
@@ -76,15 +75,11 @@
 | 字段 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
 | deviceName | string | 否 | 设备名称 |
-| status | string | 否 | 设备状态：`1` 在线，`0` 离线，`2` 到期，`3` 故障；为空时后端默认 `2` |
-| workStatus | string | 否 | 工作状态：`0` 休息，`1` 工作 |
 | powerLevel | string | 否 | 电量 |
-| wifiName | string | 否 | WiFi 名称 |
 | deviceEm | string | 否 | 设备型号 |
 | deviceSn | string | 否 | 设备序列号 |
 | fwVer | string | 否 | 固件版本 |
 | macAddress | string | 否 | MAC 地址 |
-| bindToken | string | 否 | 设备绑定令牌 |
 
 ## 电量上报
 
@@ -99,7 +94,9 @@
 
 ```json
 {
-  "powerLevel": "86"
+  "deviceName":	"Waterer_01",
+  "powerLevel": "86",
+  "charging":	1
 }
 ```
 
@@ -193,6 +190,17 @@ receive
 }
 ```
 
+## 设备编号下发
+
+| 项目 | 内容 |
+| --- | --- |
+| 功能名称 | 设备编号下发 |
+| 通信方向 | 后端发布，设备订阅 |
+| Topic | `/{deviceMac}/subscriber/cmd` |
+| Payload 类型 | JSON |
+
+说明：这是首次注册后的唯一例外，后端按设备 MAC 回传设备编号；其余下行命令都使用 `deviceNo` 作为 Topic 第一段。
+
 ## 排程任务完成上报
 
 | 项目 | 内容 |
@@ -300,7 +308,7 @@ JSON 示例：
 
 1. 设备启动后发布注册消息到 `/{deviceNo}/publish/register`。
 2. 设备定时或电量变化时发布电量到 `/{deviceNo}/publish/power`。
-3. 设备订阅自己的命令 Topic：`/{deviceNo}/subscriber/cmd`。
+3. 设备订阅自己的命令 Topic：`/{deviceNo}/subscriber/cmd` 和 `/{deviceNo}/subscriber/schedule`。
 4. 设备收到命令后立即返回 ACK 到 `/{deviceNo}/publish/ack`，推荐返回 JSON 并携带 `commandId`。
 5. 排程或按键浇水完成后，分别发布到 `/{deviceNo}/publish/finish/schedule` 或 `/{deviceNo}/publish/finish/key`。
 6. 硬件异常时发布到 `/{deviceNo}/publish/error`。