@thejrsoft/subway-protocol 1.3.0

package/docs/02-commands/README.md

@@ -0,0 +1,56 @@
+# 命令系统文档
+
+本目录包含 JRSoft Subway 协议的命令系统相关文档。
+
+## 📚 文档列表
+
+### [Simple 命令](./simple-command.md)
+点对点的简单命令：
+- 快速执行的单一操作
+- 一次请求，一次响应
+- 适用于开关控制、参数读写等
+- 完整的路由流程和错误处理
+
+### [Batch 命令](./batch-command.md)
+批量控制命令：
+- 向同一设备的多个子硬件发送相同命令
+- 通过 progress_update 报告进度
+- 支持范围语法（如 "1-10,30-40"）
+- 适用于批量设置光柱颜色、屏幕内容等
+
+### [Complex 命令](./complex-command.md)
+复杂交互命令：
+- 支持多次响应的长时间运行命令
+- 通过 progress_update 持续反馈
+- 适用于健康检查、数据导出、日志收集等
+- 设备端可自主控制响应节奏
+
+### [强类型命令](./typed-commands.md)
+基于 C# 模型的类型安全命令：
+- 从 C# 模型自动生成 TypeScript 类型
+- 编译时类型检查
+- IntelliSense 支持
+- 运行时验证
+
+## 🎯 命令类型对比
+
+| 特性 | Simple | Batch | Complex |
+|------|--------|-------|---------|
+| 响应次数 | 1次 | 多次(进度+结果) | 多次(进度+结果) |
+| 执行时间 | 短(秒级) | 中等(分钟级) | 长(分钟到小时) |
+| 适用场景 | 单一操作 | 批量操作 | 复杂任务 |
+| 进度反馈 | 无 | 有 | 有 |
+| 实现复杂度 | 低 | 中 | 中高 |
+
+## 🚀 快速选择指南
+
+- **需要控制单个设备？** → 使用 [Simple 命令](./simple-command.md)
+- **需要批量控制多个子硬件？** → 使用 [Batch 命令](./batch-command.md)
+- **需要执行长时间任务并获取进度？** → 使用 [Complex 命令](./complex-command.md)
+- **需要类型安全和编译时检查？** → 使用 [强类型命令](./typed-commands.md)
+
+## 🔗 相关文档
+
+- [协议规范](../01-protocol/) - 了解底层协议
+- [示例代码](../05-examples/) - 查看实际使用示例
+- [API 参考](../06-reference/api.md) - 详细的 API 文档

package/docs/02-commands/batch-command.md

