@thejrsoft/subway-protocol 1.3.0

package/GATEWAY_PROTOCOL_COMPARISON.md

@@ -0,0 +1,216 @@
+# Gateway vs Protocol 类型定义比较
+
+## BaseMessage 比较
+
+### Gateway 定义
+```typescript
+export interface BaseMessage {
+  type: MessageType;
+  targetClientId?: string;
+}
+```
+
+### Protocol 定义
+```typescript
+export interface BaseMessage {
+  type: MessageType;
+  timestamp: string;  // ISO 8601 格式
+  version: string;    // 协议版本 "1.0"
+}
+```
+
+### 差异分析
+| 字段 | Gateway | Protocol | 说明 |
+|------|---------|----------|------|
+| type | ✓ | ✓ | 都有，类型一致 |
+| targetClientId | ✓ (可选) | ✗ | Gateway 特有，但应该只在特定消息中使用 |
+| timestamp | ✗ | ✓ (必需) | Protocol 要求所有消息都有时间戳 |
+| version | ✗ | ✓ (必需) | Protocol 要求协议版本号 |
+
+## CommandMessage 比较
+
+### Gateway 定义
+```typescript
+export interface CommandMessage extends BaseMessage {
+  type: typeof WS_MESSAGE_TYPES.COMMAND;
+  requestRef: string;
+  targetClientId: string;
+  command: {
+    commandType?: 'SIMPLE' | 'BATCH' | 'COMPLEX';
+    commandCode: string;
+    deviceType: string;
+    deviceId?: number;
+    operationType: string;
+    parameters: Record<string, unknown>;
+  };
+  priority: string;
+  timeout: number;
+  timestamp: string;
+  callback?: string;
+  version?: string;
+  metadata?: Record<string, any>;
+}
+```
+
+### Protocol 定义
+```typescript
+export interface CommandMessage extends BaseMessage {
+  type: MessageType.COMMAND;
+  requestRef: string;
+  targetClientId: string;
+  command: Command;  // 支持多种命令类型
+  priority: Priority;  // 枚举类型
+  timeout: number;
+  retryCount?: number;
+  callback: string;
+  metadata?: Record<string, any>;
+}
+
+// Command 可以是:
+// - SpecificCommand (从 C# 生成)
+// - SimpleCommand
+// - BatchCommand
+// - ComplexCommand
+// - GenericCommand
+```
+
+### 详细差异分析
+
+#### 1. 继承的差异
+- **Gateway**: 继承的 BaseMessage 有 `targetClientId?`
+- **Protocol**: 继承的 BaseMessage 有 `timestamp` 和 `version`
+
+#### 2. 字段级别差异
+
+| 字段 | Gateway | Protocol | 差异说明 |
+|------|---------|----------|----------|
+| requestRef | ✓ string | ✓ string | ✅ 一致 |
+| targetClientId | ✓ string | ✓ string | ✅ 一致 |
+| command | 内联对象 | Command 类型 | ⚠️ Protocol 使用强类型 |
+| priority | string | Priority 枚举 | ⚠️ Protocol 使用枚举 |
+| timeout | ✓ number | ✓ number | ✅ 一致 |
+| timestamp | ✓ string | 继承自 BaseMessage | ⚠️ Gateway 直接定义，Protocol 继承 |
+| callback | ✓ 可选 | ✓ 必需 | ❌ **重要差异** |
+| version | ✓ 可选 | 继承自 BaseMessage | ⚠️ Gateway 直接定义，Protocol 继承 |
+| retryCount | ✗ | ✓ 可选 | ⚠️ Protocol 特有 |
+| metadata | ✓ 可选 | ✓ 可选 | ✅ 一致 |
+
+#### 3. Command 结构差异
+
+**Gateway 的 command**:
+```typescript
+command: {
+  commandType?: 'SIMPLE' | 'BATCH' | 'COMPLEX';
+  commandCode: string;
+  deviceType: string;
+  deviceId?: number;
+  operationType: string;
+  parameters: Record<string, unknown>;
+}
+```
+
+**Protocol 的 command**:
+- 支持多种类型（SimpleCommand, BatchCommand, ComplexCommand, GenericCommand）
+- deviceId 支持 `number | number[] | string`
+- 有严格的类型定义和验证
+
+## 其他消息类型差异
+
+### RegisterMessage
+**主要差异**:
+- Gateway: `clientType: 'device' | 'edge' | 'backend'`
+- Protocol: `clientType: ClientType` (枚举)
+- Gateway: 没有 timestamp 和 version
+- Protocol: 继承自 BaseMessage，有 timestamp 和 version
+
+### RegisterAckMessage
+**主要差异**:
+- Gateway: `message?: string`
+- Protocol: `error?: { code: string; message: string }`
+- Protocol 有更详细的 serverInfo
+
+## 字段一致性总结
+
+### CommandMessage 完全一致的字段：
+- `requestRef: string` ✅
+- `targetClientId: string` ✅
+- `timeout: number` ✅
+- `metadata?: Record<string, any>` ✅
+
+### 主要差异字段：
+1. **callback**: Gateway 可选 vs Protocol 必需 ❌
+2. **priority**: Gateway 字符串 vs Protocol 枚举 ⚠️
+3. **command**: Gateway 内联对象 vs Protocol 强类型 ⚠️
+4. **retryCount**: 只在 Protocol 中存在 ⚠️
+
+## 统一建议
+
+### 1. BaseMessage 统一
+```typescript
+// 建议的统一定义
+export interface BaseMessage {
+  type: MessageType;
+  timestamp: string;    // 必需，便于追踪
+  version: string;      // 必需，便于版本管理
+  // targetClientId 不应该在这里，只在需要的消息中定义
+}
+```
+
+### 2. CommandMessage 统一
+需要决定：
+- **callback**: 是否必需？
+- **priority**: 使用枚举还是字符串？
+- **command**: 使用强类型还是松散对象？
+
+### 3. 迁移步骤
+1. Gateway 先迁移到使用协议包
+2. 处理字段差异（添加 timestamp, version）
+3. 统一类型定义（枚举 vs 字符串）
+4. 更新验证逻辑
+
+## 影响评估
+
+### 如果采用 Protocol 的严格定义
+**需要修改 Gateway**:
+1. 所有消息添加 timestamp 和 version
+2. callback 改为必需（或修改协议使其可选）
+3. priority 使用 Priority 枚举
+4. 移除 BaseMessage 中的 targetClientId
+
+### 如果放松 Protocol 的定义
+**需要修改 Protocol**:
+1. callback 改为可选
+2. priority 改为可选并提供默认值
+3. 可能需要调整验证逻辑
+
+## 推荐方案
+
+1. **保持 Protocol 的严格定义**（推荐）
+   - 更好的类型安全
+   - 清晰的 API 契约
+   - Gateway 迁移到使用协议包
+
+2. **创建适配层**
+   - Gateway 保持现有定义
+   - 创建转换函数在 Gateway 和 Protocol 之间转换
+   - 逐步迁移
+
+3. **放松 Protocol 定义**
+   - 使某些字段可选
+   - 降低迁移成本
+   - 但可能导致运行时错误
+
+## 更新说明
+
+### 关于 timeout 字段
+经过检查，`timeout` 字段在 Gateway 和 Protocol 的 CommandMessage 定义中都存在，都是必需的 `number` 类型。这不是差异点。
+
+### Backend 使用情况
+- Backend 已经完全迁移到使用 `@jrsoft/subway-protocol`
+- Backend 的 `gateway.client.ts` 和 `command.dispatcher.ts` 都使用了协议包的类型定义
+- Backend 中的 callback 使用 `appConfig.gateway.callbackUrl` 作为值
+
+### Gateway 使用情况  
+- Gateway 仍在使用自己的类型定义文件 (`src/types/common.types.ts`)
+- Gateway 尚未迁移到协议包
+- Gateway 的 callback 字段是可选的，这是主要差异之一

