smartrack-sdk 1.0.0
广东浩鲸科技智能料架系统Python SDK
Requires Python: >=3.6
Keywords: smartrack 广东浩鲸科技 wms仓储管理 智能料架 api sdk

# SmartRack SDK for Python

SmartRack智能料架系统Python SDK，提供与智能料架系统Web API的集成接口。

## 特性

- ✅ 完整的API接口支持
- ✅ 强类型模型（dataclasses）
- ✅ 完善的异常处理
- ✅ 自动序列化/反序列化
- ✅ 认证支持
- ✅ 超时控制
- ✅ WebAPI回调处理
- ✅ Flask/FastAPI集成支持
- ✅ 详细日志记录
- ✅ 单元测试覆盖

## 快速开始

### 安装

```bash
pip install smartrack-sdk
```

或从源码安装：

```bash
git clone https://github.com/smartrack/smartrack-sdk-python.git
cd smartrack-sdk-python
pip install -e .
```

### 基本使用

```python
import logging
from smartrack_sdk import SmartRackClient
from smartrack_sdk.models.requests import StockInRequest
from smartrack_sdk.models.enums import LedColors

# 配置日志
logging.basicConfig(level=logging.INFO)

# 创建客户端
with SmartRackClient("https://your-smartrack-api.com") as client:
    # 创建入库请求
    request = StockInRequest("test123", "MES001")
    request.set_sheet_id("SI-20240101001")
    request.set_rack_id("A001")
    request.set_grn("PRODUCT001")
    request.set_led_color(LedColors.GREEN)
    request.set_blink(True)

    # 发送请求
    response = client.stock_in_request(request)
    print(f"入库请求结果: Code={response.code}, Message={response.message}")
```

## 功能模块

### 1. 入库管理

#### 入库请求
```python
from smartrack_sdk.models.requests import StockInRequest

request = StockInRequest("test", "MES")
request.set_sheet_id("入库单号")
request.set_rack_id("料架编号")
request.set_grn("产品朔源码")
request.set_led_color(LedColors.GREEN)
request.set_blink(True)

response = client.stock_in_request(request)
print(f"入库请求结果: {response.message}")
```

#### 入库完成
```python
from smartrack_sdk.models.requests import StockInFinishRequest

request = StockInFinishRequest("test", "MES")
request.set_sheet_id("入库单号")

response = client.stock_in_finish(request)
print(f"入库完成结果: {response.message}")
```

### 2. 出库管理

#### 出库请求
```python
from smartrack_sdk.models.requests import StockOutRequest

request = StockOutRequest("test", "MES")
request.set_sheet_id("出库单号")
request.add_grn("朔源码1")
request.add_grn("朔源码2")
request.set_led_color(LedColors.RED)
request.set_blink(True)

response = client.stock_out_request(request)
for item in response.result_data:
    print(f"储位: {item.cell}, GRN: {item.grn}")
```

#### 单号出库请求
```python
from smartrack_sdk.models.requests import StockOutSheetRequest

request = StockOutSheetRequest("test", "MES")
request.set_sheet_id("工单号/领料单号")
request.add_grn("朔源码1")
request.add_grn("朔源码2")

response = client.stock_out_sheet_request(request)
print(f"亮灯颜色: {response.led_color}")
print(f"颜色名称: {response.color_name}")
```

#### 单号出库完成
```python
from smartrack_sdk.models.requests import StockOutSheetFinishRequest

request = StockOutSheetFinishRequest("test", "MES")
request.set_sheet_id("工单号/领料单号")

response = client.stock_out_sheet_finish(request)
print(f"单号出库完成结果: {response.message}")
```

#### 单号出库取消
```python
from smartrack_sdk.models.requests import StockOutSheetCancelRequest

request = StockOutSheetCancelRequest("test", "MES")
request.set_sheet_id("工单号/领料单号")

response = client.stock_out_sheet_cancel(request)
```

### 3. 库存查询

#### 查询库存数据
```python
response = client.get_stock_data(
    grn="PRODUCT001",          # GRN
    rack_id="A001",           # 料架号
    cell_id="A0010001",       # 储位号
    led_color=LedColors.GREEN,  # LED颜色
    is_blink=False,            # 是否闪烁
    skip_count=0,              # 跳过数量
    max_result_count=50         # 最大结果数量
)

print(f"查询到 {response.total} 条库存记录")
for stock in response.result_data:
    print(f"料架: {stock.rack_id}, 储位: {stock.cell_id}, GRN: {stock.grn}")
```

#### 通过GRN列表查询库存
```python
from smartrack_sdk.models.requests import GetStockByGRNListRequest

request = GetStockByGRNListRequest("test", "MES")
request.add_grn("GRN001")
request.add_grn("GRN002")
request.add_grn("GRN003")

response = client.get_stock_by_grn_list(request)
print(f"查询到 {response.total} 条库存记录")
```

