# 骑手端WebSocket工具说明

## 📁 文件结构

```
utils/
├── websocket.js          # WebSocket连接管理器
├── messageHandlers.js    # 消息处理器
└── README.md            # 说明文档

mixins/
└── websocketMixin.js    # WebSocket功能混入

config/
└── websocket.js         # WebSocket配置文件

store/modules/
└── websocket.js         # WebSocket状态管理
```

## 🚀 快速开始

### 1. 在页面中使用WebSocket功能

```javascript
// 在页面组件中引入mixin
import websocketMixin from '@/mixins/websocketMixin.js';

export default {
  mixins: [websocketMixin],
  
  onLoad() {
    // mixin会自动处理WebSocket连接
    // 如果用户已通过审核，会自动连接WebSocket
  }
}
```

### 2. 自定义消息处理

```javascript
// 在页面中重写消息处理方法
export default {
  mixins: [websocketMixin],
  
  methods: {
    // 重写新订单通知处理
    handleNewOrderNotification(message) {
      console.log('自定义处理新订单:', message);
      // 自定义逻辑
      this.showCustomOrderDialog(message);
    }
  }
}
```

### 3. 手动控制WebSocket

```javascript
export default {
  mixins: [websocketMixin],
  
  methods: {
    // 手动连接
    connectManually() {
      this.initWebSocket();
    },
    
    // 手动断开
    disconnectManually() {
      this.disconnectWebSocket();
    },
    
    // 重连
    reconnectManually() {
      this.reconnectWebSocket();
    },
    
    // 发送消息
    sendTestMessage() {
      this.sendWebSocketMessage('test message');
    },
    
    // 检查连接状态
    checkStatus() {
      const status = this.getWebSocketStatus();
      console.log('WebSocket状态:', status);
    }
  }
}
```

## 🔧 配置说明

### WebSocket配置 (config/websocket.js)

```javascript
export default {
  connection: {
    maxReconnectAttempts: 5,    // 最大重连次数
    reconnectInterval: 5000,    // 重连间隔(ms)
    heartbeatInterval: 30000,   // 心跳间隔(ms)
    connectionTimeout: 10000    // 连接超时(ms)
  },
  
  notification: {
    enableSound: true,          // 启用声音提醒
    enableVibration: true,      // 启用震动提醒
    enableToast: true,          // 启用Toast通知
    urgentOrderModal: true      // 紧急订单使用模态框
  }
}
```

### 消息类型常量

```javascript
import { MESSAGE_TYPES } from '@/utils/websocket.js';

// 可用的消息类型
MESSAGE_TYPES.NEW_ORDER           // 新订单
MESSAGE_TYPES.ORDER_CANCEL        // 订单取消
MESSAGE_TYPES.ORDER_STATUS_UPDATE // 订单状态更新
MESSAGE_TYPES.SYSTEM_MESSAGE      // 系统消息
```

## 📡 API参考

### WebSocket管理器 (utils/websocket.js)

#### 主要方法

```javascript
import riderWebSocketManager from '@/utils/websocket.js';

// 连接WebSocket
riderWebSocketManager.connect(userInfo, baseUrl);

// 断开连接
riderWebSocketManager.disconnect();

// 发送消息
riderWebSocketManager.send('message');

// 检查连接状态
riderWebSocketManager.isConnected();

// 注册消息处理器
riderWebSocketManager.onMessage('NEW_ORDER', (message) => {
  console.log('收到新订单:', message);
});

// 注册状态变化处理器
riderWebSocketManager.onStatusChange((status, data) => {
  console.log('状态变化:', status);
});
```

### 消息处理器 (utils/messageHandlers.js)

#### 处理器函数

```javascript
import { 
  handleNewOrderNotification,
  handleOrderCancelNotification,
  handleSystemMessage,
  registerMessageHandlers,
  unregisterMessageHandlers
} from '@/utils/messageHandlers.js';

// 注册所有处理器
registerMessageHandlers(wsManager, this);

// 注销所有处理器
unregisterMessageHandlers(wsManager);
```

### WebSocket混入 (mixins/websocketMixin.js)

#### 提供的方法

```javascript
// 混入提供的方法
this.initWebSocket()          // 初始化连接
this.disconnectWebSocket()    // 断开连接
this.reconnectWebSocket()     // 重连
this.sendWebSocketMessage()   // 发送消息
this.getWebSocketStatus()     // 获取状态
this.setWebSocketEnabled()    // 启用/禁用
```

#### 生命周期处理

- `onShow`: 页面显示时自动检查并重连
- `onHide`: 页面隐藏时保持连接
- `beforeDestroy`: 组件销毁前清理资源
- `onUnload`: 页面卸载时断开连接

## 🎯 使用场景

### 场景1: 基础使用

```javascript
// 只需要基本的WebSocket功能
export default {
  mixins: [websocketMixin]
  // 就这么简单！
}
```

### 场景2: 自定义通知

```javascript
export default {
  mixins: [websocketMixin],
  
  methods: {
    handleNewOrderNotification(message) {
      // 自定义新订单处理逻辑
      if (message.urgencyLevel >= 3) {
        // 特急订单特殊处理
        this.playUrgentSound();
        this.showFullScreenAlert(message);
      } else {
        // 普通订单
        this.showToast(message.orderNo);
      }
    }
  }
}
```

### 场景3: 状态监控

```javascript
export default {
  mixins: [websocketMixin],
  
  data() {
    return {
      wsStatus: '未连接'
    }
  },
  
  methods: {
    handleConnectionStatusChange(status) {
      this.wsStatus = status;
      // 更新UI状态显示
    }
  }
}
```

## 🐛 调试和故障排除

### 1. 启用调试日志

在开发环境中，WebSocket工具会自动输出详细的调试信息到控制台。

### 2. 常见问题

**Q: WebSocket连接失败**
```javascript
// 检查用户状态
if (!this.userInfo || !this.userInfo.state) {
  console.log('用户未通过审核');
}

// 检查网络连接
// 检查服务器地址配置
```

**Q: 消息处理器不工作**
```javascript
// 确保正确注册了处理器
registerMessageHandlers(riderWebSocketManager, this);

// 检查消息类型是否匹配
console.log('消息类型:', message.type);
```

**Q: 自动重连不工作**
```javascript
// 检查重连配置
riderWebSocketManager.reset(); // 重置重连状态
this.reconnectWebSocket();      // 手动重连
```

### 3. 性能监控

```javascript
// 检查连接状态
console.log('连接状态:', this.getWebSocketStatus());

// 查看重连次数
console.log('重连次数:', riderWebSocketManager.reconnectAttempts);

// 监控消息处理性能
performance.mark('message-start');
// 处理消息...
performance.mark('message-end');
performance.measure('message-processing', 'message-start', 'message-end');
```

## 📈 最佳实践

1. **使用mixin**: 推荐使用websocketMixin，它处理了大部分生命周期管理
2. **自定义处理**: 根据业务需求重写消息处理方法
3. **错误处理**: 总是处理连接错误和消息解析错误
4. **性能优化**: 避免在消息处理中执行耗时操作
5. **用户体验**: 合理使用声音、震动等提醒方式
6. **状态管理**: 使用Vuex模块管理WebSocket状态（可选）

## 🔄 版本更新

### v1.0.0
- 基础WebSocket连接管理
- 消息处理器系统
- Vue混入支持
- 自动重连机制
- 心跳保活功能