# 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 类型系统