258 lines
6.6 KiB
Markdown
258 lines
6.6 KiB
Markdown
# 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. **数据库连接失败**
|
||
- 检查配置文件中的数据库信息
|
||
- 确认数据库服务状态 |