@thejrsoft/subway-protocol 1.3.0

package/PROTOCOL_UTILS_USAGE.md

@@ -0,0 +1,278 @@
+# ProtocolUtils 使用指南
+
+## 概述
+
+`ProtocolUtils` 提供了一系列工具方法，用于处理协议中的枚举转换、消息类型判断和请求引用管理。
+
+## 功能分类
+
+### 1. 状态和枚举转换
+
+#### 基础转换方法
+
+```typescript
+import { ProtocolUtils, CommandStatus, Priority, ClientType } from '@jrsoft/subway-protocol';
+
+// CommandStatus 转换
+const status = ProtocolUtils.stringToStatus('completed'); // => CommandStatus.COMPLETED
+const statusStr = ProtocolUtils.statusToString(CommandStatus.FAILED); // => 'FAILED'
+
+// Priority 转换
+const priority = ProtocolUtils.priorityToEnum('high'); // => Priority.HIGH
+const priorityStr = ProtocolUtils.enumToPriority(Priority.CRITICAL); // => 'CRITICAL'
+
+// ClientType 转换
+const clientType = ProtocolUtils.clientTypeToEnum('device'); // => ClientType.DEVICE
+const typeStr = ProtocolUtils.enumToClientType(ClientType.BACKEND); // => 'BACKEND'
+```
+
+#### 安全转换方法（不抛出异常）
+
+```typescript
+// 返回枚举值或 null
+const status = ProtocolUtils.tryParseStatus('invalid'); // => null
+const priority = ProtocolUtils.tryParsePriority('HIGH'); // => Priority.HIGH
+const clientType = ProtocolUtils.tryParseClientType('backend'); // => ClientType.BACKEND
+```
+
+### 2. 消息类型判断
+
+增强的类型判断方法，不仅检查类型还验证结构：
+
+```typescript
+// 检查是否为命令消息
+if (ProtocolUtils.isCommandMessage(message)) {
+  // TypeScript 知道 message 是 CommandMessage
+  console.log(message.command.commandCode);
+}
+
+// 检查是否为进度更新
+if (ProtocolUtils.isProgressUpdate(message)) {
+  console.log(`Progress: ${message.progress}%`);
+}
+
+// 检查是否为程序消息
+if (ProtocolUtils.isProgramMessage(message)) {
+  console.log(message.command.parameters.programName);
+}
+```
+
+### 3. 请求引用管理
+
+#### 生成请求引用
+
+```typescript
+// 基础生成
+const ref1 = ProtocolUtils.generateRequestRef(); 
+// => "1703123456789-a1b2c3d4e"
+
+// 带前缀生成
+const ref2 = ProtocolUtils.generateRequestRef('backend');
+// => "backend-1703123456789-f5g6h7i8j"
+
+// 结构化生成
+const ref3 = ProtocolUtils.generateStructuredRequestRef('gateway', 'sendCommand');
+// => "gateway:sendcommand:1703123456789:k9l0m1"
+```
+
+#### 提取和解析请求引用
+
+```typescript
+// 从消息中提取请求引用
+const requestRef = ProtocolUtils.extractRequestRef(message);
+
+// 解析请求引用
+const parsed = ProtocolUtils.parseRequestRef('backend-1703123456789-a1b2c3d4e');
+// => { prefix: 'backend', timestamp: 1703123456789, random: 'a1b2c3d4e' }
+
+const structured = ProtocolUtils.parseRequestRef('gateway:sendcommand:1703123456789:k9l0m1');
+// => { service: 'gateway', operation: 'sendcommand', timestamp: 1703123456789, random: 'k9l0m1' }
+```
+
+### 4. 辅助方法
+
+```typescript
+// 获取消息类型的友好名称
+const typeName = ProtocolUtils.getMessageTypeName(message);
+// => "Command Response"
+
+// 检查是否为请求消息（需要响应）
+if (ProtocolUtils.isRequestMessage(message)) {
+  // 处理需要响应的消息
+}
+
+// 检查是否为响应消息
+if (ProtocolUtils.isResponseMessage(message)) {
+  // 处理响应消息
+}
+```
+
+## 实际使用场景
+
+### 场景 1：处理外部 API 数据
+
+```typescript
+// 从 REST API 接收的数据
+const apiData = {
+  status: 'completed',  // 小写
+  priority: 'HIGH',
+  client_type: 'backend'  // 下划线格式
+};
+
+// 转换为协议格式
+const command = {
+  status: ProtocolUtils.stringToStatus(apiData.status),
+  priority: ProtocolUtils.priorityToEnum(apiData.priority),
+  clientType: ProtocolUtils.clientTypeToEnum(apiData.client_type.replace('_', ''))
+};
+```
+
+### 场景 2：请求追踪和日志
+
+```typescript
+class CommandService {
+  async sendCommand(command: Command, targetClientId: string) {
+    // 生成可追踪的请求 ID
+    const requestRef = ProtocolUtils.generateStructuredRequestRef('backend', 'command');
+    
+    const message = MessageFactory.createCommandMessage(
+      requestRef,
+      targetClientId,
+      command,
+      '/api/callback'
+    );
+    
+    logger.info(`Sending command ${requestRef}`);
+    
+    try {
+      const response = await this.gateway.send(message);
+      
+      // 从响应中提取请求引用进行关联
+      const responseRef = ProtocolUtils.extractRequestRef(response);
+      logger.info(`Received response for ${responseRef}`);
+      
+    } catch (error) {
+      logger.error(`Command ${requestRef} failed:`, error);
+    }
+  }
+}
+```
+
+### 场景 3：消息路由和处理
+
+```typescript
+class MessageRouter {
+  handleMessage(message: AnyMessage) {
+    // 获取友好的消息类型名称用于日志
+    const messageType = ProtocolUtils.getMessageTypeName(message);
+    logger.info(`Processing ${messageType} message`);
+    
+    // 根据消息类型路由
+    if (ProtocolUtils.isRequestMessage(message)) {
+      this.handleRequest(message);
+    } else if (ProtocolUtils.isResponseMessage(message)) {
+      this.handleResponse(message);
+    } else if (ProtocolUtils.isProgressUpdate(message)) {
+      this.handleProgress(message as ProgressUpdateMessage);
+    }
+  }
+  
+  private handleProgress(message: ProgressUpdateMessage) {
+    const requestRef = ProtocolUtils.extractRequestRef(message);
+    const parsed = ProtocolUtils.parseRequestRef(requestRef!);
+    
+    if (parsed?.service === 'backend') {
+      // 处理来自 backend 的进度更新
+      this.notifyBackendProgress(message);
+    }
+  }
+}
+```
+
+### 场景 4：错误处理和重试
+
+```typescript
+class ErrorHandler {
+  handleError(error: any, originalMessage?: AnyMessage) {
+    let errorMessage: ErrorMessage;
+    
+    if (error.code && error.message) {
+      // 创建错误消息
+      errorMessage = MessageFactory.createErrorMessage(
+        error.code,
+        error.message,
+        originalMessage ? ProtocolUtils.extractRequestRef(originalMessage) : undefined
+      );
+    }
+    
+    // 安全地转换错误级别
+    const severity = ProtocolUtils.tryParseStatus(error.severity || 'FAILED');
+    if (severity) {
+      // 处理特定严重程度的错误
+    }
+  }
+}
+```
+
+### 场景 5：协议版本兼容
+
+```typescript
+class LegacyAdapter {
+  // 处理旧版本的消息格式
+  adaptLegacyMessage(legacyMsg: any): AnyMessage | null {
+    // 旧版本可能使用不同的状态值
+    const status = this.mapLegacyStatus(legacyMsg.status);
+    const modernStatus = ProtocolUtils.tryParseStatus(status);
+    
+    if (!modernStatus) {
+      logger.warn(`Unknown legacy status: ${legacyMsg.status}`);
+      return null;
+    }
+    
+    // 构建现代消息格式
+    // ...
+  }
+  
+  private mapLegacyStatus(legacyStatus: string): string {
+    const mapping: Record<string, string> = {
+      'done': 'COMPLETED',
+      'error': 'FAILED',
+      'pending': 'IN_PROGRESS'
+    };
+    
+    return mapping[legacyStatus] || legacyStatus;
+  }
+}
+```
+
+## 最佳实践
+
+1. **使用安全转换方法处理不可信输入**
+   ```typescript
+   const status = ProtocolUtils.tryParseStatus(userInput) || CommandStatus.FAILED;
+   ```
+
+2. **生成结构化的请求引用便于追踪**
+   ```typescript
+   const ref = ProtocolUtils.generateStructuredRequestRef(serviceName, operationName);
+   ```
+
+3. **使用增强的类型判断进行完整验证**
+   ```typescript
+   if (ProtocolUtils.isCommandMessage(message)) {
+     // 不仅类型正确，结构也已验证
+   }
+   ```
+
+4. **在日志中使用友好的消息类型名称**
+   ```typescript
+   logger.info(`${ProtocolUtils.getMessageTypeName(message)} processed`);
+   ```
+
+5. **解析请求引用以获取上下文信息**
+   ```typescript
+   const parsed = ProtocolUtils.parseRequestRef(requestRef);
+   if (parsed?.service === 'critical-service') {
+     // 优先处理关键服务的请求
+   }
+   ```

