@thejrsoft/subway-protocol 1.3.0

package/docs/04-integration/gateway-guide.md

@@ -0,0 +1,180 @@
+# Gateway 集成指南
+
+## 概述
+
+本指南说明如何在 jrsoft-subway-gateway 中使用统一的 WebSocket 协议包。
+
+## 安装
+
+```bash
+cd jrsoft-subway-gateway
+npm install ../jrsoft-subway-protocol --save
+```
+
+## 使用方式
+
+### 1. 导入类型
+
+```typescript
+import { 
+  MessageType,
+  RegisterMessage,
+  CommandMessage,
+  MessageFactory,
+  MessageValidator,
+  // ... 其他类型
+} from '@jrsoft/subway-protocol';
+```
+
+### 2. 处理消息
+
+```typescript
+// 使用枚举判断消息类型
+switch (message.type) {
+  case MessageType.REGISTER:
+    handleRegister(message);
+    break;
+  case MessageType.COMMAND:
+    handleCommand(message);
+    break;
+  // ...
+}
+```
+
+### 3. 创建响应
+
+```typescript
+// 直接创建消息对象
+const response: RegisterAckMessage = {
+  type: MessageType.REGISTER_ACK,
+  clientId: message.clientId,
+  success: true,
+  timestamp: new Date().toISOString()
+};
+
+// 或使用消息工厂
+const command = MessageFactory.createCommandMessage(
+  requestRef,
+  clientId,
+  commandDetails,
+  { priority: Priority.HIGH }
+);
+```
+
+### 4. 验证消息
+
+```typescript
+if (!MessageValidator.validateCommandMessage(message)) {
+  throw new Error('Invalid command message');
+}
+```
+
+## Gateway 特有扩展
+
+Gateway 在协议包基础上扩展了以下类型：
+
+```typescript
+// 设备连接信息
+export interface DeviceConnection {
+  ws: WebSocket;
+  lastPing: number;
+  status: 'connected' | 'disconnecting' | 'reconnecting';
+  connectionTime: number;
+  reconnectAttempts: number;
+  metadata?: Record<string, unknown>;
+}
+
+// 设备映射
+export type DeviceMap = Map<string, DeviceConnection>;
+```
+
+## Edge 代理支持
+
+协议包内置了 Edge 代理支持，一个 Edge 节点可以管理一套或多套隧道媒体广告播放系统的设备端：
+
+```typescript
+// Edge 注册
+const edgeRegister: RegisterMessage = {
+  type: MessageType.REGISTER,
+  clientId: "edge-01",
+  clientType: ClientType.EDGE,
+  clientInfo: {
+    version: "1.0",
+    capabilities: ["device-proxy", "batch-command"]
+  }
+};
+
+// Edge 转发命令到具体设备
+const edgeCommand: EdgeDeviceMessage = {
+  type: MessageType.COMMAND,
+  edgeId: "edge-station-01",
+  targetDeviceId: "device-123",
+  command: { /* ... */ }
+};
+```
+
+### 进度更新处理
+
+Gateway 需要正确处理和转发进度更新消息：
+
+```typescript
+import { 
+  isProgressUpdateMessage,
+  ProgressStatus,
+  ProgressPhase 
+} from '@jrsoft/subway-protocol';
+
+// 处理进度更新
+function handleProgressUpdate(message: ProgressUpdateMessage, clientId: string) {
+  // 记录日志
+  if (message.log) {
+    logger.log(message.log.level, 
+      `[${clientId}] ${message.log.code || ''}: ${message.message}`,
+      message.log.data
+    );
+  }
+  
+  // 根据状态处理
+  switch (message.status) {
+    case ProgressStatus.FAILED:
+      // 记录失败信息
+      errorTracker.record(clientId, message.requestRef, message.log);
+      break;
+      
+    case ProgressStatus.COMPLETED:
+      // 更新完成统计
+      metrics.recordCompletion(clientId, message.phase, message.timestamp);
+      break;
+      
+    case ProgressStatus.PAUSED:
+    case ProgressStatus.CANCELLED:
+      // 通知相关方
+      notifyStatusChange(clientId, message.requestRef, message.status);
+      break;
+  }
+  
+  // 转发到后端
+  forwardToBackend(message, clientId);
+}
+
+// 进度汇总
+function aggregateProgress(requestRef: string): ProgressSummary {
+  const updates = progressCache.get(requestRef) || [];
+  
+  return {
+    totalProgress: calculateOverallProgress(updates),
+    currentPhase: getCurrentPhase(updates),
+    status: getOverallStatus(updates),
+    logs: extractLogs(updates),
+    deviceCommands: extractDeviceCommands(updates)
+  };
+}
+```
+
+## 注意事项
+
+1. **使用 v1.0 标准协议** - 统一的协议定义
+2. **使用枚举类型** - 避免硬编码字符串
+3. **时间戳格式** - 使用 ISO 8601 格式
+4. **消息验证** - 使用内置验证器
+5. **类型安全** - 充分利用 TypeScript 类型系统

