# 外部WebSocket设备标注集成说明

## 概述

本文档说明如何使用新创建的外部WebSocket设备标注功能，该功能专门用于处理来自外部WebSocket的无人装备数据并在地图上绘制相应的标注。

## 新增方法

### 1. 主要方法

#### `加载外部WebSocket设备标注(deviceData: any)`
- **功能**: 处理外部WebSocket数据并在地图上创建/更新设备标注
- **参数**: `deviceData` - 外部WebSocket消息数据
- **返回**: 无

#### `removeExternalDeviceAnnotation(deviceSn: string)`
- **功能**: 移除指定设备的地图标注
- **参数**: `deviceSn` - 设备序列号
- **返回**: 无

#### `clearAllExternalDeviceAnnotations()`
- **功能**: 清除所有外部设备的地图标注
- **参数**: 无
- **返回**: 无

#### `getExternalDeviceAnnotations()`
- **功能**: 获取所有外部设备标注列表
- **参数**: 无
- **返回**: 设备标注数组

### 2. 辅助方法

#### `extractExternalDeviceInfo(data: any)`
- **功能**: 从外部WebSocket数据中提取设备信息
- **参数**: `data` - 原始WebSocket数据
- **返回**: 标准化的设备信息对象

#### `getDeviceIcon(deviceType: string)`
- **功能**: 根据设备类型获取对应的图标URL
- **参数**: `deviceType` - 设备类型（'unmanned_vehicle' 或 'drone'）
- **返回**: 图标URL字符串

#### `addStrikeRangeForExternalDevice(deviceSn: string, deviceInfo: any)`
- **功能**: 为外部设备添加侦察范围显示
- **参数**: 
  - `deviceSn` - 设备序列号
  - `deviceInfo` - 设备信息对象
- **返回**: 无

## 支持的数据格式

### 1. 外部WebSocket数据格式（您提供的数据）

```javascript
{
  type: "unmanned_vehicle_data",
  topic: "/CKC/WRJ/PTZT",
  deviceType: "unmanned_vehicle",
  data: {
    XXLX: "PTZT",
    XXXX: [{
      BBH: "V000.00.100",
      CKZD: {
        GC: 55.6,
        JD: 119.068079,
        WD: 32.04998,
        ZBID: 'b'
      },
      WRZB: {
        GC: '55.6',
        JD: '119.068',
        WD: '32.05',
        ZBID: '10002000'
      },
      JKZT: {
        ZHZT: '1'  // 1表示在线，0表示离线
      },
      YDFX: 0,  // 运动方向
      YDSD: 0,  // 运动速度
      SBSJ: "2025-8-15 17:32:57"
    }]
  },
  timestamp: "2025-09-04T12:37:25.1932Z"
}
```

### 2. 简化位置数据格式

```javascript
{
  type: "position",
  device_sn: "FF2023081601",
  device_name: "哈瓦战斧",
  longitude: 118.10067,
  latitude: 32.511448,
  altitude: 200,
  online_status: true,
  strikeRange: 10
}
```

## 集成步骤

### 1. 在WebSocket消息处理中调用

```javascript
// 在您的WebSocket消息处理函数中
import { Xiaorui } from '@/utils/aixiaorui';

// 假设您有一个Xiaorui实例
let xiaoruiInstance: Xiaorui;

// 处理外部WebSocket消息
function handleExternalWebSocketMessage(data) {
  console.log('处理外部WebSocket消息:', data);
  
  try {
    // 检查是否是无人车数据格式
    if (data.type === 'unmanned_vehicle_data' && data.data && data.data.XXXX) {
      console.log('检测到无人车数据，开始在地图上绘制...');
      
      // 调用新的外部设备标注方法
      if (xiaoruiInstance) {
        xiaoruiInstance.加载外部WebSocket设备标注(data);
      }
    }
    
    // 处理其他类型的外部数据
    else if (data.type === 'position' && data.longitude && data.latitude) {
      console.log('检测到位置数据，开始在地图上绘制...');
      
      if (xiaoruiInstance) {
        xiaoruiInstance.加载外部WebSocket设备标注(data);
      }
    }
    
  } catch (error) {
    console.error('处理外部WebSocket消息失败:', error);
  }
}
```

### 2. 在Vue组件中使用

```vue
<template>
  <div>
    <!-- 您的地图组件 -->
    <div ref="mapContainer"></div>
  </div>
</template>

<script>
import { Xiaorui } from '@/utils/aixiaorui';
import EventBus from '@/event-bus';

export default {
  data() {
    return {
      xiaoruiInstance: null
    };
  },
  
  mounted() {
    // 初始化Xiaorui实例
    this.xiaoruiInstance = new Xiaorui();
    // 假设您有地图初始化代码
    // this.xiaoruiInstance.map = yourMapInstance;
    // this.xiaoruiInstance.graphicLayer = yourGraphicLayer;
    
    // 监听外部WebSocket消息
    EventBus.on('ExternalWebSocket-Message', (payload) => {
      this.handleExternalWebSocketMessage(payload.data);
    });
  },
  
  methods: {
    // 处理外部WebSocket消息
    handleExternalWebSocketMessage(data) {
      if (this.xiaoruiInstance) {
        this.xiaoruiInstance.加载外部WebSocket设备标注(data);
      }
    },
    
    // 移除设备标注
    removeDevice(deviceSn) {
      if (this.xiaoruiInstance) {
        this.xiaoruiInstance.removeExternalDeviceAnnotation(deviceSn);
      }
    },
    
    // 清除所有设备标注
    clearAllDevices() {
      if (this.xiaoruiInstance) {
        this.xiaoruiInstance.clearAllExternalDeviceAnnotations();
      }
    }
  }
};
</script>
```

## 功能特性

### 1. 自动设备类型识别
- 根据数据格式自动识别设备类型（无人车/无人机）
- 为不同设备类型使用不同的图标和样式

### 2. 实时位置更新
- 支持设备位置的实时更新
- 自动同步侦察范围位置

### 3. 在线状态显示
- 根据设备在线状态显示不同颜色
- 在线设备：绿色高亮
- 离线设备：红色高亮

### 4. 侦察范围显示
- 自动从设备列表获取侦察范围数据
- 支持右键切换侦察范围显示/隐藏
- 流动边框效果

### 5. 设备信息标签
- 显示设备名称和序列号
- 支持距离显示条件（50km内可见）
- 带背景的标签样式

## 注意事项

1. **地图实例初始化**: 确保在调用标注方法前，Xiaorui实例的地图和图形图层已正确初始化。

2. **数据格式兼容**: 新方法支持多种数据格式，但主要针对您提供的外部WebSocket数据格式进行了优化。

3. **设备图标**: 确保`/src/assets/icons/car.png`文件存在，用于无人车图标显示。

4. **内存管理**: 使用`removeExternalDeviceAnnotation`和`clearAllExternalDeviceAnnotations`方法及时清理不需要的标注，避免内存泄漏。

5. **错误处理**: 所有方法都包含错误处理，建议在生产环境中添加适当的日志记录。

## 调试建议

1. 在浏览器控制台中查看相关日志输出
2. 使用`getExternalDeviceAnnotations()`方法检查当前标注状态
3. 确保WebSocket数据格式符合预期
4. 检查地图实例和图形图层的初始化状态

## 扩展功能

如果需要添加更多功能，可以考虑：

1. 添加设备轨迹显示
2. 支持更多设备类型
3. 添加设备信息弹窗
4. 支持设备分组显示
5. 添加设备搜索和过滤功能