package/README.md

@@ -0,0 +1,237 @@
+# JRSoft Subway WebSocket 协议
+
+统一的 WebSocket 协议定义，供 Gateway、Backend 和 Edge 组件使用。
+
+## 📋 概述
+
+JRSoft Subway Protocol 是一个以 Gateway 为中心的实时通信协议，设计原则：
+- **简单性优先** - 基础功能使用最简消息格式
+- **渐进增强** - 通过可选字段支持高级功能  
+- **统一标准** - 所有组件使用 v1.0 协议
+- **类型安全** - 完整的 TypeScript 支持
+
+## 🏗️ 系统架构
+
+```
+┌─────────────┐     ┌─────────────┐     ┌──────────┐     ┌──────────┐
+│   Backend   │────▶│   Gateway   │────▶│   Edge   │────▶│  Device  │
+│  (18082)    │◀────│   (18081)   │◀────│ (Proxy)  │◀────│(Client)  │
+└─────────────┘     └─────────────┘     └──────────┘     └──────────┘
+```
+
+## 📚 文档结构
+
+### [01. 协议规范](./docs/01-protocol/)
+- [协议规范](./docs/01-protocol/specification.md) - 完整的协议定义
+- [消息类型](./docs/01-protocol/message-types.md) - 所有消息类型详解
+- [设计理念](./docs/01-protocol/design-rationale.md) - 协议设计决策
+
+### [02. 命令系统](./docs/02-commands/)
+- [Simple 命令](./docs/02-commands/simple-command.md) - 点对点命令
+- [Batch 命令](./docs/02-commands/batch-command.md) - 批量控制命令
+- [Complex 命令](./docs/02-commands/complex-command.md) - 复杂交互命令
+- [强类型命令](./docs/02-commands/typed-commands.md) - TypeScript 类型安全
+
+### [03. 架构设计](./docs/03-architecture/)
+- [Edge 代理](./docs/03-architecture/edge-proxy.md) - Edge 节点设计
+- [设备协议](./docs/03-architecture/device-protocol.md) - 设备连接规范
+- [消息路由](./docs/03-architecture/routing-flow.md) - 路由机制详解
+
+### [04. 集成指南](./docs/04-integration/)
+- [Gateway 集成](./docs/04-integration/gateway-guide.md) - Gateway 实施指南
+- [Backend 集成](./docs/04-integration/backend-guide.md) - Backend 实施指南
+- [Edge 集成](./docs/04-integration/edge-guide.md) - Edge 实施指南
+- [迁移指南](./docs/04-integration/migration-guide.md) - 版本迁移说明
+
+### [05. 示例代码](./docs/05-examples/)
+- 命令示例 - 各类命令的使用示例
+- 流程示例 - 完整的业务流程
+- 代码片段 - 常用代码模板
+
+### [06. 参考文档](./docs/06-reference/)
+- API 参考 - 完整的 API 文档
+- 术语表 - 专业术语解释
+- 常见问题 - FAQ
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+npm install jrsoft-subway-protocol
+```
+
+### 基本使用
+
+```typescript
+import { 
+  createSimpleCommand,
+  validateMessage,
+  GatewayClient 
+} from 'jrsoft-subway-protocol';
+
+// 创建命令
+const command = createSimpleCommand({
+  targetClientId: 'td-01',  // 直接指定设备ID
+  commandCode: 'SET_BRIGHTNESS',
+  deviceType: 'screen',
+  deviceId: 1,
+  operationType: 'write',
+  parameters: { brightness: 80 }
+});
+
+// 验证消息
+const valid = validateMessage(command);
+
+// 发送命令
+const client = new GatewayClient('ws://localhost:18081');
+const response = await client.sendCommand(command);
+```
+
+### 强类型命令
+
+```typescript
+import { createLedSwitchCommand } from 'jrsoft-subway-protocol';
+
+// TypeScript 提供完整的类型检查和智能提示
+const ledCommand = createLedSwitchCommand(
+  'req-123',           // requestRef
+  'td-01',             // targetClientId (设备ID)
+  15,                  // deviceId (子硬件ID)
+  'ON',                // switch: 'ON' | 'OFF'
+  'write'              // operationType
+);
+```
+
+## 🔑 核心特性
+
+### 消息类型
+- **register** - 客户端注册
+- **command** - 命令请求
+- **command_response** - 命令响应
+- **progress_update** - 进度更新
+- **program** - 节目上传
+- **heartbeat** - 心跳保活
+- **error** - 错误消息
+
+### 命令类型
+- **Simple** - 单次请求响应的简单命令
+- **Batch** - 批量控制多个子硬件
+- **Complex** - 支持多次响应的复杂命令
+
+### 客户端类型
+- **BACKEND** - 业务后端服务
+- **GATEWAY** - 中心路由网关
+- **EDGE** - 设备代理节点
+- **DEVICE** - 终端设备
+
+## 🛠️ 开发工具
+
+### 类型定义
+```typescript
+// 所有类型定义都已导出
+import type { 
+  CommandMessage,
+  CommandResponseMessage,
+  ProgressUpdateMessage 
+} from 'jrsoft-subway-protocol';
+```
+
+### 验证工具
+```typescript
+// 消息验证
+validateMessage(message);
+
+// 类型守卫
+if (isCommandMessage(message)) {
+  // TypeScript knows this is CommandMessage
+}
+```
+
+### 工厂函数
+```typescript
+// 创建各种消息
+createRegisterMessage(clientId, clientType);
+createHeartbeatMessage(clientId);
+createErrorMessage(code, message);
+```
+
+## 📦 项目结构
+
+```
+jrsoft-subway-protocol/
+├── src/                    # 源代码
+│   ├── index.ts           # 主入口，协议定义
+│   ├── command-types.ts   # 强类型命令定义
+│   ├── command-factory.ts # 命令工厂函数
+│   └── __tests__/         # 单元测试
+├── docs/                   # 文档
+│   ├── 01-protocol/       # 协议规范
+│   ├── 02-commands/       # 命令系统
+│   ├── 03-architecture/   # 架构设计
+│   ├── 04-integration/    # 集成指南
+│   ├── 05-examples/       # 示例代码
+│   └── 06-reference/      # 参考文档
+├── examples/               # 示例项目
+└── package.json           # 项目配置
+```
+
+## 📊 版本信息
+
+- **当前版本**: 1.0.6
+- **协议版本**: 1.0
+- **最低 Node.js**: 14.0.0
+- **TypeScript**: 4.5+
+
+## 🌟 核心功能
+
+### 连接管理
+- 客户端注册与注销（含 ACK 确认）
+- 心跳保活机制（含服务器状态）
+- Edge 代理设备注册
+- 会话管理和认证
+
+### 命令系统
+- **Simple 命令** - 快速点对点控制
+- **Batch 命令** - 高效批量操作
+- **Complex 命令** - 复杂交互流程
+- **强类型命令** - 基于 C# 模型的类型安全
+
+### 进度报告
+- 统一的 progress_update 机制
+- 支持自定义阶段
+- 结构化日志（ReportMessage）
+- 设备操作追踪
+
+### 程序管理
+- 大文件上传支持
+- 多阶段进度反馈
+- 断点续传能力
+- 完整性校验
+
+## 🤝 贡献指南
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'Add amazing feature'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 创建 Pull Request
+
+## 📝 更新日志
+
+查看 [CHANGELOG.md](./CHANGELOG.md) 了解版本更新历史。
+
+## 📄 许可证
+
+本项目采用 MIT 许可证 - 查看 [LICENSE](./LICENSE) 文件了解详情。
+
+## 🔗 相关项目
+
+- [jrsoft-subway-gateway](https://github.com/jrsoft/subway-gateway) - Gateway 实现
+- [jrsoft-subway-backend](https://github.com/jrsoft/subway-backend) - Backend 实现
+- [jrsoft-subway-edge](https://github.com/jrsoft/subway-edge) - Edge 实现
+
+## 💬 联系方式
+
+- 问题反馈: [GitHub Issues](https://github.com/jrsoft/subway-protocol/issues)
+- 邮件: tech@jrsoft.com