### 4. 料架管理

#### 料架测试
```python
from smartrack_sdk.models.requests import RackTestRequest
from smartrack_sdk.models.enums import RackTestMode

request = RackTestRequest("test", "MES")
request.set_rack_id("A001")
request.set_test_mode(RackTestMode.RGB_TEST)
request.set_blink(False)

response = client.rack_test(request)
print(f"料架测试结果: {response.message}")
```

#### 重置储位状态
```python
from smartrack_sdk.models.requests import ResetCellRequest

request = ResetCellRequest("test", "MES")
request.add_cell("A0010001")
request.add_cell("A0010002")
request.add_cell("A0010003")

response = client.reset_cell(request)
print(f"重置储位状态结果: {response.message}")
```

#### 清除错误
```python
from smartrack_sdk.models.requests import ClearErrorRequest

request = ClearErrorRequest("test", "MES")
request.set_cell_id("A0010001")  # 或者使用 set_rack_id("A001")

response = client.clear_error(request)
for item in response.result_data:
    status_text = "空" if item.is_empty() else "非空"
    print(f"储位: {item.cell}, GRN: {item.grn}, 状态: {status_text}")
```

### 5. WebAPI回调处理

#### 使用Flask（推荐）
```python
from smartrack_sdk.callback import FlaskCellEventHandler, CellEventCallbackService
from flask import Flask

# 创建Flask应用
app = Flask(__name__)

# 创建回调处理器
handler = CellEventCallbackService()
flask_handler = FlaskCellEventHandler(app, handler)

# 启动服务器
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8080)
```

#### 使用FastAPI
```python
from smartrack_sdk.callback import FastAPICellEventHandler
import uvicorn

# 创建FastAPI应用
app = FastAPICellEventHandler()
uvicorn.run(app, host="0.0.0.0", port=8080)
```

#### 自定义回调处理器
```python
from smartrack_sdk.callback import CellEventHandler
from smartrack_sdk.models.callback import CellEventHandleRequest, CellEventHandleResponse

class CustomCellEventHandler(CellEventHandler):
    def handle(self, request: CellEventHandleRequest) -> CellEventHandleResponse:
        # 自定义处理逻辑
        print(f"收到储位事件回调: {request.user_id}")

        # 处理事件数据
        for event_data in request.data:
            print(f"储位: {event_data.cell_id}, GRN: {event_data.grn}")

        # 返回成功响应
        return CellEventHandleResponse.success(request.session_id)

# 使用自定义处理器
handler = CustomCellEventHandler()
```

## 枚举类型

### LedColors (LED灯颜色)
```python
from smartrack_sdk.models.enums import LedColors

# 颜色值
LedColors.OFF           # 0 - 关闭
LedColors.RED           # 1 - 红色
LedColors.GREEN         # 2 - 绿色
LedColors.YELLOW        # 3 - 黄色
LedColors.BLUE          # 4 - 蓝色
LedColors.MAGENTA       # 5 - 洋红色
LedColors.CYAN          # 6 - 青色
LedColors.WHITE         # 7 - 白色
LedColors.BLINK         # 128 - 闪烁
LedColors.RED_BLINK     # 129 - 红色闪烁
LedColors.GREEN_BLINK   # 130 - 绿色闪烁
LedColors.YELLOW_BLINK  # 131 - 黄色闪烁
LedColors.BLUE_BLINK    # 132 - 蓝色闪烁
LedColors.MAGENTA_BLINK # 133 - 洋红色闪烁
LedColors.CYAN_BLINK    # 134 - 青色闪烁
LedColors.WHITE_BLINK   # 135 - 白色闪烁
```

### CellStatus (储位状态)
```python
from smartrack_sdk.models.enums import CellStatus

CellStatus.EMPTY             # 0 - 空
CellStatus.HOLD              # 1 - 非空
CellStatus.LOCKED            # 2 - 预定状态
CellStatus.TAKE_OUT          # 3 - 已取料
CellStatus.CHECKED           # 4 - 已复核
CellStatus.MOVE              # 5 - 移库已取出
CellStatus.ILLEGAL_TAKE_OUT # -3 - 非法取料
CellStatus.ILLEGAL_TAKE_IN  # -2 - 非法上料
CellStatus.DISABLED          # -1 - 禁用储位
```

### RackTestMode (料架测试模式)
```python
from smartrack_sdk.models.enums import RackTestMode

RackTestMode.ALL_OFF           # 0 - 全部灭灯
RackTestMode.RGB_TEST          # 1 - RGB测试
RackTestMode.LIGHT_SEQUENCE_TEST # 2 - 灯序测试
RackTestMode.WARNING_LIGHT_TEST # 3 - 警示灯测试
RackTestMode.EMPTY_LIGHT       # 4 - 空位亮灯
RackTestMode.NON_EMPTY_LIGHT   # 5 - 非空亮灯
```

