smartrack-sdk 1.0.0__py3-none-any.whl

smartrack_sdk/client/smart_rack_client.py

@@ -0,0 +1,523 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+SmartRack SDK 客户端核心类
+"""
+
+import json
+import logging
+import requests
+from typing import Optional, Dict, Any, Union
+from urllib.parse import urlencode
+
+from ..exceptions import (
+    SmartRackException,
+    SmartRackApiException,
+    SmartRackNetworkException,
+    SmartRackConfigurationException,
+    SmartRackValidationException,
+)
+from ..models.requests import (
+    BaseRequest,
+    ClearErrorRequest,
+    RackTestRequest,
+    StockInRequest,
+    StockOutRequest,
+    StockOutSheetRequest,
+    StockOutSheetCancelRequest,
+    StockOutSheetFinishRequest,
+    StockInFinishRequest,
+    ResetCellRequest,
+    GetStockByGRNListRequest,
+)
+from ..models.responses import (
+    BaseResponse,
+    ClearErrorResponse,
+    StockDataResponse,
+    StockOutResponse,
+    StockOutSheetResponse,
+)
+from ..models.enums import LedColors, CellStatus
+
+# 配置日志
+logger = logging.getLogger(__name__)
+
+
+class SmartRackClient:
+    """SmartRack SDK 客户端"""
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: int = 30,
+        auth_token: Optional[str] = None,
+        verify_ssl: bool = True,
+    ):
+        """
+        初始化SmartRack客户端
+
+        Args:
+            base_url: API基础URL
+            timeout: 请求超时时间（秒）
+            auth_token: 认证Token
+            verify_ssl: 是否验证SSL证书
+        """
+        if not base_url or not base_url.strip():
+            raise SmartRackConfigurationException("Base URL cannot be empty")
+
+        self.base_url = base_url.rstrip('/')
+        self.timeout = timeout
+        self.auth_token = auth_token
+        self.verify_ssl = verify_ssl
+
+        # 创建HTTP会话
+        self.session = requests.Session()
+        self.session.timeout = timeout
+
+        # 设置默认请求头
+        self.session.headers.update({
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+            'User-Agent': 'SmartRack-Python-SDK/1.0.0',
+        })
+
+        # 设置认证Token
+        if auth_token:
+            self.set_auth_token(auth_token)
+
+        logger.info(f"SmartRack客户端初始化完成: {self.base_url}")
+
+    def set_auth_token(self, token: str) -> None:
+        """
+        设置认证Token
+
+        Args:
+            token: 认证Token
+        """
+        self.auth_token = token
+        self.session.headers.update({
+            'Authorization': f'Bearer {token}'
+        })
+        logger.debug("设置认证Token成功")
+
+    def clear_auth_token(self) -> None:
+        """清除认证Token"""
+        self.auth_token = None
+        if 'Authorization' in self.session.headers:
+            del self.session.headers['Authorization']
+        logger.debug("清除认证Token成功")
+
+    def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        data: Optional[Union[Dict[str, Any], BaseRequest]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        发送HTTP请求
+
+        Args:
+            method: HTTP方法
+            endpoint: API端点
+            data: 请求数据
+            params: 查询参数
+
+        Returns:
+            响应数据
+
+        Raises:
+            SmartRackNetworkException: 网络错误
+            SmartRackApiException: API错误
+        """
+        url = f"{self.base_url}{endpoint}"
+
+        # 准备请求参数
+        request_kwargs = {
+            'verify': self.verify_ssl,
+            'timeout': self.timeout,
+        }
+
+        # 处理查询参数
+        if params:
+            request_kwargs['params'] = params
+
+        # 处理请求数据
+        if data is not None:
+            if isinstance(data, BaseRequest):
+                request_kwargs['json'] = data.to_dict()
+            else:
+                request_kwargs['json'] = data
+
+        try:
+            logger.debug(f"发送{method}请求到: {url}")
+            if request_kwargs.get('json'):
+                logger.debug(f"请求数据: {request_kwargs['json']}")
+
+            response = self.session.request(method, url, **request_kwargs)
+
+            # 检查HTTP状态码
+            response.raise_for_status()
+
+            # 解析响应
+            response_data = response.json()
+            logger.debug(f"响应数据: {response_data}")
+
+            return response_data
+
+        except requests.exceptions.Timeout as e:
+            error_msg = f"请求超时: {str(e)}"
+            logger.error(error_msg)
+            raise SmartRackNetworkException(error_msg, cause=e)
+
+        except requests.exceptions.ConnectionError as e:
+            error_msg = f"连接错误: {str(e)}"
+            logger.error(error_msg)
+            raise SmartRackNetworkException(error_msg, cause=e)
+
+        except requests.exceptions.HTTPError as e:
+            error_msg = f"HTTP错误: {str(e)}"
+            logger.error(error_msg)
+
+            # 尝试解析错误响应
+            try:
+                error_data = e.response.json()
+                status_code = e.response.status_code
+                raise SmartRackNetworkException(
+                    f"HTTP {status_code}: {error_data.get('message', error_msg)}",
+                    status_code=status_code,
+                    cause=e
+                )
+            except (ValueError, AttributeError):
+                raise SmartRackNetworkException(error_msg, e.response.status_code, e)
+
+        except requests.exceptions.RequestException as e:
+            error_msg = f"请求异常: {str(e)}"
+            logger.error(error_msg)
+            raise SmartRackNetworkException(error_msg, cause=e)
+
+        except json.JSONDecodeError as e:
+            error_msg = f"JSON解析错误: {str(e)}"
+            logger.error(error_msg)
+            raise SmartRackApiException("响应数据格式错误", -500)
+
+    def _handle_response(self, response_data: Dict[str, Any], response_class=BaseResponse):
+        """
+        处理API响应
+
+        Args:
+            response_data: 响应数据
+            response_class: 响应类
+
+        Returns:
+            响应对象
+
+        Raises:
+            SmartRackApiException: API错误
+        """
+        try:
+            response = response_class.from_dict(response_data)
+
+            # 检查API返回的状态码
+            if response.code != 0:
+                error_msg = response.message or f"API错误 (代码: {response.code})"
+                raise SmartRackApiException(error_msg, response.code, response.session_id)
+
+            return response
+
+        except Exception as e:
+            if isinstance(e, SmartRackApiException):
+                raise
+            error_msg = f"响应处理错误: {str(e)}"
+            logger.error(error_msg)
+            raise SmartRackApiException(error_msg, -500)
+
+    # API方法实现
+
+    def clear_error(self, request: ClearErrorRequest) -> ClearErrorResponse:
+        """
+        清错错误
+
+        Args:
+            request: 清错请求
+
+        Returns:
+            清错响应
+        """
+        if not request.rack_id and not request.cell_id:
+            raise SmartRackValidationException("必须指定rackId或cellId")
+
+        response_data = self._make_request(
+            'POST',
+            '/api/HJWMS/External/SmartRackExternal/ClearError',
+            request
+        )
+        return self._handle_response(response_data, ClearErrorResponse)
+
+    def rack_test(self, request: RackTestRequest) -> BaseResponse:
+        """
+        料架测试
+
+        Args:
+            request: 测试请求
+
+        Returns:
+            测试响应
+        """
+        if not request.rack_id:
+            raise SmartRackValidationException("rackId不能为空")
+
+        response_data = self._make_request(
+            'POST',
+            '/api/HJWMS/External/SmartRackExternal/RackTest',
+            request
+        )
+        return self._handle_response(response_data)
+
+    def stock_in_request(self, request: StockInRequest) -> BaseResponse:
+        """
+        入库请求
+
+        Args:
+            request: 入库请求
+
+        Returns:
+            入库响应
+        """
+        if not request.sheet_id or not request.rack_id or not request.grn:
+            raise SmartRackValidationException("sheetId、rackId和grn不能为空")
+
+        response_data = self._make_request(
+            'POST',
+            '/api/HJWMS/External/SmartRackExternal/StockInRequest',
+            request
+        )
+        return self._handle_response(response_data)
+
+    def stock_out_request(self, request: StockOutRequest) -> StockOutResponse:
+        """
+        出库请求
+
+        Args:
+            request: 出库请求
+
+        Returns:
+            出库响应
+        """
+        if not request.grn_list:
+            raise SmartRackValidationException("grnList不能为空")
+
+        response_data = self._make_request(
+            'POST',
+            '/api/HJWMS/External/SmartRackExternal/StockOutRequest',
+            request
+        )
+        return self._handle_response(response_data, StockOutResponse)
+
+    def stock_out_sheet_cancel(self, request: StockOutSheetCancelRequest) -> StockOutResponse:
+        """
+        单号出库取消
+
+        Args:
+            request: 取消请求
+
+        Returns:
+            取消响应
+        """
+        if not request.sheet_id:
+            raise SmartRackValidationException("sheetId不能为空")
+
+        response_data = self._make_request(
+            'POST',
+            '/api/HJWMS/External/SmartRackExternal/StockOutSheetCancel',
+            request
+        )
+        return self._handle_response(response_data, StockOutResponse)
+
+    def stock_out_sheet_finish(self, request: StockOutSheetFinishRequest) -> BaseResponse:
+        """
+        单号出库完成
+
+        Args:
+            request: 完成请求
+
+        Returns:
+            完成响应
+        """
+        if not request.sheet_id:
+            raise SmartRackValidationException("sheetId不能为空")
+
+        response_data = self._make_request(
+            'POST',
+            '/api/HJWMS/External/SmartRackExternal/StockOutSheetFinish',
+            request
+        )
+        return self._handle_response(response_data)
+
+    def stock_out_sheet_request(self, request: StockOutSheetRequest) -> StockOutSheetResponse:
+        """
+        单号出库请求
+
+        Args:
+            request: 出库请求
+
+        Returns:
+            出库响应
+        """
+        if not request.sheet_id or not request.grn_list:
+            raise SmartRackValidationException("sheetId和grnList不能为空")
+
+        response_data = self._make_request(
+            'POST',
+            '/api/HJWMS/External/SmartRackExternal/StockOutSheetRequest',
+            request
+        )
+        return self._handle_response(response_data, StockOutSheetResponse)
+
+    def reset_cell(self, request: ResetCellRequest) -> BaseResponse:
+        """
+        重置储位状态
+
+        Args:
+            request: 重置请求
+
+        Returns:
+            重置响应
+        """
+        if not request.cell_list:
+            raise SmartRackValidationException("cellList不能为空")
+
+        response_data = self._make_request(
+            'POST',
+            '/api/HJWMS/External/SmartRackExternal/ResetCell',
+            request
+        )
+        return self._handle_response(response_data)
+
+    def stock_in_finish(self, request: StockInFinishRequest) -> BaseResponse:
+        """
+        入库完成
+
+        Args:
+            request: 完成请求
+
+        Returns:
+            完成响应
+        """
+        if not request.sheet_id:
+            raise SmartRackValidationException("sheetId不能为空")
+
+        response_data = self._make_request(
+            'POST',
+            '/api/HJWMS/External/SmartRackExternal/StockInFinish',
+            request
+        )
+        return self._handle_response(response_data)
+
+    def get_stock_data(
+        self,
+        grn: Optional[str] = None,
+        rack_id: Optional[str] = None,
+        cell_id: Optional[str] = None,
+        stock_out_sheet: Optional[str] = None,
+        stock_in_sheet: Optional[str] = None,
+        led_color: Optional[LedColors] = None,
+        is_blink: Optional[bool] = None,
+        status: Optional[CellStatus] = None,
+        used: Optional[int] = None,
+        flag: Optional[int] = None,
+        sorting: Optional[str] = None,
+        skip_count: int = 0,
+        max_result_count: int = 10,
+    ) -> StockDataResponse:
+        """
+        查询库存
+
+        Args:
+            grn: GRN
+            rack_id: 料架号
+            cell_id: 储位号
+            stock_out_sheet: 出库单号
+            stock_in_sheet: 入库单号
+            led_color: LED颜色
+            is_blink: 是否闪烁
+            status: 状态
+            used: 占用状态
+            flag: 特殊标识
+            sorting: 排序
+            skip_count: 跳过数量
+            max_result_count: 最大结果数量
+
+        Returns:
+            库存数据响应
+        """
+        params = {
+            'SkipCount': skip_count,
+            'MaxResultCount': max_result_count,
+        }
+
+        # 添加可选参数
+        if grn:
+            params['GRN'] = grn
+        if rack_id:
+            params['RackId'] = rack_id
+        if cell_id:
+            params['CellId'] = cell_id
+        if stock_out_sheet:
+            params['StockOutSheet'] = stock_out_sheet
+        if stock_in_sheet:
+            params['StockInSheet'] = stock_in_sheet
+        if led_color is not None:
+            params['LedColor'] = led_color.value
+        if is_blink is not None:
+            params['IsBlink'] = is_blink
+        if status is not None:
+            params['Status'] = status.value
+        if used is not None:
+            params['Used'] = used
+        if flag is not None:
+            params['Flag'] = flag
+        if sorting:
+            params['Sorting'] = sorting
+
+        response_data = self._make_request(
+            'GET',
+            '/api/HJWMS/External/SmartRackExternal/StockData',
+            params=params
+        )
+        return self._handle_response(response_data, StockDataResponse)
+
+    def get_stock_by_grn_list(self, request: GetStockByGRNListRequest) -> StockDataResponse:
+        """
+        通过GRN列表查询库存
+
+        Args:
+            request: 查询请求
+
+        Returns:
+            库存数据响应
+        """
+        if not request.grn_list:
+            raise SmartRackValidationException("grnList不能为空")
+
+        response_data = self._make_request(
+            'POST',
+            '/api/HJWMS/External/SmartRackExternal/GetStockByGRNList',
+            request
+        )
+        return self._handle_response(response_data, StockDataResponse)
+
+    def close(self) -> None:
+        """关闭客户端"""
+        if self.session:
+            self.session.close()
+        logger.info("SmartRack客户端已关闭")
+
+    def __enter__(self):
+        """上下文管理器入口"""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """上下文管理器出口"""
+        self.close()

