@thejrsoft/subway-protocol 1.3.0

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

@@ -0,0 +1,332 @@
+# Simple 命令执行流程详解
+
+## 概述
+
+Simple 类型命令是 JRSoft Subway 协议中最基本的命令类型，遵循"一次请求，一次响应"的模式。
+
+## 执行流程
+
+### 标准执行流程
+
+所有设备都通过 Edge 接入系统，Gateway 负责路由到正确的 Edge：
+
+```
+┌─────────┐    ┌─────────┐    ┌──────┐    ┌────────┐
+│ Backend │    │ Gateway │    │ Edge │    │ Device │
+└────┬────┘    └────┬────┘    └───┬──┘    └────┬───┘
+     │              │              │            │
+     │ 1. command   │              │            │
+     │ (edge01:td01)│              │            │
+     ├─────────────►│              │            │
+     │              │              │            │
+     │              │ 2. route to  │            │
+     │              │    edge01    │            │
+     │              ├─────────────►│            │
+     │              │              │            │
+     │              │              │ 3. forward │
+     │              │              │   to td01  │
+     │              │              ├───────────►│
+     │              │              │            │
+     │              │              │            │ 4. execute
+     │              │              │            ├─┐
+     │              │              │            │ │
+     │              │              │            │◄┘
+     │              │              │            │
+     │              │              │ 5. response│
+     │              │              │◄───────────┤
+     │              │              │            │
+     │              │ 6. response  │            │
+     │              │◄─────────────┤            │
+     │              │              │            │
+     │ 7. response  │              │            │
+     │◄─────────────┤              │            │
+     │              │              │            │
+```
+
+## 关键组件职责
+
+### Backend
+- 发起命令请求
+- 指定目标设备（targetClientId = deviceId）
+- 设置超时和优先级
+- 处理命令响应
+
+### Gateway（中央路由器）
+- **路由查找**：根据设备ID查找对应的Edge节点
+- **连接管理**：维护与多个 Edge 的WebSocket连接
+- **超时控制**：监控命令执行超时
+- **响应路由**：根据 requestRef 将响应路由回发起方
+- **回调处理**：如配置了 callback URL，推送响应
+- **负载均衡**：可选，在多个 Edge 之间分配负载
+
+### Edge（设备接入点）
+- **设备管理**：管理本地多个设备的连接
+- **本地路由**：根据 targetClientId（设备ID）路由到设备
+- **协议转换**：可选，将WebSocket协议转换为设备协议
+- **状态监控**：监控本地设备健康状态
+- **断线重连**：处理设备的连接恢复
+
+### Device
+- **命令执行**：执行具体的硬件操作
+- **响应生成**：生成执行结果
+- **错误处理**：处理执行异常
+- **状态上报**：定期向 Edge 汇报状态
+
+## 消息格式
+
+### 命令请求
+```json
+{
+  "type": "COMMAND",
+  "requestRef": "cmd-${timestamp}-${random}",  // 唯一标识
+  "targetClientId": "td-01",              // 设备ID
+  "command": {
+    "commandType": "SIMPLE",
+    "commandCode": "SET_COLOR",
+    "deviceType": "pillar",
+    "deviceId": 1,
+    "operationType": "WRITE",
+    "parameters": {
+      "color": "#FF0000"
+    }
+  },
+  "priority": "NORMAL",     // low, normal, high, critical
+  "timeout": 10000,         // 毫秒
+  "callback": "http://backend/api/callback/cmd-123",  // 可选
+  "timestamp": "2024-01-20T10:00:00Z",
+  "version": "1.0"
+}
+```
+
+### 命令响应
+```json
+{
+  "type": "COMMAND_RESPONSE",
+  "requestRef": "cmd-${timestamp}-${random}",  // 与请求相同
+  "status": "COMPLETED",                       // 执行状态
+  "result": {
+    "deviceType": "pillar",
+    "deviceId": 1,
+    "commandCode": "SET_COLOR",
+    "operationType": "WRITE",
+    "data": {
+      // 成功时返回执行结果
+      "previousColor": "#00FF00",
+      "currentColor": "#FF0000"
+    }
+  },
+  "executionTime": 150,  // 执行耗时（毫秒）
+  "timestamp": "2024-01-20T10:00:00.150Z",
+  "version": "1.0"
+}
+```
+
+## targetClientId 格式
+
+```
+格式: 直接使用设备ID
+示例: 
+- "td-01" - 设备ID，Gateway自动查找对应的Edge
+- "screen-05" - 5号屏幕设备
+- "pillar-123" - 123号光柱设备
+```
+
+**路由流程：**
+1. Gateway 收到 targetClientId = "td-01"，查找路由表
+2. Gateway 发现 td-01 在 edge-001 节点下
+3. Gateway 将命令路由到 edge-001
+4. Edge 收到命令，targetClientId 就是设备ID
+5. Edge 将命令转发到设备 td-01
+
+## 超时处理
+
+1. **Backend设置超时**：在命令中指定 timeout 字段
+2. **Gateway监控超时**：
+   ```javascript
+   setTimeout(() => {
+     if (!hasResponse) {
+       sendTimeoutResponse(requestRef);
+     }
+   }, command.timeout);
+   ```
+3. **超时响应**：
+   ```json
+   {
+     "type": "COMMAND_RESPONSE",
+     "requestRef": "cmd-123",
+     "status": "TIMEOUT",
+     "log": {
+       "level": "ERROR",
+       "message": "Command execution timeout",
+       "code": "COMMAND_TIMEOUT",
+       "data": {
+         "timeout": 10000,
+         "elapsed": 10500
+       }
+     }
+   }
+   ```
+
+## 错误处理
+
+### Edge 不存在
+```json
+{
+  "type": "ERROR",
+  "requestRef": "cmd-123",
+  "code": "EDGE_NOT_FOUND",
+  "message": "Target edge edge-999 not found",
+  "details": {
+    "targetClientId": "td-01",
+    "requestedEdge": "edge-999",
+    "availableEdges": ["edge-001", "edge-002"]
+  }
+}
+```
+
+### 设备离线
+```json
+{
+  "type": "COMMAND_RESPONSE",
+  "requestRef": "cmd-123",
+  "status": "FAILED",
+  "log": {
+    "level": "ERROR",
+    "message": "Device td-01 is offline at edge-001",
+    "code": "DEVICE_OFFLINE",
+    "data": {
+      "edgeId": "edge-001",
+      "deviceId": "td-01",
+      "lastSeen": "2024-01-20T09:55:00Z"
+    }
+  }
+}
+```
+
+### 执行失败
+```json
+{
+  "type": "COMMAND_RESPONSE",
+  "requestRef": "cmd-123",
+  "status": "FAILED",
+  "result": {
+    "deviceType": "pillar",
+    "deviceId": 1,
+    "commandCode": "SET_COLOR",
+    "operationType": "WRITE",
+    "data": {
+      "Uerror": "Hardware malfunction",
+      "errorCode": "HW_ERROR_001"
+    }
+  }
+}
+```
+
+## 最佳实践
+
+### 1. RequestRef 生成
+```javascript
+function generateRequestRef(prefix = 'cmd') {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substr(2, 9);
+  return `${prefix}-${timestamp}-${random}`;
+}
+```
+
+### 2. 超时设置建议
+- 读操作：5-10秒
+- 写操作：10-30秒
+- 复杂操作：30-60秒
+
+### 3. 错误重试
+```javascript
+async function executeWithRetry(command, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const response = await sendCommand(command);
+      if (response.status === 'completed') {
+        return response;
+      }
+      
+      // 仅在特定错误时重试
+      if (!isRetryableError(response)) {
+        return response;
+      }
+    } catch (error) {
+      if (i === maxRetries - 1) throw error;
+    }
+    
+    // 指数退避
+    await sleep(Math.pow(2, i) * 1000);
+  }
+}
+```
+
+### 4. 设备端实现
+```javascript
+class DeviceHandler {
+  async handleCommand(message) {
+    // 只处理 simple 命令
+    if (message.command.commandType !== 'simple') {
+      throw new Error('Device only supports simple commands');
+    }
+    
+    try {
+      // 执行命令
+      const result = await this.executeCommand(message.command);
+      
+      // 返回成功响应
+      return {
+        type: 'command_response',
+        requestRef: message.requestRef,
+        status: 'completed',
+        result: {
+          deviceType: message.command.deviceType,
+          deviceId: message.command.deviceId,
+          commandCode: message.command.commandCode,
+          operationType: message.command.operationType,
+          data: result
+        },
+        executionTime: Date.now() - startTime,
+        timestamp: new Date().toISOString(),
+        version: '1.0'
+      };
+    } catch (error) {
+      // 返回错误响应
+      return {
+        type: 'command_response',
+        requestRef: message.requestRef,
+        status: 'failed',
+        result: {
+          deviceType: message.command.deviceType,
+          deviceId: message.command.deviceId,
+          commandCode: message.command.commandCode,
+          operationType: message.command.operationType,
+          data: {
+            error: error.message,
+            errorCode: error.code
+          }
+        },
+        log: {
+          level: 'error',
+          message: error.message,
+          code: error.code
+        },
+        timestamp: new Date().toISOString(),
+        version: '1.0'
+      };
+    }
+  }
+}
+```
+
+## 总结
+
+Simple 命令是整个协议的基础，具有以下特点：
+
+1. **简单直接**：一次请求，一次响应
+2. **路由透明**：Backend无需知道Edge拓扑，Gateway自动路由
+3. **错误处理完善**：超时、离线、执行失败都有明确处理
+4. **扩展性好**：通过 parameters 支持各种命令参数
+
+其他命令类型（Batch、Complex）最终都会分解为 Simple 命令执行，这保证了设备端实现的简单性。

