smartrack-sdk 1.0.0

广东浩鲸科技智能料架系统Python SDK

SmartRack SDK for Python

SmartRack智能料架系统Python SDK，提供与智能料架系统Web API的集成接口。

特性

• ✅ 完整的API接口支持
• ✅ 强类型模型（dataclasses）
• ✅ 完善的异常处理
• ✅ 自动序列化/反序列化
• ✅ 认证支持
• ✅ 超时控制
• ✅ WebAPI回调处理
• ✅ Flask/FastAPI集成支持
• ✅ 详细日志记录
• ✅ 单元测试覆盖

快速开始

安装

pip install smartrack-sdk

或从源码安装：

git clone https://github.com/smartrack/smartrack-sdk-python.git
cd smartrack-sdk-python
pip install -e .

基本使用

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. 入库管理

入库请求

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}")

入库完成

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. 出库管理

出库请求

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}")

单号出库请求

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}")

单号出库完成

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}")

单号出库取消

from smartrack_sdk.models.requests import StockOutSheetCancelRequest

request = StockOutSheetCancelRequest("test", "MES")
request.set_sheet_id("工单号/领料单号")

response = client.stock_out_sheet_cancel(request)

3. 库存查询

查询库存数据

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列表查询库存

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. 料架管理

料架测试

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}")

重置储位状态

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}")

清除错误

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（推荐）

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

from smartrack_sdk.callback import FastAPICellEventHandler
import uvicorn

# 创建FastAPI应用
app = FastAPICellEventHandler()
uvicorn.run(app, host="0.0.0.0", port=8080)

自定义回调处理器

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灯颜色)

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 (储位状态)

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 (料架测试模式)

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调用返回错误时抛出：

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

网络相关错误时抛出：

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

配置错误时抛出：

try:
    client = SmartRackClient("")  # 空的URL
except SmartRackConfigurationException as e:
    print(f"配置错误: {e.message}")

高级配置

自定义HTTP客户端

import requests

# 创建自定义session
session = requests.Session()
session.timeout = 60  # 60秒超时
session.verify = False  # 跳过SSL验证

# 使用自定义session创建客户端
client = SmartRackClient("https://api.smartrack.com", timeout=60)

设置认证Token

client = SmartRackClient("https://api.smartrack.com")
client.set_auth_token("your-auth-token")

日志配置

import logging

# 配置详细日志
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# SDK会自动使用配置的logger

使用上下文管理器

with SmartRackClient("https://api.smartrack.com") as client:
    # 使用client...
    response = client.stock_in_request(request)
    # 客户端会自动关闭

测试

运行基本示例

python examples/basic_usage.py

运行测试客户端

# 测试所有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

启动回调服务器

# 使用Flask启动WebAPI回调服务器
python examples/callback_server.py --server

# 查看手动设置说明
python examples/callback_server.py --manual

运行单元测试

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月