smartrack_sdk/exceptions/__init__.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+异常处理包
+包含所有SmartRack SDK相关的异常类
+"""
+
+from .base import SmartRackException
+from .api import SmartRackApiException
+from .network import SmartRackNetworkException
+from .configuration import SmartRackConfigurationException
+from .validation import SmartRackValidationException
+
+__all__ = [
+    "SmartRackException",
+    "SmartRackApiException",
+    "SmartRackNetworkException",
+    "SmartRackConfigurationException",
+    "SmartRackValidationException",
+]

smartrack_sdk/exceptions/api.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+API调用异常
+"""
+
+from .base import SmartRackException
+
+
+class SmartRackApiException(SmartRackException):
+    """API调用异常"""
+
+    def __init__(self, message: str, api_code: int, session_id: str = None):
+        """
+        初始化异常
+
+        Args:
+            message: 错误消息
+            api_code: API响应代码
+            session_id: 会话ID
+        """
+        super().__init__(message, api_code)
+        self.api_code = api_code
+        self.session_id = session_id
+
+    def __str__(self) -> str:
+        return (f"SmartRackApiException(api_code={self.api_code}, "
+                f"session_id={self.session_id}, message={self.message})")

smartrack_sdk/exceptions/base.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+SmartRack SDK 异常基类
+"""
+
+
+class SmartRackException(Exception):
+    """SmartRack SDK 异常基类"""
+
+    def __init__(self, message: str, error_code: int = -1):
+        """
+        初始化异常
+
+        Args:
+            message: 错误消息
+            error_code: 错误代码
+        """
+        super().__init__(message)
+        self.error_code = error_code
+        self.message = message
+
+    def __str__(self) -> str:
+        return f"SmartRackException(code={self.error_code}, message={self.message})"

smartrack_sdk/exceptions/configuration.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+配置异常
+"""
+
+from typing import Optional
+
+from .base import SmartRackException
+
+
+class SmartRackConfigurationException(SmartRackException):
+    """配置异常"""
+
+    def __init__(self, message: str, cause: Optional[Exception] = None):
+        """
+        初始化异常
+
+        Args:
+            message: 错误消息
+            cause: 内部异常
+        """
+        super().__init__(message, -1)
+        self.cause = cause
+
+    def __str__(self) -> str:
+        return f"SmartRackConfigurationException(message={self.message})"