package/docs/02-commands/typed-commands.md

@@ -0,0 +1,362 @@
+# 强类型命令系统
+
+## 概述
+
+强类型命令系统通过从 C# 模型自动生成 TypeScript 类型定义，实现端到端的类型安全。该系统提供编译时类型检查、智能提示和运行时验证，同时保持向后兼容性。
+
+## 架构设计
+
+### 分层架构
+
+```
+C# 模型定义 → TypeScript 类型生成 → WebSocket 协议集成
+```
+
+- **C# 模型层**：定义命令的业务逻辑和数据结构
+- **类型生成层**：自动将 C# 类型转换为 TypeScript 定义
+- **协议集成层**：将强类型集成到 WebSocket 协议中
+
+### 核心组件
+
+1. **命令类型定义** (`command-types.ts`)
+   - 所有强类型命令的 TypeScript 接口
+   - 命令代码到类型的映射
+   - 类型守卫函数
+
+2. **命令工厂** (`command-factory.ts`)
+   - 类型安全的命令创建函数
+   - 参数验证和默认值处理
+   - 通用工厂方法
+
+3. **类型验证器** (`CommandTypeValidator`)
+   - 运行时类型验证
+   - 详细的错误报告
+   - 可扩展的验证规则
+
+## 使用方法
+
+### 1. 基础使用
+
+```typescript
+import { 
+  createLedSwitchCommand, 
+  createBlockPlayCommand,
+  Priority 
+} from '@jrsoft/subway-protocol';
+
+// 创建 LED 开关命令
+const ledCommand = createLedSwitchCommand(
+  'led-req-001',      // requestRef
+  'td-01',            // targetClientId (设备ID)  
+  15,                 // deviceId (子硬件ID)
+  'ON',               // switch state
+  'write',            // operation type
+  {
+    priority: Priority.HIGH,
+    timeout: 5000,
+    callback: 'http://backend/api/callback'
+  }
+);
+
+// 创建区块播放命令
+const playCommand = createBlockPlayCommand(
+  'play-req-002',
+  'td-01',            // targetClientId (设备ID)
+  15,                 // deviceId (子硬件ID)
+  3,                  // blockNumber
+  'loop',             // playMode
+  'write',
+  { priority: Priority.NORMAL }
+);
+```
+
+### 2. 类型安全的优势
+
+```typescript
+// ✅ 强类型：编译时类型检查
+const command = createLedSwitchCommand(
+  'req-123',
+  'td-01', 
+  42,
+  'ON'  // 只能是 'ON' | 'OFF'
+);
+
+// ❌ 编译错误：类型不匹配
+const badCommand = createLedSwitchCommand(
+  'req-123',
+  'td-01',
+  42,
+  'INVALID'  // Error: Argument of type '"INVALID"' is not assignable
+);
+
+// IDE 智能提示
+command.parameters.switch // 自动提示: 'ON' | 'OFF'
+command.deviceType        // 自动提示: 'pillar'
+command.operationType     // 自动提示: 'read' | 'write'
+```
+
+### 3. 运行时验证
+
+```typescript
+import { CommandTypeValidator } from '@jrsoft/subway-protocol';
+
+// 验证命令
+const validation = CommandTypeValidator.validateCommand(command);
+if (!validation.valid) {
+  console.error('Command validation failed:', validation.errors);
+}
+
+// 验证特定命令类型
+if (CommandTypeValidator.isLedSwitchCommand(command)) {
+  // TypeScript 知道这是 LedSwitchCommand
+  console.log(command.parameters.switch); // 'ON' | 'OFF'
+}
+```
+
+### 4. 批量命令支持
+
+```typescript
+import { createBatchCommand } from '@jrsoft/subway-protocol';
+
+// 创建批量 LED 控制命令
+const batchLedCommand = createBatchCommand(
+  'batch-req-001',
+  {
+    commandCode: 'LedSwitch',
+    deviceType: 'pillar',
+    operationType: 'write',
+    parameters: {
+      switch: 'ON',
+      targets: '1-10,30-40',  // 批量目标
+      batch: true
+    }
+  },
+  {
+    priority: Priority.HIGH,
+    timeout: 30000
+  }
+);
+```
+
+### 5. 泛型工厂方法
+
+```typescript
+import { 
+  TypedCommandFactory,
+  CommandTypeMap 
+} from '@jrsoft/subway-protocol';
+
+// 使用泛型工厂创建任意类型的命令
+const typedCommand = TypedCommandFactory.createTypedCommandMessage(
+  'generic-req-003',
+  'device-01',
+  'BlockPlay',  // 命令代码作为类型参数
+  {
+    blockNumber: 5,
+    playMode: 'sequence'
+  },
+  { priority: Priority.LOW }
+);
+
+// TypeScript 自动推断返回类型为 CommandMessage<BlockPlayCommand>
+```
+
+## 支持的命令类型
+
+此处省略
+
+完整的命令列表请参考 [API 文档](../06-reference/api.md)。
+
+## 与通用命令的互操作
+
+### 向后兼容
+
+```typescript
+// 强类型命令仍然是标准的 Command
+export type Command = SpecificCommand | GenericCommand;
+
+// 可以混合使用
+const commands: Command[] = [
+  createLedSwitchCommand(...),  // 强类型
+  {                             // 通用类型
+    commandCode: 'CUSTOM_COMMAND',
+    deviceType: 'custom',
+    operationType: 'write',
+    parameters: { customParam: 'value' }
+  }
+];
+```
+
+### 类型转换
+
+```typescript
+import { CommandTypeConverter } from '@jrsoft/subway-protocol';
+
+// 将通用命令转换为强类型（如果可能）
+const genericCommand = {
+  commandCode: 'LedSwitch',
+  parameters: { switch: 'ON' }
+};
+
+const specificCommand = CommandTypeConverter.toSpecificCommand(genericCommand);
+if (specificCommand && CommandTypeValidator.isLedSwitchCommand(specificCommand)) {
+  // 现在有完整的类型信息
+}
+```
+
+## 最佳实践
+
+### 1. 优先使用强类型
+
+```typescript
+// ✅ 推荐：使用强类型命令工厂
+const command = createLedSwitchCommand(...);
+
+// ❌ 避免：手动构造命令对象
+const command = {
+  commandCode: 'LedSwitch',
+  parameters: { switch: 'ON' }
+};
+```
+
+### 2. 统一错误处理
+
+```typescript
+try {
+  const command = createLedSwitchCommand(...);
+  const validation = CommandTypeValidator.validateCommand(command);
+  
+  if (!validation.valid) {
+    throw new Error(`Invalid command: ${validation.errors.join(', ')}`);
+  }
+  
+  // 发送命令
+} catch (error) {
+  console.error('Command creation failed:', error);
+}
+```
+
+### 3. 类型守卫的使用
+
+```typescript
+function handleCommand(command: Command) {
+  if (CommandTypeValidator.isLedSwitchCommand(command)) {
+    // 处理 LED 开关命令
+    console.log(`Switching LED to ${command.parameters.switch}`);
+  } else if (CommandTypeValidator.isBlockPlayCommand(command)) {
+    // 处理区块播放命令
+    console.log(`Playing block ${command.parameters.blockNumber}`);
+  } else {
+    // 处理通用命令
+    console.log(`Generic command: ${command.commandCode}`);
+  }
+}
+```
+
+### 4. 扩展自定义命令
+
+```typescript
+// 定义自定义命令接口
+interface CustomCommand extends BaseSpecificCommand {
+  commandCode: 'CustomCommand';
+  parameters: {
+    customField: string;
+    customValue: number;
+  };
+}
+
+// 添加到命令映射
+declare module '@jrsoft/subway-protocol' {
+  interface CommandTypeMap {
+    CustomCommand: CustomCommand;
+  }
+}
+
+// 创建自定义工厂函数
+export function createCustomCommand(
+  requestRef: string,
+  targetClientId: string,
+  customField: string,
+  customValue: number,
+  options?: CommandOptions
+): CommandMessage<CustomCommand> {
+  return TypedCommandFactory.createTypedCommandMessage(
+    requestRef,
+    targetClientId,
+    'CustomCommand',
+    { customField, customValue },
+    options
+  );
+}
+```
+
+## 工具支持
+
+### TypeScript 配置
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "strictNullChecks": true,
+    "noImplicitAny": true
+  }
+}
+```
+
+### ESLint 规则
+
+```json
+{
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "Uerror",
+    "@typescript-eslint/explicit-function-return-type": "warn"
+  }
+}
+```
+
+## 迁移指南
+
+### 从通用命令迁移到强类型
+
+1. **识别使用的命令代码**
+   ```typescript
+   // 旧代码
+   const command = {
+     commandCode: 'LedSwitch',
+     parameters: { switch: 'ON' }
+   };
+   ```
+
+2. **使用对应的工厂函数**
+   ```typescript
+   // 新代码
+   const command = createLedSwitchCommand(
+     requestRef,
+     targetClientId,
+     deviceId,
+     'ON',
+     'write'
+   );
+   ```
+
+3. **更新类型注解**
+   ```typescript
+   // 旧代码
+   function handleCommand(command: any) { }
+   
+   // 新代码
+   function handleCommand(command: LedSwitchCommand) { }
+   ```
+
+## 总结
+
+强类型命令系统提供了：
+
+1. **编译时安全** - 在开发阶段捕获类型错误
+2. **更好的开发体验** - IDE 智能提示和自动补全
+3. **运行时验证** - 确保数据完整性
+4. **向后兼容** - 可以渐进式迁移
+5. **可扩展性** - 轻松添加新的命令类型
+
+这种设计既保证了类型安全，又保持了系统的灵活性，是现代 TypeScript 应用的最佳实践。