# warehouse-3d

**Repository Path**: sanzk/warehouse-3d

## Basic Information

- **Project Name**: warehouse-3d
- **Description**: 自动化立体库3D显示
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-27
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 3D立体库货位管理系统

## 📦 项目概述

本系统是一个基于React + Three.js + SQLite的3D立体仓库货位管理系统，支持实时3D可视化和数据持久化存储。

## 🚀 技术栈

### 前端
- React 18
- Vite
- Three.js
- @react-three/fiber
- @react-three/drei

### 后端
- Node.js
- Express
- sql.js (纯JavaScript SQLite实现)
- CORS

## 📁 项目结构

```bash
warehouse-3d/
├── client/                 # 前端应用
│   ├── src/
│   │   ├── components/          # React组件
│   │   ├── services/            # API服务
│   │   ├── utils/               # 工具函数
│   │   └── App.jsx              # 主应用
│   └── package.json             # 前端依赖
├── server/                 # 后端服务
│   ├── server.js                # Express服务器
│   ├── db-modules/              # 数据库模型模块
│   ├── queue-client.js          # 队列客户端
│   └── package.json             # 后端依赖
├── database-service/       # 数据库服务
│   ├── index.js                 # 服务工厂
│   ├── db-interface.js          # 数据库接口
│   ├── sqlite-service.js        # SQLite实现
│   └── package.json             # 数据库服务依赖
├── queue-service/          # 队列服务
│   ├── queue-service.js         # 队列服务主文件
│   ├── queue-manager.js         # 队列管理器
│   └── package.json             # 队列服务依赖
├── plc-service/            # PLC服务
│   ├── plc-server.js            # PLC服务主文件
│   ├── plc-service.js           # PLC服务逻辑
│   └── plc/s7-connector.js      # S7连接器
├── node-red-integration/   # Node-RED集成
│   ├── index.js                 # Node-RED服务
│   └── .node-red/               # Node-RED配置
├── bat/                    # 批处理脚本目录
│   ├── install.bat              # 安装依赖脚本
│   └── start-services.bat       # 启动服务脚本
├── start-services-background.bat  # 后台启动服务脚本
└── close-all-services.bat    # 关闭所有服务脚本
```

## 🛠️ 安装和运行

### 0. 准备工作
- 设置执行策略以允许PowerShell脚本运行：`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`

### 1. 自动安装依赖

双击 [bat/install.bat](./bat/install.bat) 文件，脚本将自动检查环境并安装所有依赖。

### 2. 手动安装依赖

```bash
# 安装前端依赖
cd client
npm install

# 安装后端依赖
cd ../server
npm install

# 安装数据库服务依赖
cd ../database-service
npm install

# 安装队列服务依赖
cd ../queue-service
npm install

# 安装PLC服务依赖
cd ../plc-service
npm install

# 安装规则引擎依赖
cd ../rules-engine
npm install

# 安装Node-RED依赖
cd ../node-red-integration
npm install
```

## 🌐 访问地址

- **前端界面**: http://localhost:5175
- **后端API**: http://localhost:3001
- **PLC服务**: http://localhost:3002
- **队列服务**: http://localhost:3003
- **规则引擎**: http://localhost:3004
- **Node-RED**: http://localhost:1880
- **Node-RED Dashboard**: http://localhost:1880/api/ui
- **数据库文件**: warehouse-3d/server/warehouse.db

## 🔐 安全配置

### Node-RED凭证加密
为了保护流程中的敏感信息，Node-RED使用凭证加密功能。系统已配置自定义凭证密钥：
```bash
credentialSecret: "warehouse-system-secret-key"
```

如需更换密钥，请修改[node-red-integration/index.js](./node-red-integration/index.js)中的配置并重新部署流程。

## 📚 文档资源

### 系统文档
- [API文档](docs/API_DOCUMENTATION.md) - 系统所有API接口详细说明
- [Node-RED教程](docs/NODE_RED_TUTORIAL.md) - Node-RED集成和使用指南
- [队列服务使用说明](docs/QUEUE_SERVICE_USAGE.md) - 任务队列服务的使用方法
- [PLC并发访问问题及解决方案](docs/PLC_CONCURRENCY_ISSUE.md) - PLC并发访问冲突问题的技术说明
- [PLC控制面板模块化复用说明](docs/PLC_PANEL_MODULARIZATION.md) - PLC控制面板模块化设计和复用实现
- [联表查询功能调试记录](docs/JOINT_TABLE_QUERY_DEBUG.md) - 联表查询功能的调试过程和解决方案
- [模块化复用开发指南](docs/MODULE_REUSE_GUIDE.md) - 创建独立model和前端页面的标准流程

