# 工业级3D数字孪生仓库管理系统

**Repository Path**: xiaoshi_love/xyck

## Basic Information

- **Project Name**: 工业级3D数字孪生仓库管理系统
- **Description**: 基于 **Vue3 + Three.js + Element Plus** 实现的工业级3D数字孪生仓库可视化管理系统，真实还原仓库场景，支持实时交互、货架配置、货物管理和性能优化。

**核心亮点**：

- 🎨 真实3D可视化效果
- ⚙️ 灵活的货架配置（层数、列数自定义）
- 📦 完整的货物管理系统
- 🚀 支持1000+货架的性能优化
- 📊 实时性能监控面板

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-27
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🏭 工业级3D数字孪生仓库管理系统

## 📖 项目介绍

基于 **Vue3 + Three.js + Element Plus** 实现的工业级3D数字孪生仓库可视化管理系统，真实还原仓库场景，支持实时交互、货架配置、货物管理和性能优化。

**核心亮点**：

- 🎨 真实3D可视化效果
- ⚙️ 灵活的货架配置（层数、列数自定义）
- 📦 完整的货物管理系统
- 🚀 支持1000+货架的性能优化
- 📊 实时性能监控面板

***

## 🎯 核心功能

### 1️⃣ 3D可视化

- ✅ **真实3D场景** - Three.js渲染引擎，支持阴影、光照、雾效
- ✅ **立体货架模型** - 程序化生成货架，支持多层结构
- ✅ **货物堆叠效果** - 3D货物盒子，随机堆叠展示
- ✅ **分区可视化** - 固定货架区、可移动货架区、分拣区、通道区
- ✅ **状态指示灯** - 满货(绿)、部分(橙)、空货(灰)

### 2️⃣ 货架配置

- ✅ **层数配置** - 支持1-8层自由配置
- ✅ **列数配置** - 支持1-8列自由配置
- ✅ **容量计算** - 自动计算总容量（层数×列数）
- ✅ **位置设置** - X/Z坐标自定义
- ✅ **状态选择** - 满货/部分/空货
- ✅ **实时添加** - 即时添加到3D场景

### 3️⃣ 货架详情

- ✅ **3D独立展示** - 货架单独渲染，可旋转查看
- ✅ **层位详情** - 显示每一层的所有列位
- ✅ **货物预览** - 每个货位显示货物信息
- ✅ **空位标识** - 空位清晰标注
- ✅ **状态颜色** - 满货(绿)、部分(橙)、空货(灰)

### 4️⃣ 货物管理

- ✅ **货物信息** - 名称、SKU、数量
- ✅ **位置信息** - 第几层第几列
- ✅ **入库时间** - 显示入库日期
- ✅ **状态显示** - 货物状态可视化
- ✅ **详细描述** - 货物详细信息

### 5️⃣ 性能优化

- ✅ **InstancedMesh** - 实例化渲染，支持1000+货架
- ✅ **性能监控** - 实时FPS、Draw Calls、三角形数量
- ✅ **性能测试** - 100-5000货架压力测试
- ✅ **视锥体剔除** - 只渲染可见物体
- ✅ **材质优化** - Lambert材质提升性能

***

## 🛠️ 技术栈

| 层级     | 技术选型                    | 核心作用           |
| ------ | ----------------------- | -------------- |
| 3D引擎   | **Three.js**            | 场景渲染、模型生成、交互控制 |
| 前端框架   | Vue 3 + Composition API | 业务逻辑、状态管理      |
| UI组件   | Element Plus            | 界面组件、交互反馈      |
| 状态管理   | Pinia                   | 全局状态、数据共享      |
| HTTP请求 | Axios                   | API接口调用        |
| 构建工具   | Vite                    | 快速开发、热更新       |

***

## 📁 项目结构

```
frontend/
├── src/
│   ├── components/
│   │   ├── WarehouseScene3D.vue          # 3D场景组件
│   │   ├── WarehouseScene3DOptimized.vue # 优化版场景组件
│   │   ├── ShelfDetailDialog.vue         # 货架详情弹窗
│   │   └── GoodsDetailDialog.vue         # 货物详情弹窗
│   ├── views/
│   │   └── WarehouseView.vue             # 主页面
│   ├── store/
│   │   └── warehouse.js                  # Pinia状态管理
│   ├── api/
│   │   └── index.js                      # API接口定义
│   ├── utils/
│   │   └── request.js                    # Axios封装
│   ├── App.vue
│   └── main.js
├── index.html
├── vite.config.js
├── package.json
├── README.md
└── 性能优化方案.md                       # 性能优化详细文档
```

