第一次提交

yudao-module-iot/yudao-module-iot-gateway/src/test/resources/tcp-binary-packet-examples.md

@@ -0,0 +1,193 @@
+# TCP 二进制协议数据包格式说明
+
+## 1. 协议概述
+
+TCP 二进制协议是一种高效的自定义协议格式，采用紧凑的二进制格式传输数据，适用于对带宽和性能要求较高的 IoT 场景。
+
+### 1.1 协议特点
+
+- **高效传输**：完全二进制格式，减少数据传输量
+- **版本控制**：内置协议版本号，支持协议升级
+- **类型安全**：明确的消息类型标识
+- **简洁设计**：去除冗余字段，协议更加精简
+- **兼容性**：与现有 `IotDeviceMessage` 接口完全兼容
+
+## 2. 协议格式
+
+### 2.1 整体结构
+
+```
++--------+--------+--------+---------------------------+--------+--------+
+| 魔术字 | 版本号 | 消息类型|         消息长度(4字节)          |
++--------+--------+--------+---------------------------+--------+--------+
+|           消息 ID 长度(2字节)        |      消息 ID (变长字符串)         |
++--------+--------+--------+--------+--------+--------+--------+--------+
+|           方法名长度(2字节)        |      方法名(变长字符串)         |
++--------+--------+--------+--------+--------+--------+--------+--------+
+|                        消息体数据(变长)                              |
++--------+--------+--------+--------+--------+--------+--------+--------+
+```
+
+### 2.2 字段详细说明
+
+| 字段 | 长度 | 类型 | 说明 |
+|------|------|------|------|
+| 魔术字 | 1字节 | byte | `0x7E` - 协议识别标识，用于数据同步 |
+| 版本号 | 1字节 | byte | `0x01` - 协议版本号，支持版本控制 |
+| 消息类型 | 1字节 | byte | `0x01`=请求, `0x02`=响应 |
+| 消息长度 | 4字节 | int | 整个消息的总长度（包含头部） |
+| 消息 ID 长度 | 2字节 | short | 消息 ID 字符串的字节长度 |
+| 消息 ID | 变长 | string | 消息唯一标识符（UTF-8编码） |
+| 方法名长度 | 2字节 | short | 方法名字符串的字节长度 |
+| 方法名 | 变长 | string | 消息方法名（UTF-8编码） |
+| 消息体 | 变长 | binary | 根据消息类型的不同数据格式 |
+
+**⚠️ 重要说明**：deviceId 不包含在协议中，由服务器根据连接上下文自动设置
+
+### 2.3 协议常量定义
+
+```java
+// 协议标识
+private static final byte MAGIC_NUMBER = (byte) 0x7E;
+private static final byte PROTOCOL_VERSION = (byte) 0x01;
+
+// 消息类型
+private static final byte REQUEST = (byte) 0x01;   // 请求消息
+private static final byte RESPONSE = (byte) 0x02;  // 响应消息
+
+// 协议长度
+private static final int HEADER_FIXED_LENGTH = 7;      // 固定头部长度
+private static final int MIN_MESSAGE_LENGTH = 11;      // 最小消息长度
+```
+
+## 3. 消息类型和格式
+
+### 3.1 请求消息 (REQUEST - 0x01)
+
+请求消息用于设备向服务器发送数据或请求。
+
+#### 3.1.1 消息体格式
+```
+消息体 = params 数据(JSON格式)
+```
+
+#### 3.1.2 示例：设备认证请求
+
+**消息内容：**
+- 消息 ID: `auth_1704067200000_123`
+- 方法名: `auth`
+- 参数: `{"clientId":"device_001","username":"productKey_deviceName","password":"device_password"}`
+
+**二进制数据包结构：**
+```
+7E                              // 魔术字 (0x7E)
+01                              // 版本号 (0x01)
+01                              // 消息类型 (REQUEST)
+00 00 00 89                     // 消息长度 (137字节)
+00 19                           // 消息 ID 长度 (25字节)
+61 75 74 68 5F 31 37 30 34 30   // 消息 ID: "auth_1704067200000_123"
+36 37 32 30 30 30 30 30 5F 31 
+32 33
+00 04                           // 方法名长度 (4字节)
+61 75 74 68                     // 方法名: "auth"
+7B 22 63 6C 69 65 6E 74 49 64   // JSON参数数据
+22 3A 22 64 65 76 69 63 65 5F   // {"clientId":"device_001",
+30 30 31 22 2C 22 75 73 65 72   //  "username":"productKey_deviceName",
+6E 61 6D 65 22 3A 22 70 72 6F   //  "password":"device_password"}
+64 75 63 74 4B 65 79 5F 64 65
+76 69 63 65 4E 61 6D 65 22 2C
+22 70 61 73 73 77 6F 72 64 22
+3A 22 64 65 76 69 63 65 5F 70
+61 73 73 77 6F 72 64 22 7D
+```
+
+#### 3.1.3 示例：属性数据上报
+
+**消息内容：**
+- 消息 ID: `property_1704067200000_456`
+- 方法名: `thing.property.post`
+- 参数: `{"temperature":25.5,"humidity":60.2,"pressure":1013.25}`
+
+### 3.2 响应消息 (RESPONSE - 0x02)
+
+响应消息用于服务器向设备回复请求结果。
+
+#### 3.2.1 消息体格式
+```
+消息体 = 响应码(4字节) + 响应消息长度(2字节) + 响应消息(UTF-8) + 响应数据(JSON)
+```
+
+#### 3.2.2 字段说明
+
+| 字段 | 长度 | 类型 | 说明 |
+|------|------|------|------|
+| 响应码 | 4字节 | int | HTTP状态码风格，0=成功，其他=错误 |
+| 响应消息长度 | 2字节 | short | 响应消息字符串的字节长度 |
+| 响应消息 | 变长 | string | 响应提示信息（UTF-8编码） |
+| 响应数据 | 变长 | binary | JSON格式的响应数据（可选） |
+
+#### 3.2.3 示例：认证成功响应
+
+**消息内容：**
+- 消息 ID: `auth_response_1704067200000_123`
+- 方法名: `auth`
+- 响应码: `0`
+- 响应消息: `认证成功`
+- 响应数据: `{"success":true,"message":"认证成功"}`
+
+**二进制数据包结构：**
+```
+7E                              // 魔术字 (0x7E)
+01                              // 版本号 (0x01)
+02                              // 消息类型 (RESPONSE)
+00 00 00 A4                     // 消息长度 (164字节)
+00 22                           // 消息 ID 长度 (34字节)
+61 75 74 68 5F 72 65 73 70 6F   // 消息 ID: "auth_response_1704067200000_123"
+6E 73 65 5F 31 37 30 34 30 36
+37 32 30 30 30 30 30 5F 31 32
+33
+00 04                           // 方法名长度 (4字节)
+61 75 74 68                     // 方法名: "auth"
+00 00 00 00                     // 响应码 (0 = 成功)
+00 0C                           // 响应消息长度 (12字节)
+E8 AE A4 E8 AF 81 E6 88 90 E5   // 响应消息: "认证成功" (UTF-8)
+8A 9F
+7B 22 73 75 63 63 65 73 73 22   // JSON响应数据
+3A 74 72 75 65 2C 22 6D 65 73   // {"success":true,"message":"认证成功"}
+73 61 67 65 22 3A 22 E8 AE A4
+E8 AF 81 E6 88 90 E5 8A 9F 22
+7D
+```
+
+## 4. 编解码器标识
+
+```java
+public static final String TYPE = "TCP_BINARY";
+```
+
+## 5. 协议优势
+
+- **数据紧凑**：二进制格式，相比 JSON 减少 30-50% 的数据量
+- **解析高效**：直接二进制操作，减少字符串转换开销
+- **类型安全**：明确的消息类型和字段定义
+- **设计简洁**：去除冗余字段，协议更加精简高效
+- **版本控制**：内置版本号支持协议升级
+
+## 6. 与 JSON 协议对比
+
+| 特性   | 二进制协议       | JSON协议 |
+|------|-------------|--------|
+| 数据大小 | 小（节省30-50%） | 大      |
+| 解析性能 | 高           | 中等     |
+| 网络开销 | 低           | 高      |
+| 可读性  | 差           | 优秀     |
+| 调试难度 | 高           | 低      |
+| 扩展性  | 良好          | 优秀     |
+
+**推荐场景**：
+- ✅ **高频数据传输**：传感器数据实时上报
+- ✅ **带宽受限环境**：移动网络、卫星通信
+- ✅ **性能要求高**：需要低延迟、高吞吐的场景
+- ✅ **设备资源有限**：嵌入式设备、低功耗设备
+- ❌ **开发调试阶段**：调试困难，建议使用 JSON 协议
+- ❌ **快速原型开发**：开发效率低

