@thejrsoft/subway-protocol 1.3.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@thejrsoft/subway-protocol",
+  "version": "1.3.0",
+  "description": "Shared WebSocket protocol definitions for JRSoft Subway",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "clean": "rm -rf dist",
+    "validate:asyncapi": "ts-node scripts/validate-asyncapi.ts",
+    "generate:asyncapi-enums": "ts-node -e \"import {generateAsyncApiEnums} from './src/asyncapi-sync'; console.log(generateAsyncApiEnums())\"",
+    "test": "jest",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": ["websocket", "protocol", "jrsoft", "subway"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOUR_ORG/jrsoft-subway.git"
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*",
+    "docs/**/*",
+    "examples/**/*",
+    "scripts/**/*",
+    "*.md",
+    "tsconfig.json"
+  ],
+  "devDependencies": {
+    "@types/node": "^18.0.0",
+    "@types/jest": "^29.0.0",
+    "@asyncapi/parser": "^2.1.0",
+    "typescript": "^5.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "eslint": "^8.0.0",
+    "@typescript-eslint/parser": "^5.0.0",
+    "@typescript-eslint/eslint-plugin": "^5.0.0",
+    "ts-node": "^10.0.0"
+  }
+}

package/scripts/validate-asyncapi.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * 验证 TypeScript 实现与 AsyncAPI 规范的一致性
+ */
+
+import { Parser } from '@asyncapi/parser';
+import * as fs from 'fs';
+import * as path from 'path';
+import { 
+  MessageType,
+  RegisterMessage,
+  CommandMessage 
+} from '../src/index';
+
+async function validateProtocolConsistency() {
+  // 1. 解析 AsyncAPI 文档
+  const parser = new Parser();
+  const asyncApiPath = path.join(__dirname, '../../jrsoft-subway-gateway/asyncapi.yaml');
+  const asyncApiContent = fs.readFileSync(asyncApiPath, 'utf8');
+  
+  const { document, diagnostics } = await parser.parse(asyncApiContent);
+  
+  if (diagnostics.length > 0) {
+    console.error('AsyncAPI parsing errors:', diagnostics);
+    return false;
+  }
+
+  // 2. 提取 AsyncAPI 中定义的消息类型
+  const asyncApiMessages = new Set<string>();
+  const channels = document?.channels();
+  
+  if (channels) {
+    for (const [channelName, channel] of Object.entries(channels)) {
+      const publish = channel.publish();
+      const subscribe = channel.subscribe();
+      
+      [publish, subscribe].forEach(operation => {
+        if (operation?.messages()) {
+          operation.messages().forEach(msg => {
+            const payload = msg.payload();
+            if (payload?.properties?.type?.const) {
+              asyncApiMessages.add(payload.properties.type.const);
+            }
+          });
+        }
+      });
+    }
+  }
+
+  // 3. 比较 TypeScript 枚举与 AsyncAPI 定义
+  const tsMessageTypes = Object.values(MessageType);
+  const missingInAsyncApi = tsMessageTypes.filter(type => !asyncApiMessages.has(type));
+  const missingInTypeScript = Array.from(asyncApiMessages).filter(type => !tsMessageTypes.includes(type as any));
+
+  // 4. 输出验证结果
+  console.log('=== Protocol Validation Results ===');
+  console.log(`TypeScript message types: ${tsMessageTypes.length}`);
+  console.log(`AsyncAPI message types: ${asyncApiMessages.size}`);
+  
+  if (missingInAsyncApi.length > 0) {
+    console.error('❌ Missing in AsyncAPI:', missingInAsyncApi);
+  }
+  
+  if (missingInTypeScript.length > 0) {
+    console.error('❌ Missing in TypeScript:', missingInTypeScript);
+  }
+  
+  if (missingInAsyncApi.length === 0 && missingInTypeScript.length === 0) {
+    console.log('✅ All message types are synchronized!');
+  }
+
+  return missingInAsyncApi.length === 0 && missingInTypeScript.length === 0;
+}
+
+// 运行验证
+validateProtocolConsistency().then(isValid => {
+  process.exit(isValid ? 0 : 1);
+});

package/src/__tests__/protocol.test.ts

