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系统的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连接超时**: 调整数据库连接池配置