package/INTEGRATION_GUIDE.md

@@ -0,0 +1,190 @@
+# JRSoft Subway Protocol - C# 模型集成指南
+
+## 概述
+
+本协议包设计为与 `jrsoft-subway-csharp-model` 生成的 TypeScript 类型配合使用。当前包含的命令类型（`ExampleCommand`）仅为示例，实际使用时应从 C# 模型包导入真实的命令类型。
+
+## 集成步骤
+
+### 1. 安装 C# 模型包
+
+首先，需要将 C# 模型包添加为依赖：
+
+```bash
+# 如果 C# 模型包已发布到 npm
+npm install @jrsoft/csharp-model
+
+# 或者使用本地链接（开发时）
+cd ../jrsoft-subway-csharp-model
+npm link
+cd ../jrsoft-subway-protocol
+npm link @jrsoft/csharp-model
+```
+
+### 2. 更新 package.json
+
+在 `package.json` 中添加依赖：
+
+```json
+{
+  "dependencies": {
+    "@jrsoft/csharp-model": "^1.0.0"
+  }
+}
+```
+
+或者对于本地开发：
+
+```json
+{
+  "dependencies": {
+    "@jrsoft/csharp-model": "file:../jrsoft-subway-csharp-model"
+  }
+}
+```
+
+### 3. 更新 command-types.ts
+
+将示例命令替换为真实的 C# 生成的命令：
+
+```typescript
+// src/command-types.ts
+
+import { OperationType, CommandType } from './index';
+
+// 导入 C# 生成的命令类型
+import { 
+  LedSwitchCommand as CSharpLedSwitchCommand,
+  LedSwitchParameters,
+  BlockPlayCommand as CSharpBlockPlayCommand,
+  BlockPlayParameters,
+  // ... 更多命令
+} from '@jrsoft/csharp-model/typescript-schemas';
+
+// 适配命令接口（处理字段名差异，如 deviceID -> deviceId）
+export interface LedSwitchCommand extends Omit<CSharpLedSwitchCommand, 'deviceID'> {
+  commandType: CommandType;
+  deviceId: number | number[] | string;  // 重命名并支持批量
+}
+
+export interface BlockPlayCommand extends Omit<CSharpBlockPlayCommand, 'deviceID'> {
+  commandType: CommandType;
+  deviceId: number | number[] | string;
+}
+
+// 导出所有命令的联合类型
+export type SpecificCommand = 
+  | LedSwitchCommand
+  | BlockPlayCommand
+  // ... 更多命令
+  ;
+
+// 命令映射
+export interface CommandTypeMap {
+  'LedSwitch': LedSwitchCommand;
+  'BlockPlay': BlockPlayCommand;
+  // ... 更多映射
+}
+```
+
+### 4. 更新 command-factory.ts
+
+为每个真实命令添加工厂方法：
+
+```typescript
+// src/command-factory.ts
+
+export class TypedCommandFactory {
+  static createLedSwitchCommand(
+    requestRef: string,
+    targetClientId: string,
+    deviceId: number | number[] | string,
+    switchState: 'ON' | 'OFF',
+    operationType: OperationType = OperationType.WRITE,
+    options?: CommandOptions
+  ): CommandMessage {
+    return this.createTypedCommandMessage(
+      requestRef,
+      targetClientId,
+      'LedSwitch',
+      {
+        commandType: CommandType.SIMPLE,
+        deviceType: 'pillar',
+        deviceId,
+        operationType,
+        parameters: { switch: switchState }
+      },
+      options
+    );
+  }
+
+  // ... 更多命令工厂方法
+}
+```
+
+## 字段映射说明
+
+C# 生成的类型和协议要求的类型之间存在一些差异：
+
+1. **字段名称差异**
+   - C# 使用 `deviceID`（大写 ID）
+   - 协议使用 `deviceId`（小写 id）
+
+2. **额外字段**
+   - 协议需要 `commandType` 字段（SIMPLE/BATCH/COMPLEX）
+   - C# 生成的类型可能不包含此字段
+
+3. **批量操作支持**
+   - 协议的 `deviceId` 支持 `number | number[] | string`
+   - C# 可能只定义了 `number`
+
+## 开发建议
+
+1. **使用 TypeScript 接口扩展**
+   ```typescript
+   interface ProtocolCommand extends CSharpCommand {
+     commandType: CommandType;
+     // 其他协议特定字段
+   }
+   ```
+
+2. **创建适配器函数**
+   ```typescript
+   function adaptCSharpCommand(cmd: CSharpCommand): ProtocolCommand {
+     return {
+       ...cmd,
+       commandType: CommandType.SIMPLE,
+       deviceId: cmd.deviceID, // 字段重命名
+     };
+   }
+   ```
+
+3. **验证器更新**
+   - 确保验证器能处理 C# 生成的命令结构
+   - 添加特定命令的验证逻辑
+
+## 注意事项
+
+1. **版本同步**：确保 C# 模型包和协议包版本兼容
+2. **类型安全**：使用 TypeScript 的严格模式确保类型正确
+3. **测试覆盖**：为每个集成的命令添加单元测试
+4. **文档更新**：集成新命令时更新相关文档
+
+## 示例项目结构
+
+```
+jrsoft-subway/
+├── jrsoft-subway-protocol/          # 协议定义
+│   ├── src/
+│   │   ├── index.ts                # 核心协议
+│   │   ├── command-types.ts        # 命令类型（导入 C# 类型）
+│   │   └── command-factory.ts      # 命令工厂
+│   └── package.json
+├── jrsoft-subway-csharp-model/      # C# 模型
+│   ├── typescript-schemas/         # 生成的 TS 类型
+│   │   ├── LedSwitchCommand.generated.ts
+│   │   └── ...
+│   └── package.json
+└── jrsoft-subway-gateway/           # 使用协议的服务
+    └── package.json                # 依赖 protocol 包
+```

