web-map/docs/库位功能逻辑分析.md

库位功能逻辑分析

1. 概述

本文档旨在详细解析项目中“库位”(Storage Location)功能的实现逻辑。该功能的核心目标是实时监控与地图中“动作点”关联的库位状态，并将这些状态直观地反馈在前端界面上，包括更新画布上点的边框颜色和在详情卡片中展示详细的库位信息。

整个功能逻辑主要由 StorageLocationService 服务和 PointDetailCard UI组件协作完成，数据通过 WebSocket 从后端实时推送。

2. 核心服务: StorageLocationService

StorageLocationService 是库位管理的中枢，封装了所有核心业务逻辑。它在 movement-supervision.vue 页面中被实例化和管理。

文件路径: src/services/storage-location.service.ts

主要职责

1. WebSocket 通信:

   • 通过调用 @api/scene 中的 monitorStorageLocationById 方法，建立一个 WebSocket 连接来接收实时的库位状态更新。
   • 连接建立后，会主动向后端请求一次全量的库位状态数据。

2. 数据处理与状态管理:

   • 维护一个核心数据结构 storageLocations: Ref<Map<string, StorageLocationInfo[]>>。这是一个响应式的 Map，其中：
     • key: 画布中“动作点”的 ID (pointId)。
     • value: 一个数组，包含所有绑定到该动作点的库位信息 (StorageLocationInfo[])。
   • 通过 handleStorageLocationUpdate 方法处理来自 WebSocket 的两种消息：
     • storage_location_update: 用于全量更新所有库位信息。
     • storage_location_status_change: 用于更新单个库位的状态，实现增量更新。

3. 与编辑器 (EditorService) 的交互:

   • ID 映射: 通过 buildStationToPointIdMap 方法，将后端数据中的 station_name (如 "AP9") 与画布中“动作点”的唯一 id (如 "3351") 进行映射。这是连接后端逻辑与前端视觉呈现的关键桥梁。
   • 视觉状态更新: 实现 updatePointBorderColor 方法，根据一个点所关联的所有库位的占用状态 (is_occupied)，动态更新该点在画布上的边框颜色：
     • 全部占用: 红色 (#ff4d4f)
     • 部分或全部未占用: 绿色 (#52c41a)

对外接口

• getLocationsByPointId(pointId: string): 向外部组件提供一个接口，用于根据“动作点”的 ID 获取其关联的所有库位的详细信息数组。

3. UI 展示: PointDetailCard

当用户在 movement-supervision.vue 页面中选中一个“动作点”时，PointDetailCard 组件会负责展示该点的详细信息，其中就包括了库位的实时状态。

文件路径: src/components/card/point-detail-card.vue

主要职责

1. 接收数据:

   • 通过 props 从父组件接收 storageLocations 数组。该数组的数据源是 StorageLocationService.getLocationsByPointId() 方法的返回值。

2. 渲染库位状态:

   • 遍历 storageLocations 数组，为每一个库位渲染一个信息块。
   • 使用 getStorageStatusTag 方法，根据库位的多个布尔状态 (is_occupied, is_locked, is_disabled, is_empty_tray)，生成对应文本（如“已占用”、“未锁定”）和颜色样式的标签，为用户提供清晰、直观的状态反馈。

4. 数据流转图

下面的流程图清晰地展示了从后端数据推送到前端UI渲染的完整过程。

sequenceDiagram
    participant Backend as Backend (WebSocket)
    participant StorageLocationService as StorageLocationService
    participant MovementSupervision as movement-supervision.vue
    participant PointDetailCard as PointDetailCard
    participant EditorService as EditorService (Canvas)

    MovementSupervision->>StorageLocationService: new StorageLocationService(editor, sceneId)
    MovementSupervision->>StorageLocationService: startMonitoring()
    StorageLocationService->>Backend: 建立 WebSocket 连接
    Backend-->>StorageLocationService: 推送库位状态消息 (JSON)

    StorageLocationService->>StorageLocationService: handleStorageLocationUpdate(message)
    StorageLocationService->>EditorService: buildStationToPointIdMap() <br> (获取点位ID与站点名称映射)
    StorageLocationService->>StorageLocationService: 更新内部 storageLocations Map
    StorageLocationService->>EditorService: updatePointBorderColor(pointId, color) <br> (更新画布点的边框颜色)

    Note right of MovementSupervision: 用户点击一个动作点
    MovementSupervision->>StorageLocationService: getLocationsByPointId(current.id)
    StorageLocationService-->>MovementSupervision: 返回库位信息数组
    MovementSupervision->>PointDetailCard: :storage-locations="locations"

    PointDetailCard->>PointDetailCard: 渲染库位名称和状态标签

5. 关联文件清单

• src/pages/movement-supervision.vue:
  • 角色: 核心页面。负责实例化和管理 StorageLocationService 的生命周期，并将获取到的库位数据传递给 PointDetailCard。
• src/services/storage-location.service.ts:
  • 角色: 核心服务。处理所有与库位相关的业务逻辑，包括数据获取、状态管理和与画布的交互。
• src/components/card/point-detail-card.vue:
  • 角色: UI组件。负责展示单个动作点所绑定的库位的详细状态信息。
• src/apis/scene/api.ts:
  • 角色: API定义。包含 monitorStorageLocationById 方法，用于发起 WebSocket 连接请求。
• src/core/editor.service.ts:
  • 角色: 编辑器服务。StorageLocationService 依赖此服务来获取画布中的点位信息并更新其视觉样式。