Update device identifier format from UUID to NanoID in example.jsonc, mqtt.md, schema.json, and schema.md; enhance documentation to reflect changes in device ID representation.

This commit is contained in:
2025-07-07 18:52:54 +08:00
parent 6c90561b6f
commit fb42ca777f
5 changed files with 17 additions and 21 deletions

View File

@ -11,7 +11,7 @@ WHTP 消息由根级字段与 `fields` 数组两部分组成。根级字段描
| version | 是 | number | 协议主版本号 |
| msg_type | 是 | string | 消息类别,目前仅 `"telemetry"` |
| mode | 否 | string | 工作模式,`"descriptive"`(默认)或 `"strict"` |
| dev_id | 是 | string | 设备唯一标识(UUID v4 |
| dev_id | 是 | string | 设备唯一标识(NanoID |
| dev_type | 是 | string / object | 设备型号标识 |
| timestamp | 是 | Timestamp | 消息生成时刻 |
| fields | 是 | Field[] | 采集字段数组 |
@ -36,7 +36,7 @@ WHTP 消息由根级字段与 `fields` 数组两部分组成。根级字段描
### 设备 ID (`dev_id`)
必填。设备唯一标识,采用 UUID v4 格式(如 `148413b4-c352-49a9-9c48-9d15276a99e7`),在设备生命周期内保持不变。
必填。设备唯一标识,采用 [NanoID](https://github.com/ai/nanoid) 格式(如 `2B1oj2S5k7kS8mL_QaCs`),在设备生命周期内保持不变。
### 设备类型 (`dev_type`)
@ -47,14 +47,14 @@ type DeviceType = string | { type_id: string } | { type_name: string }
必选。用于标识设备类别或型号。支持三种写法:
1. **字符串**:例如 `"device_type_name"`;与 `{ "type_name": string }` 等价
2. **对象** `{ "type_id": UUID }`UUID 为设备型号的唯一标识, 由平台分配
2. **对象** `{ "type_id": NanoID }`NanoID 为设备型号的唯一标识, 由平台分配
3. **对象** `{ "type_name": string }`
> [!NOTE]
>
> 以上三种写法在语义上等价, 由数据生产方按需选择
>
> - 对于长期稳定的系统, 推荐使用 `{ "type_id": UUID }` 格式, 作为稳定的唯一标识符
> - 对于长期稳定的系统, 推荐使用 `{ "type_id": NanoID }` 格式, 作为稳定的唯一标识符
> - 对于临时场景, 可以使用 `string` 或 `{ "type_name": string }` 格式
### 根级时间戳 (`timestamp`)