@@ -0,0 +1,297 @@
+/**
+ * 协议规范测试套件
+ * 验证实现是否符合 PROTOCOL_SPECIFICATION.md
+ */
+
+import {
+  MessageFactory,
+  MessageValidator,
+  MessageType,
+  ClientType,
+  Priority,
+  OperationType,
+  CommandType,
+  GatewayUtils,
+  GATEWAY_SITE_ID,
+  isRegisterMessage,
+  isCommandMessage
+} from '../index';
+
+describe('JRSoft Subway Protocol v1.0', () => {
+  describe('基础消息格式', () => {
+    test('所有消息必须包含 type 字段', () => {
+      const message = { type: 'register', clientId: 'test' };
+      expect(MessageValidator.validateMessage(message)).toBe(true);
+      
+      const invalidMessage = { clientId: 'test' };
+      expect(MessageValidator.validateMessage(invalidMessage)).toBe(false);
+    });
+
+    test('timestamp 和 version 字段是可选的', () => {
+      const minimalMessage = { type: 'register', clientId: 'test' };
+      expect(MessageValidator.validateRegisterMessage(minimalMessage)).toBe(true);
+      
+      const fullMessage = {
+        type: 'register',
+        clientId: 'test',
+        timestamp: new Date().toISOString(),
+        version: '1.0'
+      };
+      expect(MessageValidator.validateRegisterMessage(fullMessage)).toBe(true);
+    });
+  });
+
+  describe('注册消息兼容性', () => {
+    test('支持简单注册格式（v1.0）', () => {
+      const simpleRegister = {
+        type: 'register',
+        clientId: 'device001'
+      };
+      
+      expect(isRegisterMessage(simpleRegister)).toBe(true);
+      expect(MessageValidator.validateRegisterMessage(simpleRegister)).toBe(true);
+    });
+
+    test('支持完整注册格式（v1.0）', () => {
+      const fullRegister = MessageFactory.createRegisterMessage(
+        'backend-server',
+        ClientType.BACKEND,
+        {
+          version: '1.0.0',
+          platform: 'nodejs',
+          capabilities: ['command', 'program']
+        }
+      );
+      
+      expect(isRegisterMessage(fullRegister)).toBe(true);
+      expect(MessageValidator.validateRegisterMessage(fullRegister)).toBe(true);
+      expect(fullRegister.clientType).toBe(ClientType.BACKEND);
+      expect(fullRegister.clientInfo?.capabilities).toContain('command');
+    });
+  });
+
+  describe('命令消息格式', () => {
+    test('标准命令消息', () => {
+      const command = MessageFactory.createCommandMessage(
+        'req-123',
+        'device001',
+        {
+          commandType: CommandType.SIMPLE,
+          commandCode: 'READ_STATUS',
+          deviceType: 'controller',
+          operationType: OperationType.READ,
+          parameters: {}
+        },
+        'http://callback.example.com/response'
+      );
+      
+      expect(isCommandMessage(command)).toBe(true);
+      expect(MessageValidator.validateCommandMessage(command)).toBe(true);
+      expect(command.priority).toBe(Priority.NORMAL);
+      expect(command.timeout).toBe(10000);
+    });
+
+    test('高优先级命令', () => {
+      const command = MessageFactory.createCommandMessage(
+        'req-urgent',
+        'device001',
+        {
+          commandType: CommandType.SIMPLE,
+          commandCode: 'EMERGENCY_STOP',
+          deviceType: 'controller',
+          operationType: OperationType.WRITE,
+          parameters: {}
+        },
+        'http://callback.example.com/response',
+        {
+          priority: Priority.CRITICAL,
+          timeout: 5000
+        }
+      );
+      
+      expect(command.priority).toBe(Priority.CRITICAL);
+      expect(command.timeout).toBe(5000);
+    });
+  });
+
+  describe('Gateway 特殊命令', () => {
+    test('查询设备状态命令', () => {
+      const query = GatewayUtils.createDeviceStatusQuery('device001', 'query-001');
+      
+      expect(query.targetClientId).toBe(GATEWAY_SITE_ID);
+      expect(query.command.commandCode).toBe('GET_DEVICE_STATUS');
+      expect(query.command.operationType).toBe('read');
+      expect(query.command.parameters.targetClientId).toBe('device001');
+      expect(GatewayUtils.isGatewayCommand(query)).toBe(true);
+    });
+
+    test('列出设备命令', () => {
+      const listCmd = GatewayUtils.createListDevicesCommand({
+        status: 'online',
+        clientType: 'device'
+      });
+      
+      expect(listCmd.clientId).toBe(GATEWAY_SITE_ID);
+      expect(listCmd.command.commandCode).toBe('LIST_DEVICES');
+      expect(listCmd.command.parameters.filter).toEqual({
+        status: 'online',
+        clientType: 'device'
+      });
+    });
+
+
+    test('命令链', () => {
+      const chainCmd = GatewayUtils.createCommandChain(
+        'device001',
+        [
+          { commandCode: 'STOP', parameters: {} },
+          { commandCode: 'RESET', parameters: {}, delay: 1000 },
+          { commandCode: 'START', parameters: {} }
+        ]
+      );
+      
+      expect(chainCmd.commandChain).toHaveLength(3);
+      expect(chainCmd.commandChain![1].delay).toBe(1000);
+      expect(chainCmd.timeout).toBeGreaterThan(30000); // 默认超时应考虑延迟
+    });
+  });
+
+  describe('消息签名', () => {
+    test('签名消息', () => {
+      const message = { type: 'command', requestRef: 'test', clientId: 'test' };
+      const signedMessage = GatewayUtils.signMessage(message, 'secret-key');
+      
+      expect(signedMessage.signature).toBeDefined();
+      expect(signedMessage.signatureMethod).toBe('sha256');
+    });
+
+    test('验证签名', () => {
+      const message = { type: 'command', requestRef: 'test', clientId: 'test' };
+      const signedMessage = GatewayUtils.signMessage(message, 'secret-key');
+      
+      const isValid = GatewayUtils.verifyMessageSignature(signedMessage, 'secret-key');
+      expect(isValid).toBe(true);
+    });
+  });
+
+  describe('心跳消息', () => {
+    test('创建心跳消息', () => {
+      const heartbeat = MessageFactory.createHeartbeatMessage('device001', 12345);
+      
+      expect(heartbeat.type).toBe(MessageType.HEARTBEAT);
+      expect(heartbeat.clientId).toBe('device001');
+      expect(heartbeat.sequence).toBe(12345);
+      expect(heartbeat.timestamp).toBeDefined();
+    });
+  });
+
+  describe('错误处理', () => {
+    test('创建错误消息', () => {
+      const error = MessageFactory.createErrorMessage(
+        'DEVICE_OFFLINE',
+        'Target device is not connected',
+        'medium',
+        'device',
+        {
+          context: {
+            clientId: 'device001',
+            requestRef: 'req-123'
+          },
+          retryable: true
+        }
+      );
+      
+      expect(error.type).toBe(MessageType.ERROR);
+      expect(error.code).toBe('DEVICE_OFFLINE');
+      expect(error.retryable).toBe(true);
+      expect(error.context?.clientId).toBe('device001');
+    });
+  });
+
+  describe('程序上传', () => {
+    test('创建程序上传消息', () => {
+      const program = MessageFactory.createProgramMessage(
+        'prog-123',
+        'device001',
+        {
+          device_id: 'device001',
+          programId: 'prog-v1.0.1',
+          downloadUrl: 'https://example.com/program.zip',
+          checksum: 'sha256:abcd1234',
+          hashAlgorithm: 'sha256'
+        }
+      );
+      
+      expect(program.type).toBe(MessageType.PROGRAM);
+      expect(program.command.commandCode).toBe('UPLOAD_PROGRAM');
+      expect(program.command.operationType).toBe('write');
+      expect(program.timeout).toBe(1800000); // 30分钟
+    });
+  });
+
+  describe('协议版本兼容性', () => {
+    test('消息类型支持字符串和枚举', () => {
+      const stringType = { type: 'register', clientId: 'test' };
+      const enumType = { type: MessageType.REGISTER, clientId: 'test' };
+      
+      expect(isRegisterMessage(stringType)).toBe(true);
+      expect(isRegisterMessage(enumType)).toBe(true);
+    });
+
+    test('字段名兼容性（device_id vs deviceId）', () => {
+      const oldFormat = {
+        device_id: 'device001',
+        programId: 'test'
+      };
+      
+      const newFormat = {
+        deviceId: 'device001',
+        programId: 'test'
+      };
+      
+      // 两种格式都应该被接受
+      expect(oldFormat.device_id || oldFormat.deviceId).toBe('device001');
+      expect(newFormat.deviceId || newFormat.device_id).toBe('device001');
+    });
+  });
+});
+
+describe('协议设计原则验证', () => {
+  test('简单性优先 - 最小注册消息只需2个字段', () => {
+    const minimalRegister = {
+      type: 'register',
+      clientId: 'device001'
+    };
+    
+    const keys = Object.keys(minimalRegister);
+    expect(keys).toHaveLength(2);
+    expect(MessageValidator.validateRegisterMessage(minimalRegister)).toBe(true);
+  });
+
+  test('渐进增强 - 可选字段不影响基础功能', () => {
+    const basic = { type: 'register', clientId: 'test' };
+    const enhanced = {
+      ...basic,
+      clientType: 'device',
+      clientInfo: { version: '1.0' },
+      timestamp: new Date().toISOString(),
+      version: '2.0'
+    };
+    
+    // 两种格式都有效
+    expect(MessageValidator.validateRegisterMessage(basic)).toBe(true);
+    expect(MessageValidator.validateRegisterMessage(enhanced)).toBe(true);
+  });
+
+  test('明确语义 - 每个消息类型有唯一用途', () => {
+    const messageTypes = Object.values(MessageType);
+    const uniqueTypes = new Set(messageTypes);
+    
+    // 没有重复的消息类型
+    expect(uniqueTypes.size).toBe(messageTypes.length);
+    
+    // 每个类型都有明确的用途
+    expect(MessageType.REGISTER).not.toBe(MessageType.COMMAND);
+    expect(MessageType.HEARTBEAT).not.toBe(MessageType.PROGRAM);
+  });
+});