@@ -0,0 +1,435 @@
+# 批量命令详解
+
+## 概述
+
+批量命令用于控制同一设备内的多个子硬件（如光柱1-480）。为了提供更好的用户体验和实时反馈，批量命令采用与 Complex 命令和程序上传相同的执行模式：通过 progress_update 报告进度，最后返回汇总响应。
+
+## 核心理念
+
+批量命令是针对同一设备内的多个子硬件（如光柱1-480）执行相同操作。设备端负责解析批量目标并执行，通过 progress_update 报告每个子硬件的执行进度。
+
+## 重要限制
+
+⚠️ **批量命令仅适用于同一类型的子硬件**：
+- ✅ 可以：向编号1-20的光柱发送相同的颜色设置命令
+- ✅ 可以：向编号1-5的显示屏发送相同的内容更新命令  
+- ❌ 不可以：在同一批量命令中混合光柱和显示屏
+- ❌ 不可以：在同一批量命令中混合不同型号的硬件
+
+## 执行流程
+
+```
+Backend            Gateway              Edge              Device
+   |                  |                   |                  |
+   |  Batch Command   |                   |                  |
+   |  (targets:"1-10")|                   |                  |
+   |----------------->|                   |                  |
+   |                  |                   |                  |
+   |                  | Route to Edge     |                  |
+   |                  |------------------>|                  |
+   |                  |                   |                  |
+   |                  |                   | Device内部处理    |
+   |                  |                   |----------------->|
+   |                  |                   |                  | 执行子硬件1
+   |                  |                   |                  |
+   |                  |                   | progress_update  |
+   |                  |                   | (子硬件1)        |
+   |                  |                   |<-----------------|
+   |                  |                   |                  |
+   |                  | progress_update   |                  |
+   | progress_update  |<------------------|                  |
+   | (子硬件1完成)    |                   |                  |
+   |<-----------------|                   |                  |
+   |                  |                   |                  | 执行子硬件2
+   |                  |                   |                  |
+   |                  |                   | progress_update  |
+   |                  |                   | (子硬件2)        |
+   |                  |                   |<-----------------|
+   |                  |                   |                  |
+   |                  | progress_update   |                  |
+   | progress_update  |<------------------|                  |
+   | (子硬件2完成)    |                   |                  |
+   |<-----------------|                   |                  |
+   |                  |                   |                  |
+   |                  |                   |      ...         |
+   |                  |                   |                  | 执行子硬件10
+   |                  |                   |                  |
+   |                  |                   | command_response |
+   |                  |                   | (全部完成)       |
+   |                  |                   |<-----------------|
+   |                  |                   |                  |
+   |                  | command_response  |                  |
+   | command_response |<------------------|                  |
+   | (summary)        |                   |                  |
+   |<-----------------|                   |                  |
+```
+
+**注意**：批量命令是发送给同一个设备，由该设备内部处理多个子硬件的操作。
+
+## 应用场景
+
+### 典型硬件布局
+
+```
+隧道媒体广告设备端 (TC-01)
+├─ 光柱系统 (1-480编号)
+│  ├─ 光柱 001 ～ 020  (区域A)
+│  ├─ 光柱 021 ～ 040  (区域B)
+│  ├─ 光柱 041 ～ 060  (区域C)
+│  │  ...
+│  └─ 光柱 461 ～ 480  (区域Z)
+├─ 同步器 (1编号)
+├─ 测速器 (1-5编号)
+└─ 通讯板 (1-10编号)
+```
+
+## 范围语法
+
+批量命令支持灵活的范围语法来指定目标子硬件：
+
+### 基本格式
+
+- **单个目标**: `"5"` - 仅目标5
+- **连续范围**: `"1-10"` - 目标1到10
+- **离散目标**: `"1,3,5,7"` - 目标1、3、5、7
+- **混合模式**: `"1-10,30-40,51,52,53,54"` - 组合使用
+- **全部目标**: `"0"`  - 所有子硬件
+
+### 语法示例
+
+```javascript
+// 范围解析示例
+"1-5"          → [1, 2, 3, 4, 5]
+"1,3,5"        → [1, 3, 5]
+"1-3,7-9"      → [1, 2, 3, 7, 8, 9]
+"1-100,200-300" → [1...100, 200...300]
+"0"            → [所有可用设备]
+```
+
+## 消息结构
+
+### 1. 批量命令请求（Backend → Gateway）
+
+```json
+{
+  "type": "COMMAND",
+  "requestRef": "batch-123",
+  "targetClientId": "td-01",  // 设备ID
+  "command": {
+    "commandType": "BATCH",
+    "commandCode": "SET_COLOR",
+    "deviceType": "pillar",
+    "deviceId": "1-10,30-40",  // 批量目标
+    "operationType": "WRITE",
+    "parameters": {
+      "color": "#FF0000"
+    }
+  },
+  "priority": "NORMAL",
+  "timeout": 60000
+}
+```
+
+### 2. Edge 转发批量命令到设备（Edge → Device）
+
+```json
+{
+  "type": "COMMAND",
+  "requestRef": "batch-123",
+  "targetClientId": "td-01",  // 设备ID
+  "command": {
+    "commandType": "BATCH",
+    "commandCode": "SET_COLOR",
+    "deviceType": "pillar",
+    "deviceId": "1-10,30-40",  // 子硬件范围
+    "operationType": "WRITE",
+    "parameters": {
+      "color": "#FF0000",
+      "targets": "1-10,30-40",  // 明确的目标列表
+      "Ubatch": true
+    }
+  },
+  "priority": "NORMAL",
+  "timeout": 60000
+}
+```
+
+### 3. 进度更新（Device → Edge → Gateway → Backend）
+
+```json
+{
+  "type": "PROGRESS_UPDATE",
+  "requestRef": "batch-123",
+  "status": "IN_PROGRESS",
+  "phase": "executing",
+  "progress": 10,  // 1/10 子硬件完成
+  "sourceType": "COMMAND",
+  "command": {
+    "commandType": "SIMPLE",
+    "commandCode": "SET_COLOR",
+    "deviceType": "pillar",
+    "deviceId": 1,  // 子硬件ID
+    "operationType": "WRITE",
+    "result": {
+      "previousColor": "#00FF00",
+      "currentColor": "#FF0000"
+    }
+  },
+  "log": {
+    "level": "INFO",
+    "message": "光柱 1 颜色设置成功"
+  },
+  "timestamp": "2024-01-20T10:00:01Z",
+  "version": "1.0"
+}
+```
+
+### 4. 最终响应（Device → Edge → Gateway → Backend）
+
+```json
+{
+  "type": "COMMAND_RESPONSE",
+  "requestRef": "batch-123",
+  "status": "COMPLETED",
+  "result": {
+    "deviceType": "pillar",
+    "deviceId": "1-10,30-40",
+    "commandCode": "SET_COLOR",
+    "operationType": "WRITE",
+    "data": {
+      "message": "批量设置颜色完成",
+      "color": "#FF0000",
+      "targetCount": 16,
+      "successCount": 15,
+      "failureCount": 1
+    }
+  },
+  "summary": {
+    "total": 16,
+    "successful": 15,
+    "Ufailed": 1,
+    "failedTargets": [35]
+  },
+  "executionTime": 5200,
+  "timestamp": "2024-01-20T10:00:05Z",
+  "version": "1.0"
+}
+```
+
+## 设备端实现指南
+
+### 基本实现模式
+
+```typescript
+class DeviceHandler {
+  async handleBatchCommand(message: CommandMessage) {
+    const { command } = message;
+    const targets = this.parseTargets(command.parameters.targets);
+    let completedCount = 0;
+    let successCount = 0;
+    let failedTargets = [];
+    
+    // 处理每个子硬件
+    for (const targetId of targets) {
+      try {
+        // 执行子硬件操作
+        const result = await this.executeOnSubHardware(targetId, command);
+        
+        completedCount++;
+        successCount++;
+        
+        // 发送进度更新
+        await this.sendProgressUpdate({
+          requestRef: message.requestRef,
+          phase: 'executing',
+          progress: (completedCount / targets.length) * 100,
+          command: {
+            commandType: 'simple',
+            commandCode: command.commandCode,
+            deviceType: command.deviceType,
+            deviceId: targetId,  // 子硬件ID
+            operationType: command.operationType,
+            result
+          },
+          log: {
+            level: 'info',
+            message: `子硬件 ${targetId} 执行成功`
+          }
+        });
+        
+      } catch (error) {
+        completedCount++;
+        failedTargets.push(targetId);
+        
+        // 发送错误进度
+        await this.sendProgressUpdate({
+          requestRef: message.requestRef,
+          phase: 'executing',
+          progress: (completedCount / targets.length) * 100,
+          command: {
+            commandType: 'simple',
+            commandCode: command.commandCode,
+            deviceType: command.deviceType,
+            deviceId: targetId,
+            operationType: command.operationType,
+            result: { error: error.message }
+          },
+          log: {
+            level: 'error',
+            message: `子硬件 ${targetId} 执行失败: ${error.message}`
+          }
+        });
+      }
+    }
+    
+    // 发送最终响应
+    return {
+      type: 'command_response',
+      requestRef: message.requestRef,
+      status: 'completed',
+      result: {
+        deviceType: command.deviceType,
+        deviceId: command.deviceId,
+        commandCode: command.commandCode,
+        operationType: command.operationType,
+        data: {
+          message: '批量命令执行完成',
+          targetCount: targets.length,
+          successCount,
+          failureCount: failedTargets.length
+        }
+      },
+      summary: {
+        total: targets.length,
+        successful: successCount,
+        failed: failedTargets.length,
+        failedTargets
+      }
+    };
+  }
+  
+  private parseTargets(targets: string | number[]): number[] {
+    if (Array.isArray(targets)) {
+      return targets;
+    }
+    
+    // 解析 "1-10,30-40,51,52" 格式
+    const result = [];
+    const parts = targets.split(',');
+    
+    for (const part of parts) {
+      if (part.includes('-')) {
+        const [start, end] = part.split('-').map(Number);
+        for (let i = start; i <= end; i++) {
+          result.push(i);
+        }
+      } else {
+        result.push(Number(part));
+      }
+    }
+    
+    return result;
+  }
+}
+```
+
+### 范围解析函数
+
+```typescript
+function parseRangeString(rangeStr: string): number[] {
+  // 特殊情况：0 或 * 表示全部
+  if (rangeStr === '0' || rangeStr === '*') {
+    return getAllAvailableTargets();
+  }
+  
+  const targets = new Set<number>();
+  const parts = rangeStr.split(',').map(s => s.trim());
+  
+  for (const part of parts) {
+    if (part.includes('-')) {
+      // 处理范围：1-10
+      const [start, end] = part.split('-').map(Number);
+      if (!isNaN(start) && !isNaN(end) && start <= end) {
+        for (let i = start; i <= end; i++) {
+          targets.add(i);
+        }
+      }
+    } else {
+      // 处理单个数字
+      const num = Number(part);
+      if (!isNaN(num)) {
+        targets.add(num);
+      }
+    }
+  }
+  
+  return Array.from(targets).sort((a, b) => a - b);
+}
+```
+
+## 最佳实践
+
+### 1. 进度报告策略
+
+- **合理的报告频率** - 避免过于频繁的进度更新
+- **关键节点报告** - 在开始、25%、50%、75%、完成时报告
+
+### 2. 错误处理
+
+- **失败继续** - 单个子硬件失败不应停止整个批量操作
+- **详细记录** - 记录每个失败的子硬件ID和原因
+- **部分成功** - 支持部分成功的场景
+
+### 3. 性能优化
+
+```typescript
+// 并行执行示例
+async function executeBatchParallel(targets: number[], command: Command) {
+  const batchSize = 10; // 每批处理10个
+  const results = [];
+  
+  for (let i = 0; i < targets.length; i += batchSize) {
+    const batch = targets.slice(i, i + batchSize);
+    const batchResults = await Promise.all(
+      batch.map(target => executeOnSubHardware(target, command))
+    );
+    results.push(...batchResults);
+    
+    // 报告批次进度
+    await reportProgress(((i + batch.length) / targets.length) * 100);
+  }
+  
+  return results;
+}
+```
+
+### 4. 超时处理
+
+```typescript
+// 设置合理的超时时间
+const timeoutMs = Math.max(
+  5000,  // 最小5秒
+  targets.length * 100  // 每个目标100ms
+);
+```
+
+## 与其他命令类型的对比
+
+| 特性 | Simple | Batch | Complex |
+|------|--------|-------|---------|
+| 目标数量 | 单个 | 多个子硬件 | 单个 |
+| 响应次数 | 1次 | 多次(进度+结果) | 多次(进度+结果) |
+| 进度反馈 | 无 | 有 | 有 |
+| 适用场景 | 单一操作 | 批量控制 | 复杂任务 |
+| 超时设置 | 较短 | 中等 | 较长 |
+
+## 设计优势
+
+1. **统一的执行模式** - 批量命令、Complex 命令、程序上传都使用 progress_update 报告进度
+2. **更好的可观察性** - 实时看到每个子硬件的执行状态
+3. **灵活的执行策略** - 设备可以控制子硬件的执行顺序
+4. **清晰的职责划分** - Gateway 路由、Edge 管理连接、Device 执行操作
+
+## 总结
+
+批量命令通过引入 progress_update 机制，为批量操作提供了实时的执行反馈。这种设计既保证了协议的灵活性，又维持了实现的简洁性，为用户提供了良好的体验。