package/docs/04-integration/migration-guide.md

@@ -0,0 +1,226 @@
+# WebSocket 协议统一迁移指南
+
+## 概述
+
+本指南帮助将 Gateway 和 Backend 迁移到统一的 WebSocket 协议（v2.0）。新协议设计为向后兼容，支持渐进式升级。
+
+## 主要变更
+
+### 1. 注册消息的统一
+
+**当前差异:**
+- Gateway: 只需要 `type` 和 `clientId`
+- Backend: 需要 `clientType`、`clientInfo` 等额外字段
+
+**统一方案:**
+```typescript
+// 简单注册（向后兼容）
+{
+  "type": "REGISTER",
+  "clientId": "device001"
+}
+
+// 完整注册（新协议）
+{
+  "type": "REGISTER",
+  "clientId": "backend-server",
+  "clientType": "BACKEND",
+  "clientInfo": {
+    "version": "1.0.0",
+    "platform": "nodejs",
+    "capabilities": ["command", "program"]
+  },
+  "timestamp": "2024-01-01T00:00:00Z",
+  "version": "2.0"
+}
+```
+
+### 2. 命令状态的统一
+
+**当前差异:**
+- Gateway: 包含 `in_progress` 状态
+- Backend: 不包含 `in_progress` 状态
+
+**统一方案:**
+- 所有状态都被支持，组件可选择性使用
+
+## 迁移步骤
+
+### 第一阶段：添加协议包依赖
+
+1. **安装共享协议包**
+```bash
+# 在 Gateway 项目
+cd jrsoft-subway-gateway
+npm install ../jrsoft-subway-protocol
+
+# 在 Backend 项目  
+cd jrsoft-subway-backend
+npm install ../jrsoft-subway-protocol
+
+# 在 Edge 项目
+cd jrsoft-subway-edge
+npm install ../jrsoft-subway-protocol
+```
+
+### 第二阶段：更新 Gateway（保持向后兼容）
+
+1. **更新消息处理器以支持扩展字段**
+```typescript
+// src/ws/websocket-handler.ts
+import { RegisterMessage, MessageValidator } from '@jrsoft/subway-protocol';
+
+private handleRegister(ws: WebSocket, message: RegisterMessage) {
+  const { clientId, clientType, clientInfo } = message;
+  
+  // 存储扩展信息（如果提供）
+  const client = {
+    ws,
+    clientId,
+    clientType: clientType || 'device',  // 默认为device
+    clientInfo: clientInfo || {},
+    registeredAt: new Date()
+  };
+  
+  this.clients.set(clientId, client);
+  
+  // 发送确认，包含sessionId
+  const ack = {
+    type: 'register_ack',
+    clientId,
+    success: true,
+    sessionId: generateSessionId(),
+    timestamp: new Date().toISOString()
+  };
+  
+  ws.send(JSON.stringify(ack));
+}
+```
+
+2. **添加协议版本协商**
+```typescript
+// 在连接建立时检查协议版本
+ws.on('message', (data) => {
+  const message = JSON.parse(data.toString());
+  
+  // 记录客户端协议版本
+  if (message.version) {
+    ws.protocolVersion = message.version;
+  }
+  
+  // 处理消息...
+});
+```
+
+### 第三阶段：更新 Backend（使用新协议）
+
+1. **使用共享协议定义**
+```typescript
+// src/services/gateway.service.ts
+import { 
+  MessageFactory, 
+  MessageType, 
+  ClientType 
+} from '@jrsoft/subway-protocol';
+
+private registerWithGateway() {
+  const registerMsg = MessageFactory.createRegisterMessage(
+    this.clientId,
+    ClientType.BACKEND,
+    {
+      version: '1.0.0',
+      platform: 'nodejs',
+      capabilities: ['command', 'program']
+    }
+  );
+  
+  this.ws.send(JSON.stringify(registerMsg));
+}
+```
+
+2. **处理简化的响应**
+```typescript
+private handleMessage(data: any) {
+  const message = JSON.parse(data);
+  
+  switch (message.type) {
+    case 'register_ack':
+      // 检查是否有sessionId（新协议）
+      if (message.sessionId) {
+        this.sessionId = message.sessionId;
+      }
+      break;
+    // ...
+  }
+}
+```
+
+### 第四阶段：测试和验证
+
+1. **创建协议兼容性测试**
+```typescript
+// test/protocol-compatibility.test.ts
+describe('Protocol Compatibility', () => {
+  it('should handle v1.0 simple registration', async () => {
+    const msg = { type: 'register', clientId: 'test' };
+    // 验证Gateway能处理
+  });
+  
+  it('should handle v2.0 full registration', async () => {
+    const msg = MessageFactory.createRegisterMessage(
+      'test',
+      ClientType.BACKEND,
+      { version: '1.0.0' }
+    );
+    // 验证Gateway能处理
+  });
+});
+```
+
+## 协议实现要求
+
+1. **支持两种注册格式**
+   - 简单格式：仅 `type` 和 `clientId`
+   - 完整格式：包含所有扩展字段
+
+2. **使用统一的消息类型**
+   - 使用 MessageType 枚举确保类型安全
+   - 避免硬编码字符串
+
+3. **处理可选字段**
+   - `timestamp`、`version` 等字段为可选
+   - 缺失时使用合理的默认值
+
+## 监控和回滚计划
+
+1. **添加协议版本监控**
+```typescript
+// 记录每个连接的协议版本
+logger.info('Client connected', {
+  clientId,
+  protocolVersion: message.version || '1.0',
+  clientType: message.clientType || 'unknown'
+});
+```
+
+2. **准备回滚脚本**
+   - 保留旧的协议处理代码
+   - 通过特性开关控制新协议启用
+
+## 时间表
+
+- **第1周**: 部署更新的 Gateway（向后兼容）
+- **第2周**: 逐步升级 Backend 使用新协议
+- **第3周**: 升级 Edge 和其他客户端
+- **第4周**: 监控和优化
+
+## 常见问题
+
+**Q: 旧版本客户端会受影响吗？**
+A: 不会。新协议完全向后兼容，旧客户端可继续使用简单注册。
+
+**Q: 如何知道客户端使用的协议版本？**
+A: 检查消息中的 `version` 字段，缺失则为 v1.0。
+
+**Q: 性能会受影响吗？**
+A: 几乎没有影响。额外字段是可选的，不会增加必需的网络开销。