package/src/asyncapi-sync.ts

@@ -0,0 +1,84 @@
+/**
+ * 保持 TypeScript 实现与 AsyncAPI 文档同步的工具
+ */
+
+import { MessageType, ClientType, OperationType, Priority, CommandStatus } from './index';
+
+/**
+ * 生成 AsyncAPI 的枚举定义
+ */
+export function generateAsyncApiEnums() {
+  const enums = {
+    MessageType: Object.values(MessageType),
+    ClientType: Object.values(ClientType),
+    OperationType: Object.values(OperationType),
+    Priority: Object.values(Priority),
+    CommandStatus: Object.values(CommandStatus)
+  };
+
+  return `
+# AsyncAPI Enum Definitions
+# Generated from TypeScript implementation
+
+components:
+  schemas:
+    MessageType:
+      type: string
+      enum: ${JSON.stringify(enums.MessageType)}
+    
+    ClientType:
+      type: string
+      enum: ${JSON.stringify(enums.ClientType)}
+    
+    OperationType:
+      type: string
+      enum: ${JSON.stringify(enums.OperationType)}
+    
+    Priority:
+      type: string
+      enum: ${JSON.stringify(enums.Priority)}
+    
+    CommandStatus:
+      type: string
+      enum: ${JSON.stringify(enums.CommandStatus)}
+  `;
+}
+
+/**
+ * 生成消息示例用于 AsyncAPI 文档
+ */
+export function generateMessageExamples() {
+  return {
+    register_simple: {
+      type: 'register',
+      clientId: 'device001'
+    },
+    register_full: {
+      type: MessageType.REGISTER,
+      clientId: 'backend-server',
+      clientType: ClientType.BACKEND,
+      clientInfo: {
+        version: '1.0.0',
+        platform: 'nodejs',
+        capabilities: ['command', 'program']
+      },
+      timestamp: new Date().toISOString(),
+      version: '2.0'
+    },
+    command: {
+      type: MessageType.COMMAND,
+      requestRef: 'req-123',
+      clientId: 'device001',
+      command: {
+        commandCode: 'READ_STATUS',
+        deviceType: 'controller',
+        operationType: OperationType.READ,
+        parameters: { register: 'R001' }
+      },
+      priority: Priority.HIGH,
+      timeout: 10000,
+      timestamp: new Date().toISOString(),
+      version: '2.0'
+    }
+  };
+}

