wms-py/README.md

# WMS FastAPI 项目

这是一个基于 FastAPI 的仓库管理系统(WMS)，采用标准的项目结构，支持多环境配置。

## 项目结构

```
wms-py/
├── app/                          # 应用核心代码
│   ├── __init__.py
│   ├── main.py                   # 主应用文件
│   ├── config/                   # 配置模块
│   │   ├── __init__.py
│   │   └── settings.py           # 配置管理
│   ├── controllers/              # 控制器(路由)
│   │   ├── __init__.py
│   │   ├── base_controller.py    # 基础接口
│   │   ├── database_controller.py # 数据库测试接口
│   │   └── location_controller.py # 库位管理接口 🆕
│   ├── services/                 # 业务服务层 🆕
│   │   ├── __init__.py
│   │   └── location_service.py   # 库位业务逻辑
│   ├── models/                   # 数据模型 🆕
│   │   ├── __init__.py
│   │   └── location.py           # 库位数据模型
│   ├── schemas/                  # Pydantic模式 🆕
│   │   ├── __init__.py
│   │   ├── common.py             # 通用响应模式
│   │   └── location.py           # 库位请求/响应模式
│   └── utils/                    # 工具类
│       ├── __init__.py
│       ├── database.py           # 数据库工具类
│       └── string_utils.py       # 字符串工具 🆕
├── config/                       # 环境配置文件
│   ├── development.yaml          # 开发环境配置
│   └── production.yaml           # 生产环境配置
├── requirements.txt              # 依赖包列表
├── run.py                        # 启动脚本
├── create_tables.py              # 数据库表创建脚本 🆕
└── README.md                     # 项目说明
```

## 功能特性

- ✅ 多环境配置支持 (开发/生产)
- ✅ YAML 配置文件
- ✅ 数据库连接管理
- ✅ 标准项目结构
- ✅ API 文档自动生成
- ✅ 数据库测试接口
- ✅ 健康检查接口
- ✅ **库位管理模块** 🆕
  - 批量生成库位
  - 查询已使用库位数量
  - 库位信息查询
  - 库位统计功能

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置数据库

根据需要修改配置文件：

**开发环境** (`config/development.yaml`):
```yaml
database:
  host: "localhost"
  port: 3306
  username: "root"
  password: "root"
  database: "wms_ntyc"
```

### 3. 创建数据库表

```bash
python create_tables.py
```

### 4. 运行应用

```bash
# 开发环境
python run.py

# 生产环境
set ENVIRONMENT=production && python run.py
```

## API接口

### 基础接口
- `GET /` - 系统信息
- `GET /health` - 健康检查
- `GET /config` - 配置信息

### 数据库测试接口
- `GET /database/test` - 测试数据库连接
- `GET /database/tables` - 获取所有表名
- `GET /database/query?sql=SELECT * FROM table_name` - 执行SQL查询
- `GET /database/table/{table_name}` - 查看指定表数据

### 库位管理接口 🆕

**库位生成**:
- `POST /wms/location/genLocations` - 批量生成库位

请求示例：
```json
{
  "l_row": 5,
  "l_col": 8,
  "l_layer": 6,
  "l_depth": 2,
  "sub_area": "A",
  "area_id": 1
}
```

**库位查询**:
- `GET /wms/location/getUsedLocations?equipment_id=1&location_type=1` - 获取已使用库位数量
- `GET /wms/location/location/{location_id}` - 根据ID查询库位信息
- `GET /wms/location/locations/area/{area_id}` - 根据区域查询库位列表
- `GET /wms/location/locations/stats` - 获取库位统计信息

### API 文档
- `GET /docs` - Swagger UI 文档
- `GET /redoc` - ReDoc 文档

## 库位管理功能详解

### 1. 库位生成逻辑

库位ID格式：`{子区域}{行号02d}-{列号02d}-{层号02d}-{深度02d}`

例如：
- 子区域: A
- 行: 1, 列: 2, 层: 3, 深度: 1
- 生成ID: `A01-02-03-01`

### 2. 数据库表结构

```sql
CREATE TABLE t_app_location (
    location_id VARCHAR(50) PRIMARY KEY COMMENT '库位ID',
    location_name VARCHAR(100) DEFAULT '' COMMENT '库位名称',
    location_type INT DEFAULT 1 COMMENT '库位类型',
    is_occupy INT DEFAULT 0 COMMENT '是否占用 0-未占用 1-已占用',
    is_enable INT DEFAULT 0 COMMENT '是否启用',
    equipment_id INT DEFAULT 0 COMMENT '设备ID',
    aisle_num_left INT COMMENT '左侧巷道号',
    aisle_num_right INT COMMENT '右侧巷道号',
    l_row INT COMMENT '行',
    l_col INT COMMENT '列',
    l_layer INT COMMENT '层',
    l_depth INT COMMENT '深度',
    remark TEXT DEFAULT '' COMMENT '备注',
    area_id INT DEFAULT 1 COMMENT '区域ID',
    sub_area VARCHAR(50) DEFAULT '' COMMENT '子区域'
);
```

### 3. 使用示例

**生成库位**：
```bash
curl -X POST "http://localhost:12315/wms/location/genLocations" \
  -H "Content-Type: application/json" \
  -d '{
    "l_row": 2,
    "l_col": 3,
    "l_layer": 4,
    "l_depth": 1,
    "sub_area": "A",
    "area_id": 1
  }'
```

**查询统计**：
```bash
curl "http://localhost:12315/wms/location/locations/stats"
```

## 项目架构说明

### 分层架构

1. **Controller层** (`app/controllers/`)
   - 处理HTTP请求
   - 参数验证
   - 路由定义

2. **Service层** (`app/services/`)
   - 业务逻辑处理
   - 事务管理
   - 数据操作

3. **Model层** (`app/models/`)
   - 数据库表映射
   - ORM模型定义

4. **Schema层** (`app/schemas/`)
   - 请求/响应数据验证
   - API文档生成

### 依赖注入

项目使用FastAPI的依赖注入系统：
- 数据库会话注入
- 服务类注入
- 配置注入

### 对应关系

| Java概念 | Python/FastAPI概念 | 文件位置 |
|---------|-------------------|----------|
| @RestController | APIRouter | `app/controllers/` |
| @Service | Service类 | `app/services/` |
| @Entity | SQLAlchemy Model | `app/models/` |
| DTO | Pydantic Schema | `app/schemas/` |
| @Autowired | Depends() | 依赖注入 |

## IDE 配置

### PyCharm 配置

创建运行配置：
- **Name**: `WMS Development`
- **Script path**: `run.py`
- **Environment variables**: `ENVIRONMENT=development`

## 注意事项

1. 确保数据库服务已启动
2. 首次运行前执行 `python create_tables.py` 创建表
3. 修改配置文件后需要重启应用
4. 库位生成前请确认参数，避免重复数据

## 故障排除

### 常见问题

1. **表不存在**
   - 运行 `python create_tables.py` 创建表

2. **库位ID重复**
   - 检查参数是否与已有数据冲突
   - 清理测试数据后重新生成

3. **数据库连接失败**
   - 检查配置文件中的数据库信息
   - 确认数据库服务状态