***

## 🚀 快速开始

### 安装依赖

```bash
cd frontend
npm install
```

### 启动开发服务器

```bash
npm run dev
```

访问 **<http://localhost:3000>** 查看效果

### 构建生产版本

```bash
npm run build
```

***

## 🎮 操作指南

### 基础操作

| 操作         | 功能       |
| ---------- | -------- |
| 🖱️ 鼠标左键拖拽 | 旋转视角     |
| 🖱️ 鼠标右键拖拽 | 平移视角     |
| 🖱️ 鼠标滚轮   | 缩放视角     |
| 📦 点击货架    | 查看货架基本信息 |
| 📋 点击列表项   | 定位到对应货架  |

### 功能流程

#### 添加货架

```
1. 点击"添加货架"按钮
2. 配置层数（1-8层）
3. 配置列数（1-8列）
4. 查看自动计算的容量
5. 设置位置和状态
6. 点击"确定添加"
```

#### 查看货架详情

```
1. 在3D场景中点击货架
2. 点击"查看详情"按钮
3. 左侧：3D货架独立展示（可旋转）
4. 右侧：每层每列货物列表
5. 点击货物查看详细信息
```

#### 性能测试

```
1. 点击"性能测试"按钮
2. 选择货架数量（100-5000）
3. 选择优化模式（普通/实例化）
4. 点击"开始测试"
5. 观察性能面板数据
```

***

## 📊 数据结构

### 货架数据

```javascript
{
  id: 1,
  name: 'A-01',        // 货架编号
  x: -25,              // X坐标
  z: -25,              // Z坐标
  level: 4,            // 层数
  columns: 3,          // 列数
  capacity: 12,        // 容量（层数×列数）
  status: 'full'       // 状态: full/partial/empty
}
```

### 货物数据

```javascript
{
  id: '1-1-1',
  name: '电子元件-11',  // 货物名称
  sku: 'SKU0101',       // SKU编码
  quantity: 50,         // 数量
  level: 1,             // 第1层
  column: 1,            // 第1列
  status: 'full',       // 状态
  inTime: '2024/1/15',  // 入库时间
  detail: '详细信息...'  // 详细描述
}
```

### 统计数据

```javascript
{
  totalShelves: 7,      // 货架总数
  utilization: 78,      // 空间利用率(%)
  fullShelves: 4,       // 满货货架数
  emptyShelves: 1       // 空货架数
}
```

***

## 🎨 核心功能实现

### 1. 3D场景搭建

```javascript
// 创建场景
scene = new THREE.Scene()
scene.background = new THREE.Color(0x0a0a1a)
scene.fog = new THREE.Fog(0x0a0a1a, 50, 200)

// 创建相机
camera = new THREE.PerspectiveCamera(60, width/height, 0.1, 1000)
camera.position.set(40, 30, 40)

// 创建渲染器
renderer = new THREE.WebGLRenderer({ antialias: true })
renderer.shadowMap.enabled = true
renderer.toneMapping = THREE.ACESFilmicToneMapping
```

### 2. 货架模型生成

```javascript
// 程序化生成货架
const createShelf = (data) => {
  const group = new THREE.Group()
  
  // 根据列数计算宽度
  const shelfWidth = data.columns * 1.2
  
  // 立柱
  const pillarGeometry = new THREE.BoxGeometry(0.15, height, 0.15)
  
  // 层板
  const boardGeometry = new THREE.BoxGeometry(shelfWidth, 0.1, depth)
  
  // 货物
  const goodsBox = createGoodsBox()
  
  return group
}
```

### 3. 性能优化

```javascript
// InstancedMesh 实例化渲染
const pillarMesh = new THREE.InstancedMesh(
  pillarGeometry,
  material,
  shelfCount * 4  // 所有货架的立柱
)

// 设置每个实例的位置
const matrix = new THREE.Matrix4()
shelfDataList.forEach((shelf, index) => {
  matrix.setPosition(shelf.x, shelf.y, shelf.z)
  pillarMesh.setMatrixAt(index, matrix)
})

// 一次Draw Call渲染所有立柱
scene.add(pillarMesh)
```

***

## ⚡ 性能优化

### ⚠️ 重要限制

**最大实例数量：500个货架**

由于WebGL着色器uniform变量限制（MAX\_FRAGMENT\_UNIFORM\_VECTORS=1024），系统限制最大实例数量为500个货架。超过此数量可能导致：

- 着色器编译失败
- 页面崩溃
- 性能严重下降

