# WH Telemetry Protocol over MQTT 补充说明

本文件提供将 WH Telemetry Protocol（WHTP）封装并传输于 MQTT 的推荐做法与约定，用于指导设备端、边缘网关及云端服务的接入与实现。

> 本文档为补充说明，仅描述 **传输层**（MQTT）相关约定。**应用层载荷** 仍遵循主规范 [WH Telemetry Protocol Specification](schema.md)。

## 总览

1. **主题命名**：采用层级语义化主题，便于基于通配符的订阅聚合。
2. **QoS**：默认使用 QoS1（至少一次），对高可靠性场景可使用 QoS2；不建议使用 QoS0。
3. **Retain**：遥测上行包默认不使用 Retain；状态类消息（如 LWT）可 Retain。
4. **连接安全**：~~TLS 是推荐选项，并配合基于证书或 Token 的双向认证。~~ 目前为调试期间, 使用无加密的 MQTT 连接的 1883 端口, 请生产方做好随时更换为 TLS 的准备
5. **会话管理**：生产端保持持久会话（Clean Start = 0），避免在网络抖动时丢失消息。

## 连接与认证

| 项目         | 建议                                                                                                            |
| ------------ | --------------------------------------------------------------------------------------------------------------- |
| 端口         | ~~`8883`（TLS）~~ / `1883`（非 TLS，仅调试）                                                                    |
| 加密         | ~~启用 TLS 1.2+；设备应校验服务器证书~~ 调试阶段无加密, 使用无验证方式传输                                      |
| 客户端标识符 | 使用设备 ID (`dev_id`)                                                                                          |
| 认证方式     | ~~(1) 双向 TLS + 设备证书<br/> (2) Username/Password 传递 JWT/OAuth2 Token~~ 调试阶段无认证, 使用无验证方式传输 |
| Keep-alive   | 60s–180s; 服务器以 1.5 倍 keep-alive 作为超时阈值                                                               |

## 消息主题

假设设备唯一标识 `dev_id = 148413b4-c352-49a9-9c48-9d15276a99e7`，则常用主题如下：

| 方向 | 主题模板            | 示例                                           | 说明                                 |
| ---- | ------------------- | ---------------------------------------------- | ------------------------------------ |
| 上行 | `/whtp/up/{dev_id}` | `whtp/up/148413b4-c352-49a9-9c48-9d15276a99e7` | 发送遥测数据（Payload 为 WHTP JSON） |


## QoS 与重传策略

| 场景     | 建议 QoS | 说明                                                 |
| -------- | -------: | ---------------------------------------------------- |
| 遥测数据 |        1 | 至少一次，可接受少量重复；设备收到 PUBACK 即视为成功 |
| 关键告警 |        2 | 云端必须且仅一次收到                                 |

> [!NOTE]
> **重复消息去重** 使用 `root.metadata.seq`（循环计数）及 MQTT 报文 `packetId` 实现。

## Payload 格式

MQTT Payload **必须**为 UTF-8 编码的文本，遵循 [WHTP 主规范](schema.md)。

```jsonc
// 示例：设备侧发布
Topic   : /whtp/up/148413b4-c352-49a9-9c48-9d15276a99e7
QoS     : 1
Retained: false
Payload : {
  "version": 1,
  "msg_type": "telemetry",
  "dev_id": "148413b4-c352-49a9-9c48-9d15276a99e7",
  "dev_type": "device_type_name",
  "timestamp": 1715145600,
  "fields": [
    { "id": "temperature", "value": 23.5, "metadata": { "data_type": "number", "unit": "Cel" } }
  ]
}
```

## 最佳实践

1. **批量上传**：对高频采样数据使用 `array<T>` 或 `irregular<T>`，显著降低 MQTT 消息数。
2. **压缩**：在弱网场景可使用 MQTT v5 `content-type: application/json` + `payload-format-indicator:1` 并启用网关级 gzip。
3. **流控**：设备端应监控 `MQTT_backpressure`，在云端未及时 ACK 时，暂存数据并退避重发，避免阻塞实时队列。
4. **时间同步**：定期通过 NTP 或云端 SNTP 服务校准，确保时间戳精度。
5. **错误处理**：当 `error_code ≠ 0` 时，建议 `confidence = 0` 并增加 `error_msg`，便于云端告警。