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.

2025-07-07 18:52:54 +08:00
parent 6c90561b6f
commit fb42ca777f
5 changed files with 17 additions and 21 deletions
--- a/README.md
+++ b/README.md
@ -7,12 +7,8 @@ WH Telemetry Protocol（简称 **WHTP**）是一套面向物联网场景的 **JS
 ## 特性亮点

 - **自描述（Self-descriptive）**：数据类型、单位、采样间隔等元信息随报文一并上送，脱离外部 Schema 亦可独立解析。
- **单一载体（JSON）**：无需生成器或专用编解码库，主流语言天然支持。
- **时间表达力强**：支持从秒到纳秒的多粒度 UNIX 时间戳，或 ISO-8601 字符串。
 - **批量数据友好**：内置等间隔 `array<T>` 与非等间隔 `irregular<T>` 两种批量格式，可显著降低消息数。
 - **枚举支持**：全局或内联枚举可读性强，兼具类型安全。
- **错误／置信度模型**：统一的 `error_code` + `confidence` 机制，便于数据质量管理。
- **多传输层**：已提供 [MQTT 补充说明](mqtt.md)，亦可轻松扩展至 HTTP、WebSocket、CoAP 等。

 ## 快速上手

@ -29,5 +25,3 @@ WH Telemetry Protocol（简称 **WHTP**）是一套面向物联网场景的 **JS
 | `mqtt.md`       | MQTT 传输层补充说明               |
 | `example.jsonc` | 完整示例消息，含字段注释          |
 | `README.md`     | 当前文件，项目概览                |
-
-
--- a/example.jsonc
+++ b/example.jsonc
@ -8,11 +8,11 @@
    // 
    // for descriptive mode, everything should self contained (like unit, sample interval, etc.)
    "mode": "descriptive",
-    "dev_id": "148413b4-c352-49a9-9c48-9d15276a99e7", // uuid-v4, unique for each device
+    "dev_id": "2B1oj2S5k7kS8mL_QaCs", // NanoID, unique for each device
    "dev_type": "device_type_name",
    // "dev_type field supports:
    // string: designated by a unique string
-    // {"type_id": "148413b4-c352-49a9-9c48-9d15276a99e7"} // uuid-v4, unique for each device type
+    // {"type_id": "2B1oj2S5k7kS8mL_QaCs"} // NanoID, unique for each device type
    // {"type_name": "device_type_name"} // unique string, same as the string above
    "timestamp": 1715145600, // UNIX timestamp in seconds
    // timestamp fields supports:
--- a/mqtt.md
+++ b/mqtt.md
@ -24,11 +24,11 @@

 ## 消息主题

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

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


 ## QoS 与重传策略
@ -47,13 +47,13 @@ MQTT Payload **必须**为 UTF-8 编码的文本，遵循 [WHTP 主规范](schem

 ```jsonc
 // 示例：设备侧发布
-Topic   : /whtp/up/148413b4-c352-49a9-9c48-9d15276a99e7
+Topic   : /whtp/up/2B1oj2S5k7kS8mL_QaCs
 QoS     : 1
 Retained: false
 Payload : {
  "version": 1,
  "msg_type": "telemetry",
-  "dev_id": "148413b4-c352-49a9-9c48-9d15276a99e7",
+  "dev_id": "2B1oj2S5k7kS8mL_QaCs",
  "dev_type": "device_type_name",
  "timestamp": 1715145600,
  "fields": [
--- a/schema.json
+++ b/schema.json
@ -34,8 +34,9 @@
        },
        "dev_id": {
            "type": "string",
-            "format": "uuid",
-            "description": "Device unique identifier (UUID v4)."
+            "format": "nanoid",
+            "description": "Device unique identifier (NanoID).",
+            "pattern": "^[A-Za-z0-9_-]{21}$"
        },
        "dev_type": {
            "description": "Device model identifier.",
@ -53,7 +54,8 @@
                            "properties": {
                                "type_id": {
                                    "type": "string",
-                                    "format": "uuid"
+                                    "format": "nanoid",
+                                    "pattern": "^[A-Za-z0-9_-]{21}$"
                                }
                            },
                            "additionalProperties": false
--- a/schema.md
+++ b/schema.md
@ -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`)