### 性能对比

| 货架数量  | 普通模式 FPS | 优化模式 FPS | Draw Calls | 状态    |
| ----- | -------- | -------- | ---------- | ----- |
| 100个  | 60       | 60       | 900 → 3    | ✅ 推荐  |
| 300个  | 30-40    | 60       | 2700 → 3   | ✅ 流畅  |
| 500个  | 15-20    | 60       | 4500 → 3   | ⚠️ 限制 |
| >500个 | 不支持      | 自动限制     | -          | ❌ 超限  |

### 优化措施

1. **实例数量限制** - 最多500个实例，避免着色器错误
2. **Passive事件** - 使用passive事件监听器，减少延迟
3. **异步处理** - 使用requestAnimationFrame优化点击处理
4. **材质优化** - Lambert材质替代Standard材质
5. **阴影优化** - 默认关闭阴影，提升性能
6. **像素比限制** - 最大2倍，避免高分屏卡顿

### 性能建议

- ✅ **货架 ≤ 300**：最佳性能，推荐使用
- ⚡ **货架 300-500**：可接受性能，达到限制
- ❌ **货架 > 500**：不支持，需分页处理

**详细说明**：查看 [性能问题修复说明.md](./性能问题修复说明.md)

详细优化方案请查看：[性能优化方案.md](./性能优化方案.md)

***

## 🔧 后端接口

后端接口地址配置在 `vite.config.js` 中，默认代理到 `http://localhost:8080`

### API列表

| 接口                        | 方法   | 说明      |
| ------------------------- | ---- | ------- |
| `/api/warehouse/list`     | GET  | 获取仓库列表  |
| `/api/warehouse/{id}`     | GET  | 获取仓库详情  |
| `/api/shelf/list`         | GET  | 获取货架列表  |
| `/api/shelf/saveOrUpdate` | POST | 保存/更新货架 |
| `/api/goods/list`         | GET  | 获取商品列表  |
| `/api/goods/{id}`         | GET  | 获取商品详情  |

***

## 🎯 功能演示

### 货架配置

![货架配置](./docs/shelf-config.png)

### 货架详情

![货架详情](./docs/shelf-detail.png)

### 货物详情

![货物详情](./docs/goods-detail.png)

### 性能监控

![性能监控](./docs/performance.png)

***

## 📝 开发说明

### 扩展开发

1. **添加新模型** - 在 `createShelf()` 中扩展
2. **添加新交互** - 在 `onMouseClick()` 中处理
3. **添加新效果** - 使用 Three.js 后期处理
4. **添加新功能** - 在 `WarehouseView.vue` 中扩展

### 代码规范

- 使用 Vue 3 Composition API
- 遵循 ESLint 规则
- 组件命名采用 PascalCase
- 函数命名采用 camelCase

***

## 🎯 未来规划

- [ ] 加载GLTF/GLB模型文件
- [ ] 添加叉车、传送带等设备
- [ ] 实现WebSocket实时数据同步
- [ ] 添加后期处理效果(辉光、抗锯齿)
- [ ] 实现3D标签广告牌
- [ ] 添加路径规划功能
- [ ] 支持VR/AR模式
- [ ] 实现货架拖拽移动
- [ ] 添加库存预警功能
- [ ] 支持多仓库管理

***

## 📄 许可证

本项目采用 **自定义开源许可证（非商业 Copyleft 协议）**

### 主要条款：

- ✅ **免费使用** - 非商业用途免费使用
- ❌ **禁止商业** - 不得用于任何商业用途
- 🔄 **Copyleft** - 衍生作品必须开源
- 📧 **通知义务** - 使用前需通过 3477998948@qq.com 告知

### 使用要求：

1. 非商业性使用、复制、修改和分发
2. 衍生作品必须以相同条款开源
3. 必须标注原始作者和仓库地址
4. 使用前需邮件通知作者

**完整协议**：查看 [LICENSE](./LICENSE) 文件

**联系方式**：3477998948@qq.com

***

## 🤝 技术支持

如有问题请：

- 提交 Issue
- 查看文档：[性能优化方案.md](./性能优化方案.md)
- 联系开发团队：<3477998948@qq.com>：

***

**Made with ❤️ by Warehouse Management Team**

\## 许可证说明 本项目使用自定义非商业 Copyleft 协议。 - ❌ 禁止商业使用 - ✅ 衍生作品必须开源并遵守本协议 - ✅ 使用时必须通知作者并引用原始仓库地址 详见 \[LICENSE]\(./LICENSE) 文件