202504-Wms-MengYang/202504-Wms-MengYang-tp/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（仓库管理系统）后端项目（TP托盘库版本），基于Spring Boot 3.3.5和Java 21开发，使用Maven构建。专门针对托盘库存储场景，管理仓库的入库、出库、库存和任务调度等核心业务。

## 项目特点

**TP托盘库版本特性**
- 专为托盘存储优化的算法策略
- 支持大型货物的托盘化存储管理
- 与BOX料箱库版本在业务逻辑上有所差异
- 数据库schema针对托盘库场景设计

## 开发环境设置

### 基本构建命令
```bash
# 进入项目目录
cd 202504-Wms-MengYang-tp/wms_serve_mengyang

# 编译项目
mvn clean compile

# 打包项目
mvn clean package

# 运行项目
mvn spring-boot:run

# 使用Maven Wrapper
./mvnw spring-boot:run

# 跳过测试运行（项目配置默认跳过测试）
mvn clean package -Dmaven.test.skip=true
```

### 运行环境配置

**数据库配置**
- 本地开发：MySQL `localhost:3306/wms_mengyang_tp`（注意：使用tp数据库）
- 生产环境：MySQL `10.18.58.21:3306/wms_yachi_nantong`
- 认证信息：本地使用root/root，生产使用user/user

**应用配置**
- 服务端口：12315
- 应用名称：wms_main
- 文件上传限制：单文件100MB，总计1000MB
- 当前配置：`spring.profiles.active=online`

**Maven特殊配置**
- 项目默认跳过单元测试：`maven-surefire-plugin.skip=true`
- 最终构建文件名：`wms-box-server`（注意：名称还是box-server但实际是tp版本）
- Java版本：21 (source和target都是21)

## 核心架构

### 分层架构
系统采用标准的MVC三层架构：
- **Controller层**：REST API接口，包含mywms和wms两个模块
- **Service层**：业务逻辑层，分为controller、business、api三个子模块
- **DAO层**：数据访问层，使用MyBatis-Plus

### 核心业务模块

#### 1. MyWMS模块 (`controller/mywms/`)
自定义WMS接口：
- `POST /orderIn` - 入库订单接口
- `POST /orderOut` - 出库订单接口  
- `POST /stock` - 库存查询接口

#### 2. 深度策略服务 (`service/business/DepthStrategyService`)
核心算法模块，针对托盘库优化：
- **托盘库(TP)专属存储策略**
- 大型货物的存储位置优化算法
- 托盘堆叠和存取路径优化

#### 3. 任务调度系统 (`service/quartz_job/`)
基于Quartz的定时任务框架：
- `WmsTaskExecutor` - WMS任务执行器
- `MyOutExecutor` - 出库任务执行器
- `WcsStackerTaskSender` - WCS堆垛机任务发送器

#### 4. 设备集成 (`service/api/`)
- `WcsApiService` - WCS系统集成（托盘库设备）
- `ExternalApiService` - 外部系统API调用

### 数据模型结构
- `po/` - 数据库实体对象（针对托盘库schema）
- `dto/request/` - 请求数据传输对象
- `dto/response/` - 响应数据传输对象  
- `bo/` - 业务对象（Business Object）
- `vo/` - 视图对象（View Object）

### 常用枚举类 (`constant/enums/`)

**WMS业务枚举** (`enums/wms/`)
- `StorageTypeEnums` - 存储类型（重点关注TP托盘库类型）
- `WmsDepthStrategyEnums` - 深度策略枚举（托盘库专用策略）
- `WmsTaskTypeEnums` - 任务类型枚举
- `OrderStatusEnum` - 订单状态枚举
- `WmsLocationTypeEnums` - 货位类型枚举（托盘货位）
- `WmsVehicleStatusEnums` - 载具状态枚举（托盘载具）

**WCS集成枚举** (`enums/wcs/`)
- `WcsApiResponseCodeEnums` - WCS API响应码
- `WcsStackerTaskTypeEnums` - 堆垛机任务类型（托盘堆垛机）
- `WcsStackerTaskStatusEnums` - 堆垛机任务状态

## 技术栈

### 核心依赖
- **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** - 集合工具

## 重要的文件路径

- **主要工作目录**：`202504-Wms-MengYang-tp/wms_serve_mengyang/`
- **日志存储**：`wms_log/` (按日期和级别分类)
- **数据库脚本**：`db/wms_mengyang_tp.sql`
- **MyBatis映射**：`src/main/resources/mapper/`

## 常见开发任务

### 启动应用
```bash
cd 202504-Wms-MengYang-tp/wms_serve_mengyang
mvn spring-boot:run
```

### 查看日志
```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的定时任务框架
- 关键执行器针对托盘库场景优化
- 任务状态实时监控

### Excel处理
- 后端：EasyExcel 4.0.3 + EasyPOI 4.5.0
- 支持托盘库相关的业务数据导入导出
- 模板位置：`excel/easypoi/excelTemplate/`

## TP与BOX版本的差异

### 主要区别
1. **数据库schema**：使用`wms_mengyang_tp`数据库
2. **存储策略算法**：针对托盘存储特点优化
3. **设备集成**：对接托盘库专用设备
4. **业务规则**：托盘的尺寸、重量、堆叠规则不同

### 开发注意事项
- 在开发新功能时，注意区分TP和BOX版本的业务差异
- 深度策略算法需要考虑托盘的物理特性
- WCS集成需要适配托盘库的设备类型

## 故障排除

### 常见问题
1. **端口冲突**：确认12315端口未被占用
2. **数据库连接**：检查MySQL服务状态和TP数据库配置
3. **版本混淆**：确认操作的是TP版本而非BOX版本
4. **日志分析**：按级别查看对应日志目录

### 调试技巧
- 使用`RequestLogFilter`查看API请求日志
- 通过`WmsControllerExceptionHandler`统一异常处理
- 检查定时任务执行状态：查看`TAppJobs`表
- 注意区分TP和BOX版本的业务逻辑差异

## 开发规范

### 代码规范
- 使用Lombok注解减少样板代码
- 统一的API响应格式（WmsApiResponse）
- 枚举类管理常量值
- 接口-实现分离的服务层设计

### 测试建议
项目配置跳过单元测试，建议：
1. 先实现功能代码
2. 使用Postman等工具进行API测试
3. 检查托盘库相关的数据库数据状态
4. 验证定时任务执行情况
5. 测试WCS设备集成功能