324 lines
9.3 KiB
Markdown
324 lines
9.3 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
这是一个宝应梦阳WMS（仓库管理系统）项目，包含前后端分离的完整解决方案：
|
||
- **后端项目**：基于Spring Boot 3.3.5和Java 21开发，使用Maven构建
|
||
- **前端项目**：基于Vue 3和Element Plus开发，提供Web管理界面
|
||
- **业务场景**：支持托盘库(TP)和料箱库(BOX)两种存储类型，管理仓库的入库、出库、库存和任务调度等核心业务
|
||
|
||
## 项目结构
|
||
|
||
本项目包含两个子项目，位于不同目录：
|
||
- `202504-Wms-MengYang-box/` - 料箱库(BOX)版本
|
||
- `202504-Wms-MengYang-tp/` - 托盘库(TP)版本
|
||
|
||
每个子项目都包含：
|
||
- `wms_serve_mengyang/` - Spring Boot后端服务
|
||
- `wms_web_mengyang/` - Vue.js前端应用
|
||
- `db/` - 数据库SQL文件
|
||
|
||
## 开发环境设置
|
||
|
||
### 后端项目命令（Maven）
|
||
```bash
|
||
# 进入后端目录（以BOX版本为例）
|
||
cd 202504-Wms-MengYang-box/wms_serve_mengyang
|
||
|
||
# 编译项目
|
||
mvn clean compile
|
||
|
||
# 打包项目
|
||
mvn clean package
|
||
|
||
# 运行项目
|
||
mvn spring-boot:run
|
||
|
||
# 跳过测试运行（项目配置默认跳过测试）
|
||
mvn clean package -Dmaven.test.skip=true
|
||
```
|
||
|
||
### 前端项目命令（Vue.js）
|
||
```bash
|
||
# 进入前端目录（以BOX版本为例）
|
||
cd 202504-Wms-MengYang-box/wms_web_mengyang
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器
|
||
npm run serve
|
||
|
||
# 构建生产版本
|
||
npm run build
|
||
|
||
# 代码检查和修复
|
||
npm run lint
|
||
```
|
||
|
||
### 运行环境配置
|
||
|
||
**数据库配置**
|
||
- 本地开发：MySQL `localhost:3306/wms_mengyang_box`
|
||
- 生产环境：MySQL `10.18.58.21:3306/wms_yachi_nantong`
|
||
- 认证信息：本地使用root/root，生产使用user/user
|
||
|
||
**后端服务 (Spring Boot)**
|
||
- 服务端口：12315
|
||
- 应用名称：wms_main
|
||
- 文件上传限制：单文件100MB，总计1000MB
|
||
- 当前配置：`spring.profiles.active=online`
|
||
|
||
**前端应用 (Vue.js)**
|
||
- 开发端口：12306
|
||
- 后端API地址：`http://10.18.58.21:12315`
|
||
- 路由模式：Hash路由
|
||
|
||
## 核心架构
|
||
|
||
### 分层架构
|
||
|
||
**后端架构（Spring Boot）**
|
||
系统采用标准的MVC三层架构：
|
||
- **Controller层**：REST API接口，包含mywms和wms两个模块
|
||
- **Service层**：业务逻辑层，分为controller、business、api三个子模块
|
||
- **DAO层**：数据访问层，使用MyBatis-Plus
|
||
|
||
**前端架构（Vue.js）**
|
||
采用现代化的Vue 3组件化架构：
|
||
- **Views层**：页面视图组件（login、HomeView、SystemCenter）
|
||
- **Layout层**：业务布局组件（库存、入库、出库等功能页面）
|
||
- **Components层**：可复用组件（sideMenu、appTag）
|
||
- **API层**：HTTP请求封装和接口定义
|
||
- **Store层**：Vuex状态管理（用户信息、菜单权限、标签页）
|
||
- **Router层**：Vue Router路由管理
|
||
- **Utils层**：工具函数（日期处理、格式化、加密等）
|
||
|
||
### 核心业务模块
|
||
|
||
#### 1. MyWMS模块 (`controller/mywms/`)
|
||
自定义WMS接口：
|
||
- `POST /orderIn` - 入库订单接口
|
||
- `POST /orderOut` - 出库订单接口
|
||
- `POST /stock` - 库存查询接口
|
||
|
||
#### 2. 深度策略服务 (`service/business/DepthStrategyService`)
|
||
核心算法模块，实现智能仓储策略：
|
||
- 支持托盘库(TP)和料箱库(BOX)两种存储类型
|
||
- 动态深度分析和出库优化策略
|
||
|
||
#### 3. 任务调度系统 (`service/quartz_job/`)
|
||
基于Quartz的定时任务：
|
||
- `WmsTaskExecutor` - WMS任务执行器
|
||
- `MyOutExecutor` - 出库任务执行器
|
||
- `WcsStackerTaskSender` - WCS任务发送器
|
||
|
||
#### 4. 设备集成 (`service/api/`)
|
||
- `WcsApiService` - WCS系统集成
|
||
- `ExternalApiService` - 外部系统API调用
|
||
|
||
### 数据模型结构
|
||
- `po/` - 数据库实体对象（Persistent Object）
|
||
- `dto/request/` - 请求数据传输对象
|
||
- `dto/response/` - 响应数据传输对象
|
||
- `bo/` - 业务对象（Business Object）
|
||
- `vo/` - 视图对象（View Object）
|
||
|
||
### 常用枚举类 (`constant/enums/`)
|
||
|
||
**WMS业务枚举** (`enums/wms/`)
|
||
- `StorageTypeEnums` - 存储类型（托盘库TP/料箱库BOX）
|
||
- `WmsDepthStrategyEnums` - 深度策略枚举
|
||
- `WmsTaskTypeEnums` - 任务类型枚举
|
||
- `OrderStatusEnum` - 订单状态枚举
|
||
- `WmsLocationTypeEnums` - 货位类型枚举
|
||
- `WmsGoodsStatusEnums` - 货物状态枚举
|
||
- `WmsVehicleStatusEnums` - 载具状态枚举
|
||
|
||
**WCS集成枚举** (`enums/wcs/`)
|
||
- `WcsApiResponseCodeEnums` - WCS API响应码
|
||
- `WcsStackerTaskTypeEnums` - 堆垛机任务类型
|
||
- `WcsStackerTaskStatusEnums` - 堆垛机任务状态
|
||
|
||
**任务调度枚举** (`enums/jobs/`)
|
||
- `JobStatusEnums` - 任务状态枚举
|
||
- `JobTimerTypeEnums` - 定时器类型枚举
|
||
|
||
## 技术栈
|
||
|
||
### 后端技术栈（Spring Boot）
|
||
|
||
**核心依赖**
|
||
- Spring Boot Web 3.3.5 - REST API框架
|
||
- Spring Boot Quartz - 定时任务调度
|
||
- MyBatis-Plus 3.5.7 - ORM框架
|
||
- MySQL Connector - 数据库连接
|
||
- Lombok - 代码简化
|
||
|
||
**工具库**
|
||
- Hutool 5.8.33 - Java工具类库
|
||
- FastJSON 2.0.21 - JSON处理
|
||
- EasyExcel 4.0.3 & EasyPOI 4.5.0 - Excel处理
|
||
- Apache HttpClient 4.5.13 - HTTP客户端
|
||
- Google Guava 33.3.1 - 集合工具
|
||
|
||
### 前端技术栈（Vue.js）
|
||
|
||
**核心框架**
|
||
- Vue 3.2.13 - 前端框架
|
||
- Vue Router 4.0.3 - 路由管理
|
||
- Vuex 4.0.0 - 状态管理
|
||
- Element Plus 2.4.0 - UI组件库
|
||
|
||
**主要依赖**
|
||
- Axios 1.3.3 - HTTP请求库
|
||
- Moment 2.29.4 - 日期处理
|
||
- XLSX 0.18.5 - Excel文件处理
|
||
- QRCode.vue 3.4.1 - 二维码生成
|
||
- Vue3-print-nb 0.1.4 - 打印功能
|
||
- File-saver 2.0.5 - 文件下载
|
||
|
||
**开发工具**
|
||
- Sass 1.83.4 - CSS预处理器
|
||
- ESLint - 代码质量检查
|
||
- Babel - JavaScript编译器
|
||
|
||
## 开发注意事项
|
||
|
||
### 后端代码规范
|
||
- 使用Lombok注解减少样板代码
|
||
- 统一的API响应格式（WmsApiResponse）
|
||
- 枚举类管理常量值
|
||
- 接口-实现分离的服务层设计
|
||
|
||
### 前端代码规范
|
||
- Vue 3 Composition API优先
|
||
- Element Plus组件库统一UI风格
|
||
- Vuex模块化状态管理
|
||
- ESLint代码质量检查（关闭未使用变量警告）
|
||
- 响应式设计，支持不同屏幕尺寸
|
||
|
||
### 数据库操作
|
||
- 使用MyBatis-Plus进行ORM操作
|
||
- 支持批量操作和事务处理
|
||
- 驼峰命名自动映射
|
||
- ID生成策略：assign_id
|
||
|
||
### 错误处理
|
||
- 统一异常处理器：`WmsControllerExceptionHandler`
|
||
- 标准化错误码：`WmsApiResponseCodeEnums`
|
||
- 请求日志过滤器：`RequestLogFilter`
|
||
|
||
### Excel处理
|
||
**后端**：使用EasyExcel和EasyPOI双重支持
|
||
- 货物信息、产品信息、库存信息等业务数据
|
||
- 模板位置：`excel/easypoi/excelTemplate/`
|
||
|
||
**前端**：使用XLSX和Element Plus支持
|
||
- 文件上传组件：`excel/` 目录下的各类Excel上传组件
|
||
- 支持在线预览和数据导出
|
||
- 集成二维码生成和打印功能
|
||
|
||
## 外部系统集成
|
||
|
||
### WCS系统集成
|
||
- 堆垛机任务调度
|
||
- 载具管理（托盘和料箱）
|
||
- TCP/HTTP通信协议
|
||
|
||
### MES系统对接
|
||
- 制造执行系统数据交换
|
||
- 生产任务状态同步
|
||
|
||
## 测试说明
|
||
|
||
**后端测试**
|
||
项目配置中跳过了单元测试执行（`maven-surefire-plugin.skip=true`），在开发新功能时建议：
|
||
1. 先实现功能代码
|
||
2. 使用Postman等工具进行API测试
|
||
3. 检查数据库数据状态
|
||
4. 验证定时任务执行情况
|
||
|
||
**前端测试**
|
||
- 使用浏览器开发者工具调试
|
||
- 通过Vue DevTools检查组件状态
|
||
- 使用Element Plus组件库确保UI一致性
|
||
- 在不同浏览器（Chrome、Firefox、Edge）中测试兼容性
|
||
|
||
## 开发注意事项
|
||
|
||
### 特殊的Maven配置
|
||
- 项目默认跳过单元测试：`maven-surefire-plugin.skip=true`
|
||
- 最终构建文件名：`wms-box-server`
|
||
- Java版本：21 (source和target都是21)
|
||
- Maven Wrapper可用：使用`./mvnw`替代`mvn`命令
|
||
|
||
### 重要的文件路径
|
||
- 主要工作目录：`202504-Wms-MengYang-box/wms_serve_mengyang/`
|
||
- 日志存储：`wms_log/` (按日期和级别分类)
|
||
- 数据库脚本：`db/wms_mengyang_box.sql`
|
||
- MyBatis映射：`src/main/resources/mapper/`
|
||
|
||
### 常见开发任务
|
||
|
||
**启动后端服务**
|
||
```bash
|
||
cd 202504-Wms-MengYang-box/wms_serve_mengyang
|
||
mvn spring-boot:run
|
||
# 或使用Maven Wrapper
|
||
./mvnw spring-boot:run
|
||
```
|
||
|
||
**启动前端开发服务器**
|
||
```bash
|
||
cd 202504-Wms-MengYang-box/wms_web_mengyang
|
||
npm run serve
|
||
```
|
||
|
||
**查看日志**
|
||
```bash
|
||
# 查看今天的info日志
|
||
tail -f wms_log/info/$(date +%Y-%m-%d)/$(date +%Y-%m-%d).0.log
|
||
|
||
# 查看今天的error日志
|
||
tail -f wms_log/error/$(date +%Y-%m-%d)/$(date +%Y-%m-%d).0.log
|
||
```
|
||
|
||
**数据库操作**
|
||
- 使用MyBatis-Plus进行ORM操作
|
||
- 支持批量操作和事务处理
|
||
- 驼峰命名自动映射(`map-underscore-to-camel-case: true`)
|
||
- ID生成策略：`assign_id`
|
||
|
||
### 系统集成要点
|
||
|
||
**WCS系统集成**
|
||
- TCP和HTTP双协议支持
|
||
- 堆垛机任务调度和状态同步
|
||
- 载具管理（托盘和料箱）
|
||
|
||
**任务调度系统**
|
||
- 基于Quartz的定时任务框架
|
||
- 关键执行器：`WmsTaskExecutor`、`MyOutExecutor`、`WcsStackerTaskSender`
|
||
- 任务状态实时监控
|
||
|
||
**Excel处理**
|
||
- 后端：EasyExcel 4.0.3 + EasyPOI 4.5.0
|
||
- 前端：XLSX 0.18.5 + Element Plus上传组件
|
||
- 模板位置：`excel/easypoi/excelTemplate/`
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
1. **端口冲突**：确认12315端口未被占用
|
||
2. **数据库连接**：检查MySQL服务状态和配置
|
||
3. **前端代理**：确认后端API地址配置正确
|
||
4. **日志分析**：按级别查看对应日志目录
|
||
|
||
### 调试技巧
|
||
- 使用`RequestLogFilter`查看API请求日志
|
||
- 通过`WmsControllerExceptionHandler`统一异常处理
|
||
- 检查定时任务执行状态：查看`TAppJobs`表
|
||
- Vue DevTools调试前端状态管理 |