yudao-module-iot/yudao-module-iot-gateway/src/test/resources/tcp-json-packet-examples.md

@@ -0,0 +1,191 @@
+# TCP JSON 格式协议说明
+
+## 1. 协议概述
+
+TCP JSON 格式协议采用纯 JSON 格式进行数据传输，具有以下特点：
+
+- **标准化**：使用标准 JSON 格式，易于解析和处理
+- **可读性**：人类可读，便于调试和维护
+- **扩展性**：可以轻松添加新字段，向后兼容
+- **跨平台**：JSON 格式支持所有主流编程语言
+- **安全优化**：移除冗余的 deviceId 字段，提高安全性
+
+## 2. 消息格式
+
+### 2.1 基础消息结构
+
+```json
+{
+  "id": "消息唯一标识",
+  "method": "消息方法",
+  "params": {
+    // 请求参数
+  },
+  "data": {
+    // 响应数据
+  },
+  "code": 响应码,
+  "msg": "响应消息",
+  "timestamp": 时间戳
+}
+```
+
+**⚠️ 重要说明**：
+- **不包含 deviceId 字段**：由服务器通过 TCP 连接上下文自动确定设备 ID
+- **避免伪造攻击**：防止设备伪造其他设备的 ID 发送消息
+
+### 2.2 字段详细说明
+
+| 字段名 | 类型 | 必填 | 用途 | 说明 |
+|--------|------|------|------|------|
+| id | String | 是 | 所有消息 | 消息唯一标识 |
+| method | String | 是 | 所有消息 | 消息方法，如 `auth`、`thing.property.post` |
+| params | Object | 否 | 请求消息 | 请求参数，具体内容根据method而定 |
+| data | Object | 否 | 响应消息 | 响应数据，服务器返回的结果数据 |
+| code | Integer | 否 | 响应消息 | 响应码，0=成功，其他=错误 |
+| msg | String | 否 | 响应消息 | 响应提示信息 |
+| timestamp | Long | 是 | 所有消息 | 时间戳（毫秒），编码时自动生成 |
+
+### 2.3 消息分类
+
+#### 2.3.1 请求消息（上行）
+- **特征**：包含 `params` 字段，不包含 `code`、`msg` 字段
+- **方向**：设备 → 服务器
+- **用途**：设备认证、数据上报、状态更新等
+
+#### 2.3.2 响应消息（下行）
+- **特征**：包含 `code`、`msg` 字段，可能包含 `data` 字段
+- **方向**：服务器 → 设备  
+- **用途**：认证结果、指令响应、错误提示等
+
+## 3. 消息示例
+
+### 3.1 设备认证 (auth)
+
+#### 认证请求格式
+**消息方向**：设备 → 服务器
+
+```json
+{
+  "id": "auth_1704067200000_123",
+  "method": "auth",
+  "params": {
+    "clientId": "device_001",
+    "username": "productKey_deviceName",
+    "password": "设备密码"
+  },
+  "timestamp": 1704067200000
+}
+```
+
+**认证参数说明：**
+
+| 字段名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| clientId | String | 是 | 客户端唯一标识，用于连接管理 |
+| username | String | 是 | 设备用户名，格式为 `productKey_deviceName` |
+| password | String | 是 | 设备密码，在设备管理平台配置 |
+
+#### 认证响应格式
+**消息方向**：服务器 → 设备
+
+**认证成功响应：**
+```json
+{
+  "id": "response_auth_1704067200000_123",
+  "method": "auth",
+  "data": {
+    "success": true,
+    "message": "认证成功"
+  },
+  "code": 0,
+  "msg": "认证成功",
+  "timestamp": 1704067200001
+}
+```
+
+**认证失败响应：**
+```json
+{
+  "id": "response_auth_1704067200000_123", 
+  "method": "auth",
+  "data": {
+    "success": false,
+    "message": "认证失败：用户名或密码错误"
+  },
+  "code": 401,
+  "msg": "认证失败",
+  "timestamp": 1704067200001
+}
+```
+
+### 3.2 属性数据上报 (thing.property.post)
+
+**消息方向**：设备 → 服务器
+
+**示例：温度传感器数据上报**
+```json
+{
+  "id": "property_1704067200000_456",
+  "method": "thing.property.post",
+  "params": {
+    "temperature": 25.5,
+    "humidity": 60.2,
+    "pressure": 1013.25,
+    "battery": 85,
+    "signal_strength": -65
+  },
+  "timestamp": 1704067200000
+}
+```
+
+### 3.3 设备状态更新 (thing.state.update)
+
+**消息方向**：设备 → 服务器
+
+**示例：心跳请求**
+```json
+{
+  "id": "heartbeat_1704067200000_321",
+  "method": "thing.state.update",
+  "params": {
+    "state": "online",
+    "uptime": 86400,
+    "memory_usage": 65.2,
+    "cpu_usage": 12.8
+  },
+  "timestamp": 1704067200000
+}
+```
+
+## 4. 编解码器标识
+
+```java
+public static final String TYPE = "TCP_JSON";
+```
+
+## 5. 协议优势
+
+- **开发效率高**：JSON 格式，开发和调试简单
+- **跨语言支持**：所有主流语言都支持 JSON
+- **可读性优秀**：可以直接查看消息内容
+- **扩展性强**：可以轻松添加新字段
+- **安全性高**：移除 deviceId 字段，防止伪造攻击
+
+## 6. 与二进制协议对比
+
+| 特性 | JSON协议 | 二进制协议 |
+|------|----------|------------|
+| 开发难度 | 低 | 高 |
+| 调试难度 | 低 | 高 |
+| 可读性 | 优秀 | 差 |
+| 数据大小 | 中等 | 小（节省30-50%） |
+| 解析性能 | 中等 | 高 |
+| 学习成本 | 低 | 高 |
+
+**推荐场景**：
+- ✅ **开发调试阶段**：调试友好，开发效率高
+- ✅ **快速原型开发**：实现简单，快速迭代
+- ✅ **多语言集成**：广泛的语言支持
+- ❌ **高频数据传输**：建议使用二进制协议
+- ❌ **带宽受限环境**：建议使用二进制协议