package/docs/05-examples/README.md

@@ -0,0 +1,141 @@
+# 示例文档
+
+本目录包含 JRSoft Subway 协议的各种使用示例和代码片段。
+
+## 📚 文档列表
+
+### [命令示例](./command-examples.md)
+各种命令类型的完整示例：
+- Simple 命令示例
+- Batch 命令示例
+- Complex 命令示例
+- 强类型命令示例
+
+### [流程示例](./flow-examples.md)
+完整的业务流程示例：
+- 设备控制流程
+- 批量操作流程
+- 健康检查流程
+- 节目上传流程
+
+### [代码片段](./code-snippets.md)
+常用的代码片段：
+- 连接管理
+- 错误处理
+- 消息验证
+- 性能优化
+
+## 🚀 快速查找
+
+### 按功能分类
+
+#### 设备控制
+- [LED 开关控制](#led-控制)
+- [亮度调节](#亮度调节)
+- [颜色设置](#颜色设置)
+- [播放控制](#播放控制)
+
+#### 批量操作
+- [批量设置颜色](#批量颜色设置)
+- [批量开关控制](#批量开关)
+- [批量状态查询](#批量查询)
+
+#### 系统管理
+- [健康检查](#健康检查)
+- [配置更新](#配置更新)
+- [日志收集](#日志收集)
+
+## 💡 使用提示
+
+1. **复制粘贴友好** - 所有示例都可以直接复制使用
+2. **完整可运行** - 每个示例都包含必要的导入和配置
+3. **注释详细** - 关键代码都有详细注释
+4. **错误处理** - 包含错误处理的最佳实践
+
+## 📋 示例模板
+
+### TypeScript/JavaScript
+
+```typescript
+// 导入必要的模块
+import { 
+  createLedSwitchCommand,
+  GatewayClient,
+  Priority 
+} from '@jrsoft/subway-protocol';
+
+// 创建客户端
+const client = new GatewayClient('ws://localhost:18081', 'backend-001');
+
+// 连接并发送命令
+async function example() {
+  try {
+    await client.connect();
+    
+    const command = createLedSwitchCommand(
+      'req-001',
+      'td-01',
+      1,
+      'ON',
+      'write'
+    );
+    
+    const response = await client.sendCommand(command);
+    console.log('Response:', response);
+    
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+```
+
+### Python
+
+```python
+import asyncio
+import websockets
+from datetime import datetime
+
+async def send_command():
+    async with websockets.connect('ws://localhost:18081') as websocket:
+        # 注册
+        await websocket.send(json.dumps({
+            "type": "REGISTER",
+            "clientId": "backend-001",
+            "clientType": "BACKEND",
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "version": "1.0"
+        }))
+        
+        # 发送命令
+        command = {
+            "type": "COMMAND",
+            "requestRef": "cmd-001",
+            "targetClientId": "td-01",
+            "command": {
+                "commandType": "SIMPLE",
+                "commandCode": "LedSwitch",
+                "deviceType": "pillar",
+                "deviceId": 1,
+                "operationType": "WRITE",
+                "parameters": {"switch": "ON"}
+            },
+            "priority": "NORMAL",
+            "timeout": 5000,
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "version": "1.0"
+        }
+        
+        await websocket.send(json.dumps(command))
+        
+        # 接收响应
+        response = await websocket.recv()
+        print(f"Response: {response}")
+```
+
+## 🔗 相关资源
+
+- [协议规范](../01-protocol/) - 了解协议细节
+- [命令系统](../02-commands/) - 了解命令类型
+- [API 参考](../06-reference/api.md) - 完整的 API 文档
+- [示例代码仓库](../../examples/) - 完整的示例项目