库存3D查看器 (stockChat) 设计文档

1. 概述

功能名称：库存3D仓库查看器 (stockChat)
文件路径：WIDESEA_WMSClient/src/views/stock/stockChat.vue
核心功能：使用 Three.js + WebGL 实现仓库3D可视化，用户可在3D场景中巡视仓库、查看货位状态、点击货位查看库存详情
目标用户：仓库管理员、调度人员、质检人员

2. 技术选型

技术	选型	说明
3D引擎	Three.js	WebGL 主流库，Vue 3 友好
渲染策略	InstancedMesh	批量渲染大量货位，单次 drawcall
状态管理	Vue 3 Composition API	`ref/reactive`
UI组件	Element Plus	与项目现有技术栈一致
实时通信	SignalR	与后端 WebSocket 配合实现库存动态更新

3. 功能需求

3.1 核心功能

仓库3D布局展示

全部货位均渲染，按状态着色
货架式排列，包含巷道
地面网格背景

多仓库 Tab 切换

Element Plus Tabs 组件
每个仓库独立加载数据
Tab 切换时重置3D场景

货位点击详情弹窗

全屏 Dialog 展示
显示：货位信息、库存状态、托盘编号、物料明细列表
支持查看批次、保质期预警

3D场景交互

鼠标旋转（OrbitControls）
滚轮缩放
中键平移
点击货位高亮 + 相机聚焦

实时库存状态更新

SignalR 监听库存变化
货位颜色动态更新

筛选过滤

按物料类型/批次/库存状态过滤
高亮显示匹配货位

状态图例

右上角/底部颜色图例
说明每种颜色代表的货位状态

3.2 货位状态颜色编码（颜色优先级：locationStatus > stockStatus）

颜色判定规则（按优先级顺序）：

locationStatus = 3（禁用） → 深灰 #2d2d2d（最高优先级）
locationStatus = 2（锁定） → 红色 #F56C6C
locationStatus = 1（占用）且 stockStatus = 0（无货） → 暗灰 #4a4a4a
locationStatus = 1（占用）且 stockStatus = 1（有货） → 蓝色 #409EFF
locationStatus = 1（占用）且 stockStatus = 2（库存紧张 <10%） → 橙色 #E6A23C
locationStatus = 1（占用）且 stockStatus = 3（已满 ≥90%） → 绿色 #67C23A
locationStatus = 0（空） → 暗灰 #4a4a4a

阈值定义：
- 库存紧张：stockQuantity / maxCapacity < 10%
- 已满：stockQuantity / maxCapacity ≥ 90%

4. 后端 API

4.1 新增接口

GET /api/StockInfo/Get3DLayout?warehouseId={id}

响应结构：
json { "status": true, "data": { "warehouseId": 1, "warehouseName": "主仓库", "maxRow": 10, "maxColumn": 20, "maxLayer": 5, "materielCodeList": ["M001", "M002", "M003"], "batchNoList": ["B20260301", "B20260302"], "locations": [ { "locationId": 1, "locationCode": "A-01-02-03", "row": 1, "column": 2, "layer": 3, "locationStatus": 0, "stockStatus": 2, "stockQuantity": 50, "maxCapacity": 100, "palletCode": "PLT-001", "materielCode": "M001", "materielName": "物料A", "batchNo": "B20260301" } ] } }

说明：
- locationStatus: 0=空, 1=占用, 2=锁定, 3=禁用
- stockStatus: 0=无货, 1=有货, 2=库存紧张, 3=已满
- maxCapacity: 货位最大容量（用于计算填充率）
- materielCodeList: 当前仓库所有物料编号列表（用于筛选下拉）
- batchNoList: 当前仓库所有批次号列表（用于筛选下拉）
- 颜色判定在前端实现：后端返回 stockQuantity 和 maxCapacity，前端按 3.2 规则计算颜色

4.2 SignalR 实时推送

Hub 路径：/stockHub

推送事件：
javascript // 库存变化事件 stockUpdated: { locationId, warehouseId, stockQuantity, stockStatus }

5. 前端文件结构

WIDESEA_WMSClient/src/
├── views/stock/
│   └── stockChat.vue              # 主页面组件
├── extension/stock/
│   └── stockChat.js               # ViewGrid 扩展配置
└── api/
    └── http.js                    # 复用现有 http 封装

6. 组件结构 (stockChat.vue)

<template>
  <div class="stock-chat-container">
    <!-- 仓库 Tabs -->
    <el-tabs v-model="activeWarehouse" @tab-change="onWarehouseChange">
      <el-tab-pane
        v-for="wh in warehouseList"
        :key="wh.warehouseId"
        :label="wh.warehouseName"
        :name="wh.warehouseId"
      />
    </el-tabs>

    <!-- 工具栏 -->
    <div class="toolbar">
      <el-select v-model="filterStockStatus" placeholder="库存状态筛选" clearable>
        <el-option label="有货" :value="1" />
        <el-option label="库存紧张" :value="2" />
        <el-option label="已满" :value="3" />
      </el-select>
      <el-select v-model="filterMaterielCode" placeholder="物料筛选" clearable>
        <el-option v-for="code in materielCodeList" :key="code" :label="code" :value="code" />
      </el-select>
      <el-select v-model="filterBatchNo" placeholder="批次筛选" clearable>
        <el-option v-for="batch in batchNoList" :key="batch" :label="batch" :value="batch" />
      </el-select>
      <el-button @click="resetCamera">重置视角</el-button>
    </div>

    <!-- 3D Canvas -->
    <div ref="canvasContainer" class="canvas-container" />

    <!-- 状态图例 -->
    <div class="legend">
      <div v-for="item in legendItems" :key="item.status" class="legend-item">
        <span class="color-box" :style="{ background: item.color }" />
        <span>{{ item.label }}</span>
      </div>
    </div>

    <!-- 详情弹窗 -->
    <el-dialog v-model="detailDialogVisible" title="库存详情" fullscreen>
      <!-- 详情内容 -->
    </el-dialog>
  </div>
</template>

7. Three.js 场景设计

7.1 初始化流程

创建 WebGLRenderer，挂载到 canvasContainer
创建 PerspectiveCamera（透视相机）
创建 Scene 场景
添加光照（环境光 + 定向光）
创建地面（PlaneGeometry + 网格材质）
创建货架货位（InstancedMesh）
添加 OrbitControls 控制器
启动渲染循环

7.2 货位定位算法

x = (column - maxColumn/2) * CELL_SIZE_X
y = layer * CELL_SIZE_Y
z = (row - maxRow/2) * CELL_SIZE_Z

7.3 点击拾取

使用 Raycaster 进行射线检测
通过 instanceId 识别被点击的货位实例
高亮：临时替换材质颜色

7.4 相机聚焦动画

使用简单线性插值（lerp）平滑移动相机
目标位置：货位坐标 + 偏移量
插值公式：camera.position.lerp(target, 0.05) 每帧执行

8. 性能优化

策略	说明
InstancedMesh	单次 drawcall 渲染所有货位
视锥体剔除	相机外的货位不渲染
颜色缓存	材质复用，避免频繁创建
requestAnimationFrame	渲染循环使用 RAF
数据分页	大仓库可考虑按区域分片加载

9. 路由注册

在 viewGird.js 中注册路由：
javascript { path: '/stockChat', name: 'stockChat', component: () => import('@/views/stock/stockChat.vue') }