### 界面截图展示

下面是系统各主要界面的截图展示，帮助用户更好地理解和使用系统。

#### 主页3D画面
![主页3D画面](README/主页3D画面.png)

系统主界面展示了3D立体仓库的实时可视化效果，用户可以通过鼠标交互来旋转、缩放和平移视角。

#### PLC控制中心
![PLC控制中心](README/PLC控制中心.png)

PLC控制中心提供了对西门子PLC设备的实时监控和控制功能，支持变量读写操作。

#### 低代码开发环境
![低代码开发](README/低代码开发.png)

集成的Node-RED低代码开发环境，用户可以通过可视化流程设计实现复杂的业务逻辑。

#### 服务架构图
![服务架构](README/服务.png)

系统采用微服务架构，包含前端界面、PLC服务、队列服务、规则引擎和Node-RED等多个服务组件。

#### 队列服务监控
![队列服务](README/队列.png)

队列服务监控界面展示了当前任务队列的状态，包括待处理任务数和处理状态。

#### 队列历史记录
![队列历史](README/队列历史.png)

队列历史记录界面展示了已完成任务的历史信息，便于用户追踪和分析任务执行情况。

### 配置文件
- [仓库配置](public/warehouse-config.json) - 系统基础配置参数
- [PLC配置](public/plc-config.json) - PLC变量配置
- [PLC分组配置](public/plc-groups/) - PLC变量分组配置

### 问题解决方案
- [批处理脚本编码问题解决方案](README/BATCH_SCRIPT_ENCODING_FIX.md) - 解决批处理脚本中文乱码问题的技术说明

## 📡 API接口

### 基础URL
```bash
http://localhost:3001/api
```

### 接口列表

#### 1. 获取所有货位
```bash
GET /slots
```

#### 2. 获取单个货位详情
```bash
GET /slots/:slotId
```

#### 3. 初始化货位数据
```bash
POST /slots/init
Body: {
  rows: 5,
  columns: 8,
  layers: 4,
  slots: { ... }
}
```

#### 4. 更新货位状态
```bash
PUT /slots/:slotId
Body: {
  hasGoods: true/false,
  goodsInfo: {
    name: "货物名称",
    quantity: 100,
    weight: "500 kg",
    entryDate: "2025-10-25"
  }
}
```

#### 5. 获取统计信息
```bash
GET /statistics
```

#### 6. 健康检查
```bash
GET /health
```

## 💡 功能特性

### 1. 数据持久化
- ✅ 所有货位和货物数据自动保存到SQLite数据库
- ✅ 系统重启后数据不丢失
- ✅ 支持数据导入导出

### 2. 3D可视化
- ✅ 实时3D场景渲染
- ✅ 货位颜色状态区分
- ✅ 鼠标交互(旋转/缩放/平移)
- ✅ 点击查看货位详情

### 3. 数据管理
- ✅ 刷新数据同步
- ✅ 重新初始化数据库
- ✅ 统计信息实时更新

### 4. 任务队列
- ✅ 异步任务处理
- ✅ 重试机制
- ✅ 回调支持
- ✅ 手动添加任务到队列（不自动判断）
- ✅ 统一管理数据库和PLC操作

### 5. PLC集成
- ✅ 实时PLC变量监控
- ✅ PLC变量读写控制
- ✅ 分组管理PLC变量
- ✅ 解决并发访问冲突
- ✅ 通过队列服务统一管理PLC操作

### 6. 界面布局
- 📊 **顶部**: 系统标题和数据库状态
- 🎮 **右上**: 数据操作控制面板
- 🖼️ **中心**: 3D立体库场景
- 📈 **左下**: 统计信息面板
- 📋 **右侧**: 货位详情面板(点击时显示)

## 🎯 使用说明

### 首次运行
1. 系统启动时自动检测数据库
2. 如果数据库为空,自动生成初始数据
3. 系统会优先从配置文件加载默认参数

### 配置文件
系统支持通过配置文件设置默认参数，配置文件位于`public/warehouse-config.json`：
```json
{
  "rows": 5,
  "columns": 8,
  "layers": 4,
  "goodsRate": 70
}
```
- `rows`: 货架排数
- `columns`: 每排货位列数
- `layers`: 货架层数
- `goodsRate`: 货物占用比例(0-100%)