package/src/command-factory.ts

@@ -0,0 +1,183 @@
+/**
+ * 强类型命令工厂
+ * 
+ * 提供类型安全的命令创建和验证功能
+ */
+
+import type { CommandTypeMap, SpecificCommand } from './command-types';
+import type { CommandMessage, Priority } from './index';
+import { MessageFactory, OperationType, CommandType } from './index';
+
+/**
+ * 强类型命令消息工厂
+ */
+export class TypedCommandFactory {
+  /**
+   * 创建强类型命令消息
+   */
+  static createTypedCommandMessage<T extends keyof CommandTypeMap>(
+    requestRef: string,
+    targetClientId: string,
+    commandCode: T,
+    commandProps: Omit<CommandTypeMap[T], 'commandCode'>,
+    options?: {
+      priority?: Priority;
+      timeout?: number;
+      callback?: string;
+    }
+  ): CommandMessage {
+    const command: CommandTypeMap[T] = {
+      commandCode,
+      ...commandProps
+    } as CommandTypeMap[T];
+
+    return MessageFactory.createCommandMessage(
+      requestRef,
+      targetClientId,
+      command,
+      options?.callback || '',  // callback 是必需的，如果未提供则使用空字符串
+      {
+        priority: options?.priority,
+        timeout: options?.timeout
+      }
+    );
+  }
+
+  /**
+   * 示例：创建命令的工厂方法
+   * 
+   * 实际使用时，应该为每个从 C# 生成的命令创建对应的工厂方法
+   * 例如: createLedSwitchCommand, createBlockPlayCommand 等
+   */
+  static createExampleCommand(
+    requestRef: string,
+    targetClientId: string,
+    deviceId: number,
+    exampleField: string,
+    exampleValue: number,
+    operationType: OperationType = OperationType.WRITE,
+    options?: {
+      priority?: Priority;
+      timeout?: number;
+      callback?: string;
+    }
+  ): CommandMessage {
+    return this.createTypedCommandMessage(
+      requestRef,
+      targetClientId,
+      'ExampleCommand',
+      {
+        commandType: CommandType.SIMPLE,
+        deviceType: 'example',
+        deviceId,
+        operationType,
+        parameters: { exampleField, exampleValue }
+      },
+      options
+    );
+  }
+}
+
+/**
+ * 命令类型验证器
+ */
+export class CommandTypeValidator {
+  /**
+   * 验证命令是否符合强类型定义
+   */
+  static validateCommand(command: any): { valid: boolean; errors: string[] } {
+    const errors: string[] = [];
+
+    if (!command) {
+      errors.push('Command is null or undefined');
+      return { valid: false, errors };
+    }
+
+    if (!command.commandCode || typeof command.commandCode !== 'string') {
+      errors.push('commandCode is required and must be a string');
+    }
+
+    if (!command.deviceType || typeof command.deviceType !== 'string') {
+      errors.push('deviceType is required and must be a string');
+    }
+
+    if (!command.operationType || !Object.values(OperationType).includes(command.operationType as OperationType)) {
+      errors.push('operationType must be READ or WRITE');
+    }
+
+    // 根据具体的 commandCode 进行详细验证
+    switch (command.commandCode) {
+      case 'ExampleCommand':
+        this.validateExampleCommand(command, errors);
+        break;
+      // TODO: 实际使用时，为每个真实命令添加验证
+      // case 'LedSwitch':
+      //   this.validateLedSwitchCommand(command, errors);
+      //   break;
+      default:
+        // 对于未知的命令类型，只做基本验证
+        break;
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+
+  private static validateExampleCommand(command: any, errors: string[]): void {
+    if (command.deviceType !== 'example') {
+      errors.push('ExampleCommand requires deviceType to be "example"');
+    }
+
+    if (command.parameters) {
+      if (typeof command.parameters.exampleField !== 'string') {
+        errors.push('ExampleCommand parameters.exampleField must be a string');
+      }
+      if (typeof command.parameters.exampleValue !== 'number') {
+        errors.push('ExampleCommand parameters.exampleValue must be a number');
+      }
+    }
+  }
+}
+
+/**
+ * 命令类型转换器
+ */
+export class CommandTypeConverter {
+  /**
+   * 将通用命令转换为强类型命令
+   */
+  static toTypedCommand(genericCommand: any): SpecificCommand | null {
+    const validation = CommandTypeValidator.validateCommand(genericCommand);
+    if (!validation.valid) {
+      console.warn('Command validation failed:', validation.errors);
+      return null;
+    }
+
+    // 根据 commandCode 转换为具体的强类型
+    switch (genericCommand.commandCode) {
+      case 'ExampleCommand':
+        return genericCommand as import('./command-types').ExampleCommand;
+      // TODO: 实际使用时，为每个真实命令添加转换
+      // case 'LedSwitch':
+      //   return genericCommand as import('./command-types').LedSwitchCommand;
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * 检查命令是否为强类型命令
+   */
+  static isTypedCommand(command: any): command is SpecificCommand {
+    return command && this.toTypedCommand(command) !== null;
+  }
+}
+
+// 导出便捷的工厂函数
+export const createExampleCommand = TypedCommandFactory.createExampleCommand.bind(TypedCommandFactory);
+// TODO: 实际使用时，导出真实的命令工厂函数
+// export const createLedSwitchCommand = TypedCommandFactory.createLedSwitchCommand.bind(TypedCommandFactory);
+// export const createBlockPlayCommand = TypedCommandFactory.createBlockPlayCommand.bind(TypedCommandFactory);
+
+// 导出验证函数
+export const validateCommand = CommandTypeValidator.validateCommand.bind(CommandTypeValidator);
+export const toTypedCommand = CommandTypeConverter.toTypedCommand.bind(CommandTypeConverter);