package/OPTIONAL_FIELDS_WITHOUT_DEFAULTS.md

@@ -0,0 +1,97 @@
+# Protocol 中没有默认值的可选字段
+
+## 概述
+这些可选字段在 MessageFactory 中没有提供默认值，使用时需要显式传递或留空。
+
+## 1. RegisterMessage
+- `clientInfo?: ClientInfo` - 没有默认值
+  - `name?: string`
+  - `version?: string`
+  - `platform?: string`
+  - `capabilities?: string[]`
+  - `deviceType?: string`
+  - `description?: string`
+  - `metadata?: Record<string, any>`
+- `edgeInfo?: EdgeInfo` - 没有默认值
+  - `edgeVersion?: string`
+  - `connectionTime?: string`
+
+## 2. RegisterAckMessage
+- `sessionId?: string` - 没有默认值
+- `error?: { code: string; message: string }` - 根据 success 条件生成
+- `serverInfo?: { ... }` - 没有默认值
+  - `currentLoad?: number`
+  - `maxClients?: number`
+
+## 3. UnregisterMessage
+- `reason?: string` - 没有默认值
+
+## 4. UnregisterAckMessage
+- `cleanupInfo?: { ... }` - 没有默认值
+
+## 5. CommandMessage
+- `retryCount?: number` - 没有默认值
+- `metadata?: Record<string, any>` - 没有默认值
+
+## 6. Command 相关
+- `parameters?: Record<string, any>` - 没有默认值（所有 Command 类型）
+- ComplexCommand 中的可选字段：
+  - `deviceId?: number | number[] | string`
+  - `deviceType?: string`
+  - `operationType?: OperationType`
+- GenericCommand 中的可选字段（无默认值，但验证器会检查）：
+  - `commandType?: CommandType`
+  - `deviceId?: number | number[] | string`
+  - `deviceType?: string`
+  - `operationType?: OperationType`
+
+## 7. CommandResponseMessage
+- `result?: CommandResult` - 没有默认值
+- `report?: ReportMessage` - 根据 message 参数条件生成
+- `executionTime?: number` - 没有默认值
+
+## 8. HeartbeatAckMessage
+- `latency?: number` - 没有默认值
+- `serverStatus?: { ... }` - 没有默认值
+  - `cpuUsage?: number`
+  - `memoryUsage?: number`
+
+## 9. ErrorMessage
+- `category?: string` - 没有默认值
+- `context?: any` - 根据参数构建，但内部字段可能为空
+- `retryable?: boolean` - 没有默认值
+
+## 10. ProgramResponseMessage
+- `context?: ProgramContext` - 没有默认值（使用 result 参数）
+- `report?: ReportMessage` - 根据 message 参数条件生成
+- `executionTime?: number` - 没有默认值
+
+## 11. ProgressUpdateMessage
+- `context?: ProgramContext` - 没有默认值
+- `command?: DeviceOperationRecord` - 没有默认值
+- `report?: ReportMessage` - 根据 message 参数条件生成
+  - `code?: string` - 没有默认值
+  - `data?: Record<string, any>` - 没有默认值
+
+## 12. DeviceOperationRecord
+- `result?: Record<string, any>` - 没有默认值
+
+## 建议
+
+### 可以考虑添加默认值的字段：
+1. **retryCount** - 可以默认为 0
+2. **metadata** - 可以默认为空对象 {}
+3. **latency** - 可以根据时间戳计算
+4. **executionTime** - 可以根据开始和结束时间计算
+
+### 不应该有默认值的字段：
+1. **sessionId** - 必须由服务器生成
+2. **result** - 必须是实际执行结果
+3. **error** - 只在错误时存在
+4. **serverInfo/serverStatus** - 必须是实际服务器状态
+5. **context** - 必须是实际上下文信息
+
+### Gateway 迁移注意事项：
+- 这些没有默认值的可选字段，Gateway 可以根据实际情况选择性提供
+- 不提供时，字段会被省略（undefined），这符合 Protocol 的设计
+- 某些字段（如 metadata）虽然没有默认值，但 Gateway 可以在自己的代码中设置默认空对象