### 操作指南
1. **查看货位**: 点击3D场景中的货位方块
2. **刷新数据**: 点击"刷新数据"按钮同步最新数据
3. **重新初始化**: 点击"重新初始化"清空并重建数据
4. **查看统计**: 左下角面板显示实时统计信息
5. **编辑货位**: 在货位详情面板中点击"编辑"按钮
6. **修改配置**: 在右上角控制面板中调整参数并点击"应用配置"

### 数据状态
- 🟢 **浅蓝色方块**: 有货
- ⚪ **透明白色方块**: 空闲
- 🔵 **蓝色方块**: 选中
- 🟠 **橙色货物**: 货位中的货物

## 🐛 故障排查

### 问题1: 无法连接到数据库
- 检查后端服务是否启动(端口3001)
- 查看控制台是否显示"🗄️ 数据库已连接"

### 问题2: 数据未保存
- 确认后端API服务正常运行
- 检查network标签页的API请求状态

### 问题3: 3D场景无法显示
- 确保浏览器支持WebGL
- 检查控制台是否有Three.js错误

### 问题4: PLC服务启动失败
- 检查PLC服务日志文件，查看是否有"module not found"错误
- 进入plc-service目录，运行`npm install`重新安装依赖
- 确认Node.js版本兼容性(建议使用v16+)

### 问题5: 服务无法启动或意外退出
- 检查端口是否被占用
- 查看各服务日志文件(node-red.log, plc-service.log等)
- 确认所有依赖已正确安装

## 📊 数据库文件位置
```bash
warehouse-3d/server/warehouse.db
```

可以使用SQLite客户端工具查看和管理数据库文件。

### 数据库持久化机制

系统默认使用磁盘上的SQLite数据库文件进行数据持久化：
- **数据库文件路径**: `warehouse-3d/server/warehouse.db`
- **内存模式**: 当该文件不存在或无法访问时，系统会自动在内存中创建SQLite数据库实例运行
- **数据丢失风险**: 内存中的数据仅存在于运行时，服务重启后将丢失

### 重要警告：安全操作指南

#### 不要在服务运行时直接修改数据库文件
在服务运行期间直接使用DB Browser for SQLite等工具修改数据库文件会导致：
- 文件锁定问题：队列服务运行时会锁定并使用warehouse.db文件
- 数据不一致：直接修改文件时，队列服务可能无法立即感知到这些变更
- 缓存问题：队列服务可能在内存中缓存了部分数据，直接修改文件不会更新这些缓存
- 连接异常：可能导致队列服务与数据库连接异常，出现ECONNREFUSED错误

#### 正确的数据操作方式

1. **通过API接口进行数据操作**
   - 系统会自动处理数据持久化
   - 确保数据一致性
   - 避免文件锁定和缓存问题

2. **如需直接操作数据库文件，请先停止所有服务**
   - 执行 `taskkill /f /im node.exe` 停止所有Node.js进程
   - 确认服务已停止后再操作文件
   - 完成操作后重新启动服务

## 🗃️ Git版本控制

本项目使用Git进行版本控制，遵循以下规范：

### 忽略文件
项目中的以下文件和目录不会被纳入版本控制：
- `node_modules/` - npm依赖包
- `warehouse.db` - SQLite数据库文件
- `*.log` - 日志文件
- 系统和IDE生成的临时文件

### 提交规范
- 使用中文提交信息
- 每次提交应包含完整的功能变更
- 重要功能变更应包含相应的文档更新

### 分支管理
- `master` - 主分支，包含稳定版本
- 功能开发应在独立分支进行，完成后合并到master

## 📄 许可证

MIT License

## 批处理脚本

项目提供了多个批处理脚本以简化开发和部署流程：

1. **[bat/install.bat](./bat/install.bat)** - 自动检查环境并安装所有服务依赖
2. **[bat/start-services.bat](./bat/start-services.bat)** - 启动所有服务（前台模式，窗口可见）
3. **[start-services-background.bat](./start-services-background.bat)** - 启动所有服务（后台模式，窗口最小化）
4. **[close-all-services.bat](./close-all-services.bat)** - 关闭所有运行的服务

所有脚本均可通过双击运行，无需手动输入命令。

## 一键关闭服务

使用 [close-all-services.bat](./close-all-services.bat) 脚本可以一键关闭所有与仓库管理系统相关的服务进程：

使用方法：
- 双击 [close-all-services.bat](./close-all-services.bat) 文件即可运行