317 lines
9.5 KiB
Markdown
317 lines
9.5 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
这是宝应梦阳托盘库WMS系统的Spring Boot后端服务，专门处理托盘式仓库的入库、出库、库存管理和WCS系统集成。基于Spring Boot 3.3.5和Java 21开发，采用MyBatis-Plus进行数据持久化，支持与WCS设备系统的深度集成。
|
||
|
||
## 项目特点
|
||
|
||
**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核心控制器服务 (`MyWmsControllerServiceImpl`)
|
||
**文件**: `src/main/java/com/wms_main/service/controller/serviceImpl/MyWmsControllerServiceImpl.java`
|
||
|
||
**核心功能**:
|
||
- **入库管理**: `createOrderIn()` - 处理入库订单，检查AGV锁定状态
|
||
- **出库管理**: `createOrderOut()` - 处理出库订单，执行深度策略分析
|
||
- **库存查询**: `queryStock()` - 按载具号/库位号查询库存
|
||
- **入库口状态**: `queryAllowFeed()` - 查询WCS和AGV状态
|
||
- **出库口状态**: `queryCanOut()` - 查询WCS和AGV状态
|
||
|
||
**关键特征**:
|
||
- 防重复推送检查机制
|
||
- AGV互锁机制防冲突
|
||
- 深度策略自动分析
|
||
- 完整异常处理流程
|
||
|
||
#### 2. WCS API集成服务 (`WcsApiServiceImpl`)
|
||
**文件**: `src/main/java/com/wms_main/service/api/serviceImpl/WcsApiServiceImpl.java`
|
||
|
||
**集成接口**:
|
||
- 堆垛机任务下发: `sendStackerTask()`
|
||
- 载具释放控制: `releaseVehicle()`
|
||
- 拣选任务管理: `sendPickingTask()`
|
||
- 状态查询: `queryCanFeed()`, `queryOutFeed()`
|
||
|
||
⚠️ **重要**: 当前WCS通信为调试模式，实际HTTP调用被注释，返回模拟数据
|
||
|
||
#### 3. 任务控制服务 (`TaskControllerServiceImpl`)
|
||
**文件**: `src/main/java/com/wms_main/service/controller/serviceImpl/TaskControllerServiceImpl.java`
|
||
|
||
**主要功能**:
|
||
- 入库任务请求: `taskRequire()`
|
||
- 库位分配: `choiceLocation()`
|
||
- 任务回馈: `taskFeedback()`
|
||
- AGV锁定管理: `lockAgv()`, `releaseAgv()`
|
||
|
||
#### 4. 深度策略服务 (`IDepthStrategyService`)
|
||
**文件**: `src/main/java/com/wms_main/service/business/IDepthStrategyService.java`
|
||
|
||
**策略类型** (WmsDepthStrategyEnums):
|
||
- `DIRECT_OUT`: 直接出库 (深度1)
|
||
- `SINGLE_TRANSFER`: 单层移库 (深度2)
|
||
- `DOUBLE_TRANSFER`: 双层移库 (深度3)
|
||
- `COMPLEX_TRANSFER`: 复杂移库
|
||
- `NO_ACTION`: 无需处理
|
||
|
||
#### 5. AGV锁定服务 (`IAgvLockService`)
|
||
**文件**: `src/main/java/com/wms_main/service/business/IAgvLockService.java`
|
||
|
||
**功能**:
|
||
- 单一入库口互锁
|
||
- 超时锁定自动清理
|
||
- 状态查询监控
|
||
- 批量释放支持
|
||
|
||
### 数据库设计
|
||
|
||
#### 核心数据表
|
||
- **t_app_order_in**: 入库订单表
|
||
- **t_app_order_out**: 出库订单表
|
||
- **t_app_stock**: 库存信息表
|
||
- **t_app_task**: WMS任务表
|
||
- **t_app_wcs_task**: WCS任务表
|
||
- **t_app_agv_lock**: AGV锁定表
|
||
- **t_app_location**: 库位信息表
|
||
- **t_app_config**: 系统配置表
|
||
|
||
#### MyBatis-Plus配置
|
||
- 自动分页插件 (最大1000条)
|
||
- 驼峰命名自动映射
|
||
- 主键自动生成策略
|
||
|
||
### API接口设计
|
||
|
||
#### MyWMS外部接口
|
||
**控制器**: `src/main/java/com/wms_main/controller/mywms/MyWmsController.java`
|
||
|
||
```http
|
||
POST /mywms/orderIn # 创建入库订单
|
||
POST /mywms/orderOut # 创建出库订单
|
||
POST /mywms/stock # 查询库存信息
|
||
GET /mywms/allowFeed # 查询投料状态
|
||
GET /mywms/allowOut # 查询投料状态
|
||
```
|
||
|
||
**测试文件**: `api-tests/MyWmsController.http`
|
||
|
||
#### 响应格式
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "操作成功",
|
||
"data": {},
|
||
"timestamp": "2024-01-01T12:00:00"
|
||
}
|
||
```
|
||
|
||
### 重要枚举类 (`constant/enums/`)
|
||
|
||
**WMS业务枚举** (`enums/wms/`)
|
||
- `AppConfigKeyEnums` - 系统配置项枚举
|
||
- `WmsDepthStrategyEnums` - 深度策略枚举
|
||
- `WmsStockStatusEnums` - 库存状态枚举
|
||
- `OrderStatusEnum` - 订单状态枚举
|
||
- `WmsTaskTypeEnums` - 任务类型枚举
|
||
- `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版本的业务逻辑差异
|
||
|
||
## 开发规范
|
||
|
||
### 代码约定
|
||
- Controller层只处理HTTP请求，业务逻辑在Service层
|
||
- 使用DTO传输数据，内部业务使用BO对象
|
||
- 统一通过MyBatis-Plus的BaseMapper操作数据库
|
||
- 所有业务异常继承RuntimeException并返回统一错误格式
|
||
|
||
### WCS集成规范
|
||
- WCS调用通过IWcsApiService统一管理
|
||
- AGV操作必须使用锁定机制防冲突
|
||
- 任务下发前检查设备状态和库位可用性
|
||
- 调试时注意区分模拟数据和真实WCS调用
|
||
|
||
### 异常处理
|
||
- 使用@ControllerAdvice全局异常处理
|
||
- 业务异常返回统一MyWmsResponse格式
|
||
- 记录详细错误日志便于问题定位
|
||
|
||
### 日志规范
|
||
- 使用Slf4j进行日志记录
|
||
- 关键业务操作记录INFO级别日志
|
||
- 异常情况记录ERROR级别日志
|
||
- 避免敏感信息出现在日志中
|
||
|
||
## 调试和监控
|
||
|
||
### 本地调试
|
||
- 默认端口: 12315
|
||
- H2控制台: 如果启用可通过/h2-console访问
|
||
- 日志级别: 通过logback-spring.xml配置
|
||
|
||
### 数据库连接测试
|
||
```bash
|
||
# 测试数据库连接
|
||
mysql -h localhost -P 3306 -u root -p wms_mengyang_tp
|
||
|
||
# 查看关键表结构
|
||
DESCRIBE t_app_stock;
|
||
DESCRIBE t_app_order_in;
|
||
```
|
||
|
||
### 常见问题
|
||
1. **WCS连接失败**: 检查WCS系统URL配置和网络连通性
|
||
2. **AGV锁定超时**: 检查t_app_agv_lock表的锁定记录
|
||
3. **深度策略错误**: 检查库存状态和深度计算逻辑
|
||
4. **MySQL连接超时**: 调整数据库连接池配置 |