From 7f761ceaad5538e2ff629c8c08475653675198ec Mon Sep 17 00:00:00 2001
From: xudan <staysky25@outlook.com>
Date: Fri, 18 Jul 2025 17:34:29 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E5=BA=93=E4=BD=8D?=
 =?UTF-8?q?=E5=8A=9F=E8=83=BD=E9=80=BB=E8=BE=91=E5=88=86=E6=9E=90=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=EF=BC=8C=E8=AF=A6=E7=BB=86=E6=8F=8F=E8=BF=B0=E5=BA=93?=
 =?UTF-8?q?=E4=BD=8D=E7=8A=B6=E6=80=81=E7=9B=91=E6=8E=A7=E5=8F=8AUI?=
 =?UTF-8?q?=E5=B1=95=E7=A4=BA=E6=B5=81=E7=A8=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/库位功能逻辑分析.md | 98 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 docs/库位功能逻辑分析.md

diff --git a/docs/库位功能逻辑分析.md b/docs/库位功能逻辑分析.md
new file mode 100644
index 0000000..e651485
--- /dev/null
+++ b/docs/库位功能逻辑分析.md
@@ -0,0 +1,98 @@
+# 库位功能逻辑分析
+
+## 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渲染的完整过程。
+
+```mermaid
+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` 依赖此服务来获取画布中的点位信息并更新其视觉样式。