## 异常处理

### SmartRackException
所有SDK异常的基类。

### SmartRackApiException
API调用返回错误时抛出：
```python
try:
    response = client.stock_in_request(request)
except SmartRackApiException as e:
    print(f"API错误: {e.message}")
    print(f"错误代码: {e.api_code}")
    print(f"会话ID: {e.session_id}")
```

### SmartRackNetworkException
网络相关错误时抛出：
```python
try:
    response = client.stock_in_request(request)
except SmartRackNetworkException as e:
    print(f"网络错误: {e.message}")
    print(f"HTTP状态码: {e.status_code}")

    if e.is_timeout:
        print("请求超时")
    elif e.is_connection_error:
        print("连接错误")
```

### SmartRackConfigurationException
配置错误时抛出：
```python
try:
    client = SmartRackClient("")  # 空的URL
except SmartRackConfigurationException as e:
    print(f"配置错误: {e.message}")
```

## 高级配置

### 自定义HTTP客户端
```python
import requests

# 创建自定义session
session = requests.Session()
session.timeout = 60  # 60秒超时
session.verify = False  # 跳过SSL验证

# 使用自定义session创建客户端
client = SmartRackClient("https://api.smartrack.com", timeout=60)
```

### 设置认证Token
```python
client = SmartRackClient("https://api.smartrack.com")
client.set_auth_token("your-auth-token")
```

### 日志配置
```python
import logging

# 配置详细日志
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# SDK会自动使用配置的logger
```

### 使用上下文管理器
```python
with SmartRackClient("https://api.smartrack.com") as client:
    # 使用client...
    response = client.stock_in_request(request)
    # 客户端会自动关闭
```

## 测试

### 运行基本示例
```bash
python examples/basic_usage.py
```

### 运行测试客户端
```bash
# 测试所有API
python examples/test_client.py

# 测试单个API
python examples/test_client.py stock_in
python examples/test_client.py rack_test
python examples/test_client.py clear_error
```

### 启动回调服务器
```bash
# 使用Flask启动WebAPI回调服务器
python examples/callback_server.py --server

# 查看手动设置说明
python examples/callback_server.py --manual
```

### 运行单元测试
```bash
python -m pytest smartrack_sdk/tests/
```

## 项目结构

```
smartrack-sdk-python/
├── smartrack_sdk/                 # 主包
│   ├── __init__.py
│   ├── client/                    # 客户端
│   │   ├── __init__.py
│   │   └── smart_rack_client.py
│   ├── models/                    # 数据模型
│   │   ├── __init__.py
│   │   ├── enums.py              # 枚举定义
│   │   ├── requests.py           # 请求模型
│   │   ├── responses.py          # 响应模型
│   │   └── callback.py            # 回调模型
│   ├── exceptions/               # 异常类
│   │   ├── __init__.py
│   │   ├── base.py               # 基础异常
│   │   ├── api.py                # API异常
│   │   ├── network.py            # 网络异常
│   │   ├── configuration.py      # 配置异常
│   │   └── validation.py         # 验证异常
│   └── callback/                  # 回调处理
│       ├── __init__.py
│       ├── handler.py            # 回调处理器
│       ├── service.py            # 默认回调服务
│       ├── flask_handler.py      # Flask处理器
│       └── fastapi_handler.py    # FastAPI处理器
├── examples/                      # 使用示例
│   ├── basic_usage.py          # 基本使用示例
│   ├── callback_server.py      # 回调服务器示例
│   └── test_client.py          # 测试客户端
├── smartrack_sdk/tests/           # 单元测试
├── setup.py                      # 安装配置
├── requirements.txt              # 依赖文件
└── README.md                     # 文档
```

## 依赖项

### 核心依赖
- `requests` >= 2.25.1 - HTTP客户端
- `urllib3` >= 1.26.0 - URL处理
- `python-dateutil` >= 2.8.2 - 日期处理

### 可选依赖
- `Flask` >= 2.0.0 - Web框架（用于回调处理）
- `FastAPI` >= 0.68 - Web框架（用于回调处理）
- `uvicorn` >= 0.15 - ASGI服务器（用于FastAPI）

## 开发依赖
- `pytest` >= 6.0 - 测试框架
- `pytest-cov` >= 2.0 - 测试覆盖率
- `black` >= 21.0 - 代码格式化
- `flake8` >= 3.8 - 代码检查
- `mypy` >= 0.800 - 类型检查

## 许可证

本项目基于MIT许可证开源。

## 支持

如有问题或建议，请提交Issue或联系开发团队。

---

**SmartRack SDK Team**
版本: 1.0.0
最后更新: 2024年11月