smartrack_sdk/exceptions/network.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+网络异常
+"""
+
+from typing import Optional
+from .base import SmartRackException
+
+
+class SmartRackNetworkException(SmartRackException):
+    """网络异常"""
+
+    def __init__(self, message: str, status_code: Optional[int] = None, cause: Optional[Exception] = None):
+        """
+        初始化异常
+
+        Args:
+            message: 错误消息
+            status_code: HTTP状态码
+            cause: 内部异常
+        """
+        super().__init__(message, status_code or -1)
+        self.status_code = status_code
+        self.cause = cause
+
+    @property
+    def is_timeout(self) -> bool:
+        """是否为超时异常"""
+        return (self.cause is not None and
+                hasattr(self.cause, '__class__') and
+                ('timeout' in str(type(self.cause)).lower() or
+                 'Timeout' in str(type(self.cause))))
+
+    @property
+    def is_connection_error(self) -> bool:
+        """是否为连接异常"""
+        return (self.cause is not None and
+                hasattr(self.cause, '__class__') and
+                ('Connection' in str(type(self.cause)) or
+                 'connect' in str(type(self.cause)).lower()))
+
+    def __str__(self) -> str:
+        parts = [f"SmartRackNetworkException"]
+        if self.status_code:
+            parts.append(f"status_code={self.status_code}")
+        if self.message:
+            parts.append(f"message={self.message}")
+        return f"({', '.join(parts)})"

smartrack_sdk/exceptions/validation.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+验证异常
+"""
+
+from typing import Optional
+
+from .base import SmartRackException
+
+
+class SmartRackValidationException(SmartRackException):
+    """验证异常"""
+
+    def __init__(self, message: str, cause: Optional[Exception] = None):
+        """
+        初始化异常
+
+        Args:
+            message: 错误消息
+            cause: 内部异常
+        """
+        super().__init__(message, -1)
+        self.cause = cause
+
+    def __str__(self) -> str:
+        return f"SmartRackValidationException(message={self.message})"