202504-Wms-MengYang/202504-Wms-MengYang-box/wms_serve_mengyang/CLAUDE.md

# 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调试前端状态管理