pixelarraythirdparty 1.0.3__py3-none-any.whl → 1.0.5__py3-none-any.whl

pixelarraythirdparty/__init__.py

@@ -10,7 +10,7 @@ PixelArray 第三方微服务客户端
 - user: 用户管理模块
 """
 
-__version__ = "1.0.3"
+__version__ = "1.0.5"
 __author__ = "Lu qi"
 __email__ = "qi.lu@pixelarrayai.com"
 

pixelarraythirdparty/celery/celery.py

@@ -3,30 +3,149 @@ from pixelarraythirdparty.client import Client
 
 class CeleryManager(Client):
     def get_celery_status(self):
+        """
+        获取Celery服务状态
+        
+        功能说明：
+            获取Celery服务的运行状态，包括已注册的任务、工作节点状态等。
+        
+        输入参数：
+            无
+        
+        返回字段：
+            data (dict): Celery服务状态信息
+                - registered_tasks (dict): 已注册的任务列表，按工作节点分组
+                - worker_stats (dict): 工作节点统计信息
+                - scheduled_task_count (int): 定时任务数量
+                - timestamp (str): 状态获取时间
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 获取Celery状态失败：返回错误信息"获取Celery状态失败"
+        """
         data, success = self._request("GET", "/api/celery/status")
         if not success:
             return {}, False
         return data, True
 
     def get_celery_tasks(self):
+        """
+        获取已注册任务列表
+        
+        功能说明：
+            获取所有已注册的Celery任务列表。
+        
+        输入参数：
+            无
+        
+        返回字段：
+            data (dict): 任务列表信息
+                - tasks (list): 已注册的任务名称列表
+                - count (int): 任务数量
+                - timestamp (str): 获取时间
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 获取任务列表失败：返回错误信息"获取任务列表失败"
+        """
         data, success = self._request("GET", "/api/celery/tasks")
         if not success:
             return {}, False
         return data, True
 
     def get_celery_tasks_scheduled(self):
+        """
+        获取定时任务列表
+        
+        功能说明：
+            获取所有配置的定时任务列表，包括任务详情、执行时间、状态等。
+        
+        输入参数：
+            无
+        
+        返回字段：
+            data (dict): 定时任务列表信息
+                - tasks (list): 定时任务列表
+                    - id (str): 任务ID
+                    - name (str): 任务名称
+                    - description (str): 任务描述
+                    - schedule (str): 执行时间
+                    - enabled (bool): 是否启用
+                    - task_name (str): 任务函数名
+                    - module_name (str): 模块名
+                    - function_name (str): 函数名
+                    - file_path (str): 文件路径
+                    - parameters (list): 参数列表
+                    - task_config (dict): 任务配置
+                    - registration_info (dict): 注册信息
+                - count (int): 任务数量
+                - timestamp (str): 获取时间
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 获取定时任务列表失败：返回错误信息"获取定时任务列表失败"
+        """
         data, success = self._request("GET", "/api/celery/tasks/scheduled")
         if not success:
             return {}, False
         return data, True
 
     def get_celery_tasks_detail(self, task_name: str):
+        """
+        获取任务详情
+        
+        功能说明：
+            根据任务名称获取指定任务的详细信息。
+        
+        输入参数：
+            task_name (str): 任务名称，必填，需要URL编码
+        
+        返回字段：
+            data (dict): 任务详细信息
+                - task_name (str): 任务名称
+                - module_name (str): 模块名
+                - function_name (str): 函数名
+                - file_path (str): 文件路径
+                - description (str): 任务描述
+                - parameters (list): 参数列表
+                - task_config (dict): 任务配置
+                - registration_info (dict): 注册信息
+                - timestamp (str): 获取时间
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 任务不存在：返回错误信息"任务不存在"
+            - 获取任务详情失败：返回错误信息"获取任务详情失败"
+        """
         data, success = self._request("GET", f"/api/celery/tasks/{task_name}")
         if not success:
             return {}, False
         return data, True
 
     def trigger_celery_task(self, task_name: str, args: list, kwargs: dict):
+        """
+        触发任务执行
+        
+        功能说明：
+            手动触发指定任务的执行，支持传递参数。
+        
+        输入参数：
+            task_name (str): 任务名称，必填，需要URL编码
+            args (list): 任务参数列表，可选
+            kwargs (dict): 任务关键字参数，可选
+        
+        返回字段：
+            data (dict): 任务触发信息
+                - task_id (str): 任务ID
+                - task_name (str): 任务名称
+                - status (str): 任务状态，初始为"PENDING"
+                - message (str): 触发消息
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 任务不存在：返回错误信息"任务不存在"
+            - 任务触发失败：返回错误信息"任务触发失败"
+        """
         data, success = self._request(
             "POST",
             f"/api/celery/tasks/{task_name}/trigger",

pixelarraythirdparty/client.py

@@ -1,9 +1,12 @@
 import requests
+import aiohttp
 from typing import Dict, Any, Optional, Tuple
+import asyncio
 
 
 class Client:
     """基础认证类，提供公共的 API key 认证和请求方法"""
+
     def __init__(self, api_key: str):
         self.base_url = "https://thirdparty.pixelarrayai.com"
         self.api_key = api_key
@@ -20,3 +23,25 @@ class Client:
         if resp.status_code == 200 and resp.json().get("success") is True:
             return resp.json().get("data", {}), True
         return {}, False
+
+
+class AsyncClient:
+    def __init__(self, api_key: str):
+        self.base_url = "https://thirdparty.pixelarrayai.com"
+        self.api_key = api_key
+        self.headers = {
+            "Content-Type": "application/json",
+            "X-API-Key": self.api_key,
+        }
+
+    async def _request(self, method: str, url: str, **kwargs) -> Tuple[Dict[str, Any], bool]:
+        async with aiohttp.ClientSession() as session:
+            req_method = getattr(session, method.lower())
+            async with req_method(
+                f"{self.base_url}{url}", headers=self.headers, **kwargs
+            ) as resp:
+                if resp.status == 200:
+                    result = await resp.json()
+                    if result.get("success") is True:
+                        return result.get("data", {}), True
+                return {}, False

pixelarraythirdparty/order/order.py

@@ -1,4 +1,4 @@
-from pixelarraythirdparty.client import Client
+from pixelarraythirdparty.client import Client, AsyncClient
 
 
 class OrderManager(Client):
@@ -9,6 +9,39 @@ class OrderManager(Client):
         remark: str = None,
         payment_channel: str = "WECHAT",
     ):
+        """
+        创建订单
+        
+        功能说明：
+            根据产品ID创建新的订单，系统会自动生成订单号，获取产品价格信息，并创建对应的支付订单。
+        
+        输入参数：
+            product_id (str): 产品ID，必填，用于获取产品信息和价格
+            body (str, 可选): 商品描述，如果不提供则使用产品名称
+            remark (str, 可选): 订单备注信息
+            payment_channel (str, 可选): 支付渠道，默认为"WECHAT"（微信支付）
+        
+        返回字段：
+            data (dict): 订单信息
+                - id (int): 订单ID
+                - out_trade_no (str): 商户订单号，格式为"ORD_时间戳_随机字符串"
+                - payment_status (str): 支付状态，初始为"PENDING"（待支付）
+                - payment_channel (str): 支付渠道
+                - product_id (str): 产品ID
+                - amount (str): 订单金额（元），格式为"99.00"
+                - total_fee (int): 订单金额（分），用于支付接口
+                - body (str): 商品描述
+                - remark (str): 订单备注
+                - created_at (str): 订单创建时间
+                - updated_at (str): 订单更新时间
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 产品ID为空：返回错误信息"产品ID不能为空"
+            - 产品不存在：返回错误信息"产品不存在"
+            - 产品价格无效：返回错误信息"产品价格无效"
+            - 创建订单失败：返回错误信息"创建订单失败"
+        """
         data = {
             "product_id": product_id,
             "body": body,
@@ -27,6 +60,41 @@ class OrderManager(Client):
         payment_status: str = None,
         out_trade_no: str = None,
     ):
+        """
+        获取订单列表
+        
+        功能说明：
+            分页查询订单列表，支持按支付状态和订单号进行筛选。
+        
+        输入参数：
+            page (int, 可选): 页码，默认为1，最小值为1
+            page_size (int, 可选): 每页数量，默认为10，范围为1-1000
+            payment_status (str, 可选): 支付状态筛选，可选值：
+                - "PENDING": 待支付
+                - "PAID": 已支付
+                - "REFUNDED": 已退款
+                - "CANCELLED": 已取消
+            out_trade_no (str, 可选): 订单号搜索，支持模糊匹配
+        
+        返回字段：
+            data (dict): 订单列表信息
+                - orders (list): 订单列表
+                    - id (int): 订单ID
+                    - out_trade_no (str): 商户订单号
+                    - payment_status (str): 支付状态
+                    - payment_channel (str): 支付渠道
+                    - amount (str): 订单金额（元）
+                    - total_fee (int): 订单金额（分）
+                    - created_at (str): 订单创建时间
+                    - updated_at (str): 订单更新时间
+                - total (int): 总订单数量
+                - page (int): 当前页码
+                - page_size (int): 每页数量
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 获取订单列表失败：返回错误信息"获取订单列表失败"
+        """
         params = {
             "page": page,
             "page_size": page_size,
@@ -39,6 +107,41 @@ class OrderManager(Client):
         return data, True
 
     def get_order_detail(self, out_trade_no: str):
+        """
+        获取订单详情
+        
+        功能说明：
+            根据订单号获取订单的详细信息，包括支付状态、交易信息等。
+        
+        输入参数：
+            out_trade_no (str): 商户订单号，必填
+        
+        返回字段：
+            data (dict): 订单详细信息
+                - id (int): 订单ID
+                - out_trade_no (str): 商户订单号
+                - payment_status (str): 支付状态
+                - product_id (str): 产品ID
+                - amount (str): 订单金额（元）
+                - total_fee (int): 订单金额（分）
+                - body (str): 商品描述
+                - transaction_id (str): 微信交易号（支付成功后才有）
+                - openid (str): 用户openid（支付成功后才有）
+                - trade_type (str): 交易类型（支付成功后才有）
+                - bank_type (str): 银行类型（支付成功后才有）
+                - fee_type (str): 货币类型，默认为"CNY"
+                - is_subscribe (str): 是否关注公众号（支付成功后才有）
+                - time_end (str): 支付完成时间（支付成功后才有）
+                - created_at (str): 订单创建时间
+                - updated_at (str): 订单更新时间
+                - paid_at (str): 支付时间（支付成功后才有）
+                - remark (str): 订单备注
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 订单不存在：返回错误信息"订单不存在"
+            - 获取订单详情失败：返回错误信息"获取订单详情失败"
+        """
         data, success = self._request("GET", f"/api/orders/{out_trade_no}")
         if not success:
             return {}, False
@@ -49,6 +152,42 @@ class OrderManager(Client):
         out_trade_no: str,
         payment_status: str,
     ):
+        """
+        更新订单状态
+        
+        功能说明：
+            更新指定订单的支付状态，仅支持状态修改，其他字段不可修改。
+        
+        输入参数：
+            out_trade_no (str): 商户订单号，必填
+            payment_status (str): 支付状态，必填，可选值：
+                - "PENDING": 待支付
+                - "PAID": 已支付
+                - "REFUNDED": 已退款
+                - "CANCELLED": 已取消
+        
+        返回字段：
+            data (dict): 更新后的订单信息
+                - id (int): 订单ID
+                - out_trade_no (str): 商户订单号
+                - payment_status (str): 更新后的支付状态
+                - transaction_id (str): 微信交易号（如果已支付）
+                - openid (str): 用户openid（如果已支付）
+                - trade_type (str): 交易类型（如果已支付）
+                - bank_type (str): 银行类型（如果已支付）
+                - fee_type (str): 货币类型
+                - is_subscribe (str): 是否关注公众号（如果已支付）
+                - time_end (str): 支付完成时间（如果已支付）
+                - paid_at (str): 支付时间（如果已支付）
+                - updated_at (str): 订单更新时间
+                - remark (str): 订单备注
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 支付状态为空：返回错误信息"支付状态不能为空"
+            - 订单不存在：返回错误信息"订单不存在"
+            - 更新订单状态失败：返回错误信息"更新订单状态失败"
+        """
         data = {
             "payment_status": payment_status,
         }
@@ -60,12 +199,51 @@ class OrderManager(Client):
         return data, True
 
     def delete_order(self, out_trade_no: str):
+        """
+        删除订单
+        
+        功能说明：
+            根据订单号删除指定的订单记录。
+        
+        输入参数：
+            out_trade_no (str): 商户订单号，必填
+        
+        返回字段：
+            data (None): 删除成功时返回None
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 订单不存在：返回错误信息"订单不存在"
+            - 删除订单失败：返回错误信息"删除订单失败"
+        """
         data, success = self._request("DELETE", f"/api/orders/{out_trade_no}")
         if not success:
             return {}, False
         return data, True
 
     def get_order_stats(self):
+        """
+        获取订单统计信息
+        
+        功能说明：
+            获取订单的统计汇总信息，包括总订单数、各状态订单数量、总金额等。
+        
+        输入参数：
+            无
+        
+        返回字段：
+            data (dict): 订单统计信息
+                - total_orders (int): 总订单数量
+                - pending_orders (int): 待支付订单数量
+                - paid_orders (int): 已支付订单数量
+                - refunded_orders (int): 已退款订单数量
+                - total_amount (float): 总订单金额（元）
+                - total_fee (int): 总订单金额（分）
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 获取订单统计信息失败：返回错误信息"获取订单统计信息失败"
+        """
         data, success = self._request("GET", "/api/orders/stats/summary")
         if not success:
             return {}, False
@@ -76,6 +254,30 @@ class OrderManager(Client):
         out_trade_no: str,
         payment_channel: str = "WECHAT",
     ):
+        """
+        生成支付二维码
+        
+        功能说明：
+            为指定订单生成支付二维码，支持微信支付和支付宝。二维码会自动上传到OSS并返回访问URL。
+        
+        输入参数：
+            out_trade_no (str): 商户订单号，必填
+            payment_channel (str, 可选): 支付渠道，默认为"WECHAT"，可选值：
+                - "WECHAT": 微信支付
+                - "ALIPAY": 支付宝（暂未实现）
+        
+        返回字段：
+            data (dict): 二维码信息
+                - qr_code_url (str): 二维码图片URL，可直接用于显示
+                - out_trade_no (str): 商户订单号
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 订单号为空：返回错误信息"订单号不能为空"
+            - 订单不存在：返回错误信息"订单不存在"
+            - 不支持的支付渠道：抛出ValueError异常
+            - 生成支付二维码失败：返回错误信息"生成支付二维码失败"
+        """
         if payment_channel == "WECHAT":
             url = "/api/orders/wx_pay/generate_qr_code"
         elif payment_channel == "ALIPAY":
@@ -94,6 +296,32 @@ class OrderManager(Client):
         return data, True
 
     def refund_order(self, out_trade_no: str, payment_channel: str = "WECHAT"):
+        """
+        申请订单退款
+        
+        功能说明：
+            为指定订单申请退款，支持微信支付和支付宝。退款申请提交后，系统会处理退款并更新订单状态。
+        
+        输入参数：
+            out_trade_no (str): 商户订单号，必填
+            payment_channel (str, 可选): 支付渠道，默认为"WECHAT"，可选值：
+                - "WECHAT": 微信支付
+                - "ALIPAY": 支付宝（暂未实现）
+        
+        返回字段：
+            data (dict): 退款信息
+                - out_refund_no (str): 退款单号，格式为"REFUND_订单号_时间戳"
+                - out_trade_no (str): 商户订单号
+                - total_fee (int): 退款金额（分）
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 订单号为空：返回错误信息"订单号不能为空"
+            - 订单不存在：返回错误信息"订单不存在"
+            - 订单状态不允许退款：返回错误信息"订单状态不允许退款"
+            - 不支持的支付渠道：抛出ValueError异常
+            - 退款申请失败：返回错误信息"退款申请失败"
+        """
         if payment_channel == "WECHAT":
             url = "/api/orders/wx_pay/refund"
         elif payment_channel == "ALIPAY":
@@ -108,3 +336,326 @@ class OrderManager(Client):
         if not success:
             return {}, False
         return data, True
+
+
+class OrderManagerAsync(AsyncClient):
+    async def create_order(
+        self,
+        product_id: str,
+        body: str = None,
+        remark: str = None,
+        payment_channel: str = "WECHAT",
+    ):
+        """
+        创建订单（异步版本）
+        
+        功能说明：
+            根据产品ID创建新的订单，系统会自动生成订单号，获取产品价格信息，并创建对应的支付订单。
+        
+        输入参数：
+            product_id (str): 产品ID，必填，用于获取产品信息和价格
+            body (str, 可选): 商品描述，如果不提供则使用产品名称
+            remark (str, 可选): 订单备注信息
+            payment_channel (str, 可选): 支付渠道，默认为"WECHAT"（微信支付）
+        
+        返回字段：
+            data (dict): 订单信息
+                - id (int): 订单ID
+                - out_trade_no (str): 商户订单号，格式为"ORD_时间戳_随机字符串"
+                - payment_status (str): 支付状态，初始为"PENDING"（待支付）
+                - payment_channel (str): 支付渠道
+                - product_id (str): 产品ID
+                - amount (str): 订单金额（元），格式为"99.00"
+                - total_fee (int): 订单金额（分），用于支付接口
+                - body (str): 商品描述
+                - remark (str): 订单备注
+                - created_at (str): 订单创建时间
+                - updated_at (str): 订单更新时间
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 产品ID为空：返回错误信息"产品ID不能为空"
+            - 产品不存在：返回错误信息"产品不存在"
+            - 产品价格无效：返回错误信息"产品价格无效"
+            - 创建订单失败：返回错误信息"创建订单失败"
+        """
+        data = {
+            "product_id": product_id,
+            "body": body,
+            "remark": remark,
+            "payment_channel": payment_channel,
+        }
+        data, success = await self._request("POST", "/api/orders/create", json=data)
+        if not success:
+            return {}, False
+        return data, True
+
+    async def list_order(
+        self,
+        page: int = 1,
+        page_size: int = 10,
+        payment_status: str = None,
+        out_trade_no: str = None,
+    ):
+        """
+        获取订单列表（异步版本）
+        
+        功能说明：
+            分页查询订单列表，支持按支付状态和订单号进行筛选。
+        
+        输入参数：
+            page (int, 可选): 页码，默认为1，最小值为1
+            page_size (int, 可选): 每页数量，默认为10，范围为1-1000
+            payment_status (str, 可选): 支付状态筛选，可选值：
+                - "PENDING": 待支付
+                - "PAID": 已支付
+                - "REFUNDED": 已退款
+                - "CANCELLED": 已取消
+            out_trade_no (str, 可选): 订单号搜索，支持模糊匹配
+        
+        返回字段：
+            data (dict): 订单列表信息
+                - orders (list): 订单列表
+                    - id (int): 订单ID
+                    - out_trade_no (str): 商户订单号
+                    - payment_status (str): 支付状态
+                    - payment_channel (str): 支付渠道
+                    - amount (str): 订单金额（元）
+                    - total_fee (int): 订单金额（分）
+                    - created_at (str): 订单创建时间
+                    - updated_at (str): 订单更新时间
+                - total (int): 总订单数量
+                - page (int): 当前页码
+                - page_size (int): 每页数量
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 获取订单列表失败：返回错误信息"获取订单列表失败"
+        """
+        params = {
+            "page": page,
+            "page_size": page_size,
+            "payment_status": payment_status,
+            "out_trade_no": out_trade_no,
+        }
+        data, success = await self._request("GET", "/api/orders/list", params=params)
+        if not success:
+            return {}, False
+        return data, True
+
+    async def get_order_detail(self, out_trade_no: str):
+        """
+        获取订单详情（异步版本）
+        
+        功能说明：
+            根据订单号获取订单的详细信息，包括支付状态、交易信息等。
+        
+        输入参数：
+            out_trade_no (str): 商户订单号，必填
+        
+        返回字段：
+            data (dict): 订单详细信息
+                - id (int): 订单ID
+                - out_trade_no (str): 商户订单号
+                - payment_status (str): 支付状态
+                - product_id (str): 产品ID
+                - amount (str): 订单金额（元）
+                - total_fee (int): 订单金额（分）
+                - body (str): 商品描述
+                - transaction_id (str): 微信交易号（支付成功后才有）
+                - openid (str): 用户openid（支付成功后才有）
+                - trade_type (str): 交易类型（支付成功后才有）
+                - bank_type (str): 银行类型（支付成功后才有）
+                - fee_type (str): 货币类型，默认为"CNY"
+                - is_subscribe (str): 是否关注公众号（支付成功后才有）
+                - time_end (str): 支付完成时间（支付成功后才有）
+                - created_at (str): 订单创建时间
+                - updated_at (str): 订单更新时间
+                - paid_at (str): 支付时间（支付成功后才有）
+                - remark (str): 订单备注
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 订单不存在：返回错误信息"订单不存在"
+            - 获取订单详情失败：返回错误信息"获取订单详情失败"
+        """
+        data, success = await self._request("GET", f"/api/orders/{out_trade_no}")
+        if not success:
+            return {}, False
+        return data, True
+
+    async def update_order_status(self, out_trade_no: str, payment_status: str):
+        """
+        更新订单状态（异步版本）
+        
+        功能说明：
+            更新指定订单的支付状态，仅支持状态修改，其他字段不可修改。
+        
+        输入参数：
+            out_trade_no (str): 商户订单号，必填
+            payment_status (str): 支付状态，必填，可选值：
+                - "PENDING": 待支付
+                - "PAID": 已支付
+                - "REFUNDED": 已退款
+                - "CANCELLED": 已取消
+        
+        返回字段：
+            data (dict): 更新后的订单信息
+                - id (int): 订单ID
+                - out_trade_no (str): 商户订单号
+                - payment_status (str): 更新后的支付状态
+                - transaction_id (str): 微信交易号（如果已支付）
+                - openid (str): 用户openid（如果已支付）
+                - trade_type (str): 交易类型（如果已支付）
+                - bank_type (str): 银行类型（如果已支付）
+                - fee_type (str): 货币类型
+                - is_subscribe (str): 是否关注公众号（如果已支付）
+                - time_end (str): 支付完成时间（如果已支付）
+                - paid_at (str): 支付时间（如果已支付）
+                - updated_at (str): 订单更新时间
+                - remark (str): 订单备注
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 支付状态为空：返回错误信息"支付状态不能为空"
+            - 订单不存在：返回错误信息"订单不存在"
+            - 更新订单状态失败：返回错误信息"更新订单状态失败"
+        """
+        data = {"payment_status": payment_status}
+        data, success = await self._request(
+            "PUT", f"/api/orders/{out_trade_no}/status", json=data
+        )
+        if not success:
+            return {}, False
+        return data, True
+
+    async def delete_order(self, out_trade_no: str):
+        """
+        删除订单（异步版本）
+        
+        功能说明：
+            根据订单号删除指定的订单记录。
+        
+        输入参数：
+            out_trade_no (str): 商户订单号，必填
+        
+        返回字段：
+            data (None): 删除成功时返回None
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 订单不存在：返回错误信息"订单不存在"
+            - 删除订单失败：返回错误信息"删除订单失败"
+        """
+        data, success = await self._request("DELETE", f"/api/orders/{out_trade_no}")
+        if not success:
+            return {}, False
+        return data, True
+
+    async def get_order_stats(self):
+        """
+        获取订单统计信息（异步版本）
+        
+        功能说明：
+            获取订单的统计汇总信息，包括总订单数、各状态订单数量、总金额等。
+        
+        输入参数：
+            无
+        
+        返回字段：
+            data (dict): 订单统计信息
+                - total_orders (int): 总订单数量
+                - pending_orders (int): 待支付订单数量
+                - paid_orders (int): 已支付订单数量
+                - refunded_orders (int): 已退款订单数量
+                - total_amount (float): 总订单金额（元）
+                - total_fee (int): 总订单金额（分）
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 获取订单统计信息失败：返回错误信息"获取订单统计信息失败"
+        """
+        data, success = await self._request("GET", "/api/orders/stats/summary")
+        if not success:
+            return {}, False
+        return data, True
+
+    async def generate_qr_code(
+        self, out_trade_no: str, payment_channel: str = "WECHAT"
+    ):
+        """
+        生成支付二维码（异步版本）
+        
+        功能说明：
+            为指定订单生成支付二维码，支持微信支付和支付宝。二维码会自动上传到OSS并返回访问URL。
+        
+        输入参数：
+            out_trade_no (str): 商户订单号，必填
+            payment_channel (str, 可选): 支付渠道，默认为"WECHAT"，可选值：
+                - "WECHAT": 微信支付
+                - "ALIPAY": 支付宝（暂未实现）
+        
+        返回字段：
+            data (dict): 二维码信息
+                - qr_code_url (str): 二维码图片URL，可直接用于显示
+                - out_trade_no (str): 商户订单号
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 订单号为空：返回错误信息"订单号不能为空"
+            - 订单不存在：返回错误信息"订单不存在"
+            - 不支持的支付渠道：抛出ValueError异常
+            - 生成支付二维码失败：返回错误信息"生成支付二维码失败"
+        """
+        if payment_channel == "WECHAT":
+            url = "/api/orders/wx_pay/generate_qr_code"
+        elif payment_channel == "ALIPAY":
+            url = "/api/orders/ali_pay/generate_qr_code"
+        else:
+            raise ValueError("Invalid payment channel")
+        data, success = await self._request(
+            "POST", url, json={"out_trade_no": out_trade_no}
+        )
+        if not success:
+            return {}, False
+        return data, True
+
+    async def refund_order(self, out_trade_no: str, payment_channel: str = "WECHAT"):
+        """
+        申请订单退款（异步版本）
+        
+        功能说明：
+            为指定订单申请退款，支持微信支付和支付宝。退款申请提交后，系统会处理退款并更新订单状态。
+        
+        输入参数：
+            out_trade_no (str): 商户订单号，必填
+            payment_channel (str, 可选): 支付渠道，默认为"WECHAT"，可选值：
+                - "WECHAT": 微信支付
+                - "ALIPAY": 支付宝（暂未实现）
+        
+        返回字段：
+            data (dict): 退款信息
+                - out_refund_no (str): 退款单号，格式为"REFUND_订单号_时间戳"
+                - out_trade_no (str): 商户订单号
+                - total_fee (int): 退款金额（分）
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 订单号为空：返回错误信息"订单号不能为空"
+            - 订单不存在：返回错误信息"订单不存在"
+            - 订单状态不允许退款：返回错误信息"订单状态不允许退款"
+            - 不支持的支付渠道：抛出ValueError异常
+            - 退款申请失败：返回错误信息"退款申请失败"
+        """
+        if payment_channel == "WECHAT":
+            url = "/api/orders/wx_pay/refund"
+        elif payment_channel == "ALIPAY":
+            url = "/api/orders/ali_pay/refund"
+        else:
+            raise ValueError("Invalid payment channel")
+        data, success = await self._request(
+            "POST", url, json={"out_trade_no": out_trade_no}
+        )
+        if not success:
+            return {}, False
+        return data, True

pixelarraythirdparty/product/product.py

@@ -14,6 +14,46 @@ class ProductManager(Client):
         features: str,
         sort_order: int,
     ):
+        """
+        创建产品
+        
+        功能说明：
+            创建新的产品，支持订阅产品和一次性产品，产品信息包括名称、描述、价格、分类等。
+        
+        输入参数：
+            name (str): 产品名称，必填
+            description (str): 产品描述，必填
+            price (float): 产品价格（元），必填
+            category (str): 产品分类，必填
+            status (str): 产品状态，必填，可选值：
+                - "ACTIVE": 激活
+                - "INACTIVE": 停用
+            is_subscription (bool): 是否为订阅产品，必填
+            subscription_period (str): 订阅周期，必填，可选值：
+                - "MONTHLY": 月付
+                - "YEARLY": 年付
+            features (str): 产品特性，JSON格式字符串，必填
+            sort_order (int): 排序权重，必填
+        
+        返回字段：
+            data (dict): 产品信息
+                - id (int): 产品ID
+                - name (str): 产品名称
+                - description (str): 产品描述
+                - price (float): 产品价格（元）
+                - category (str): 产品分类
+                - status (str): 产品状态
+                - is_subscription (bool): 是否为订阅产品
+                - subscription_period (str): 订阅周期
+                - features (str): 产品特性（JSON格式）
+                - sort_order (int): 排序权重
+                - created_at (str): 产品创建时间
+                - updated_at (str): 产品更新时间
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 产品创建失败：返回错误信息"产品创建失败"
+        """
         data = {
             "name": name,
             "description": description,
@@ -38,6 +78,44 @@ class ProductManager(Client):
         category: str = None,
         name: str = None,
     ):
+        """
+        获取产品列表
+        
+        功能说明：
+            分页查询产品列表，支持按状态、分类和名称进行筛选。
+        
+        输入参数：
+            page (int, 可选): 页码，默认为1，最小值为1
+            page_size (int, 可选): 每页数量，默认为10，范围为1-1000
+            status (str, 可选): 产品状态筛选，可选值：
+                - "ACTIVE": 激活
+                - "INACTIVE": 停用
+            category (str, 可选): 产品分类筛选
+            name (str, 可选): 产品名称搜索，支持模糊匹配
+        
+        返回字段：
+            data (dict): 产品列表信息
+                - products (list): 产品列表
+                    - id (int): 产品ID
+                    - name (str): 产品名称
+                    - description (str): 产品描述
+                    - price (float): 产品价格（元）
+                    - category (str): 产品分类
+                    - status (str): 产品状态
+                    - is_subscription (bool): 是否为订阅产品
+                    - subscription_period (str): 订阅周期
+                    - features (str): 产品特性（JSON格式）
+                    - sort_order (int): 排序权重
+                    - created_at (str): 产品创建时间
+                    - updated_at (str): 产品更新时间
+                - total (int): 总产品数量
+                - page (int): 当前页码
+                - page_size (int): 每页数量
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 获取产品列表失败：返回错误信息"获取产品列表失败"
+        """
         params = {
             "page": page,
             "page_size": page_size,
@@ -57,6 +135,35 @@ class ProductManager(Client):
         return data, True
 
     def get_product_detail(self, product_id: str):
+        """
+        获取产品详情
+        
+        功能说明：
+            根据产品ID获取产品的详细信息。
+        
+        输入参数：
+            product_id (str): 产品ID，必填
+        
+        返回字段：
+            data (dict): 产品详细信息
+                - id (int): 产品ID
+                - name (str): 产品名称
+                - description (str): 产品描述
+                - price (float): 产品价格（元）
+                - category (str): 产品分类
+                - status (str): 产品状态
+                - is_subscription (bool): 是否为订阅产品
+                - subscription_period (str): 订阅周期
+                - features (str): 产品特性（JSON格式）
+                - sort_order (int): 排序权重
+                - created_at (str): 产品创建时间
+                - updated_at (str): 产品更新时间
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 产品不存在：返回错误信息"产品不存在"
+            - 获取产品详情失败：返回错误信息"获取产品详情失败"
+        """
         data, success = self._request("GET", f"/api/products/{product_id}")
         if not success:
             return {}, False
@@ -75,6 +182,48 @@ class ProductManager(Client):
         features: str,
         sort_order: int,
     ):
+        """
+        更新产品信息
+        
+        功能说明：
+            更新指定产品的信息，包括名称、描述、价格、状态等。
+        
+        输入参数：
+            product_id (str): 产品ID，必填
+            name (str): 产品名称，必填
+            description (str): 产品描述，必填
+            price (float): 产品价格（元），必填
+            category (str): 产品分类，必填
+            status (str): 产品状态，必填，可选值：
+                - "ACTIVE": 激活
+                - "INACTIVE": 停用
+            is_subscription (bool): 是否为订阅产品，必填
+            subscription_period (str): 订阅周期，必填，可选值：
+                - "MONTHLY": 月付
+                - "YEARLY": 年付
+            features (str): 产品特性，JSON格式字符串，必填
+            sort_order (int): 排序权重，必填
+        
+        返回字段：
+            data (dict): 更新后的产品信息
+                - id (int): 产品ID
+                - name (str): 产品名称
+                - description (str): 产品描述
+                - price (float): 产品价格（元）
+                - category (str): 产品分类
+                - status (str): 产品状态
+                - is_subscription (bool): 是否为订阅产品
+                - subscription_period (str): 订阅周期
+                - features (str): 产品特性（JSON格式）
+                - sort_order (int): 排序权重
+                - created_at (str): 产品创建时间
+                - updated_at (str): 产品更新时间
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 产品不存在：返回错误信息"产品不存在"
+            - 产品更新失败：返回错误信息"产品更新失败"
+        """
         data = {
             "name": name,
             "description": description,
@@ -92,12 +241,46 @@ class ProductManager(Client):
         return data, True
 
     def delete_product(self, product_id: str):
+        """
+        删除产品
+        
+        功能说明：
+            根据产品ID删除指定的产品记录。
+        
+        输入参数：
+            product_id (str): 产品ID，必填
+        
+        返回字段：
+            data (None): 删除成功时返回None
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 产品不存在：返回错误信息"产品不存在"
+            - 删除产品失败：返回错误信息"删除产品失败"
+        """
         data, success = self._request("DELETE", f"/api/products/{product_id}")
         if not success:
             return {}, False
         return data, True
 
     def get_product_categories(self):
+        """
+        获取产品分类列表
+        
+        功能说明：
+            获取所有可用的产品分类列表。
+        
+        输入参数：
+            无
+        
+        返回字段：
+            data (dict): 产品分类信息
+                - categories (list): 产品分类列表，如["subscription", "service", "addon"]
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 获取产品分类失败：返回错误信息"获取产品分类失败"
+        """
         data, success = self._request("GET", "/api/products/categories/list")
         if not success:
             return {}, False

pixelarraythirdparty/user/user.py

@@ -11,6 +11,39 @@ class UserManager(Client):
         role: Optional[str] = None,
         is_active: Optional[bool] = None,
     ):
+        """
+        获取用户列表
+        
+        功能说明：
+            分页查询用户列表，支持按角色和状态进行筛选。仅管理员可访问。
+        
+        输入参数：
+            page (int, 可选): 页码，默认为1，最小值为1
+            page_size (int, 可选): 每页数量，默认为10，范围为1-1000
+            role (str, 可选): 用户角色筛选，可选值：
+                - "admin": 管理员
+                - "user": 普通用户
+            is_active (bool, 可选): 用户状态筛选，True为激活，False为禁用
+        
+        返回字段：
+            data (dict): 用户列表信息
+                - users (list): 用户列表
+                    - id (int): 用户ID
+                    - username (str): 用户名
+                    - email (str): 邮箱地址
+                    - role (str): 用户角色
+                    - is_active (bool): 是否激活
+                    - created_at (str): 用户创建时间
+                    - last_login_at (str): 最后登录时间
+                - total (int): 总用户数量
+                - page (int): 当前页码
+                - page_size (int): 每页数量
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 权限不足：返回错误信息"权限不足"
+            - 获取用户列表失败：返回错误信息"获取用户列表失败"
+        """
         params = {"page": page, "page_size": page_size}
         if role is not None:
             params["role"] = role
@@ -22,6 +55,36 @@ class UserManager(Client):
         return data, True
 
     def create_user(self, username: str, password: str, email: str, role: str):
+        """
+        创建用户
+        
+        功能说明：
+            创建新的用户账户，仅管理员可访问。
+        
+        输入参数：
+            username (str): 用户名，必填
+            password (str): 密码，必填
+            email (str): 邮箱地址，必填
+            role (str): 用户角色，必填，可选值：
+                - "admin": 管理员
+                - "user": 普通用户
+        
+        返回字段：
+            data (dict): 用户信息
+                - id (int): 用户ID
+                - username (str): 用户名
+                - email (str): 邮箱地址
+                - role (str): 用户角色
+                - is_active (bool): 是否激活，默认为True
+                - created_at (str): 用户创建时间
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 权限不足：返回错误信息"权限不足"
+            - 用户名已存在：返回错误信息"用户名已存在"
+            - 邮箱已存在：返回错误信息"邮箱已存在"
+            - 用户创建失败：返回错误信息"用户创建失败"
+        """
         data = {
             "username": username,
             "password": password,
@@ -36,6 +99,39 @@ class UserManager(Client):
     def update_user(
         self, user_id: int, username: str, email: str, role: str, is_active: bool
     ):
+        """
+        更新用户信息
+        
+        功能说明：
+            更新指定用户的信息，包括用户名、邮箱、角色和状态。仅管理员可访问。
+        
+        输入参数：
+            user_id (int): 用户ID，必填
+            username (str): 用户名，必填
+            email (str): 邮箱地址，必填
+            role (str): 用户角色，必填，可选值：
+                - "admin": 管理员
+                - "user": 普通用户
+            is_active (bool): 是否激活，必填
+        
+        返回字段：
+            data (dict): 更新后的用户信息
+                - id (int): 用户ID
+                - username (str): 用户名
+                - email (str): 邮箱地址
+                - role (str): 用户角色
+                - is_active (bool): 是否激活
+                - created_at (str): 用户创建时间
+                - updated_at (str): 用户信息更新时间
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 权限不足：返回错误信息"权限不足"
+            - 用户不存在：返回错误信息"用户不存在"
+            - 用户名已存在：返回错误信息"用户名已存在"
+            - 邮箱已存在：返回错误信息"邮箱已存在"
+            - 用户信息更新失败：返回错误信息"用户信息更新失败"
+        """
         data = {
             "username": username,
             "email": email,
@@ -48,18 +144,80 @@ class UserManager(Client):
         return data, True
 
     def delete_user(self, user_id: int):
+        """
+        删除用户
+        
+        功能说明：
+            根据用户ID删除指定的用户记录。仅管理员可访问。
+        
+        输入参数：
+            user_id (int): 用户ID，必填
+        
+        返回字段：
+            data (None): 删除成功时返回None
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 权限不足：返回错误信息"权限不足"
+            - 用户不存在：返回错误信息"用户不存在"
+            - 删除用户失败：返回错误信息"删除用户失败"
+        """
         data, success = self._request("DELETE", f"/api/users/{user_id}")
         if not success:
             return {}, False
         return data, True
 
     def get_user_detail(self, user_id: int):
+        """
+        获取用户详情
+        
+        功能说明：
+            根据用户ID获取用户的详细信息。仅管理员可访问。
+        
+        输入参数：
+            user_id (int): 用户ID，必填
+        
+        返回字段：
+            data (dict): 用户详细信息
+                - id (int): 用户ID
+                - username (str): 用户名
+                - email (str): 邮箱地址
+                - role (str): 用户角色
+                - is_active (bool): 是否激活
+                - created_at (str): 用户创建时间
+                - last_login_at (str): 最后登录时间
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 权限不足：返回错误信息"权限不足"
+            - 用户不存在：返回错误信息"用户不存在"
+            - 获取用户详情失败：返回错误信息"获取用户详情失败"
+        """
         data, success = self._request("GET", f"/api/users/{user_id}")
         if not success:
             return {}, False
         return data, True
 
     def reset_user_password(self, user_id: int, new_password: str):
+        """
+        重置用户密码
+        
+        功能说明：
+            重置指定用户的密码。仅管理员可访问。
+        
+        输入参数：
+            user_id (int): 用户ID，必填
+            new_password (str): 新密码，必填
+        
+        返回字段：
+            data (None): 重置成功时返回None
+            success (bool): 操作是否成功
+        
+        异常情况：
+            - 权限不足：返回错误信息"权限不足"
+            - 用户不存在：返回错误信息"用户不存在"
+            - 密码重置失败：返回错误信息"密码重置失败"
+        """
         data = {"new_password": new_password}
         data, success = self._request(
             "POST", f"/api/users/{user_id}/reset-password", json=data

{pixelarraythirdparty-1.0.3.dist-info → pixelarraythirdparty-1.0.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pixelarraythirdparty
-Version: 1.0.3
+Version: 1.0.5
 Summary: PixelArray 第三方微服务客户端
 Author-email: Lu qi <qi.lu@pixelarrayai.com>
 License-Expression: MIT

pixelarraythirdparty-1.0.5.dist-info/RECORD

@@ -0,0 +1,15 @@
+pixelarraythirdparty/__init__.py,sha256=cLw3MHNC7dl2u-nOF78E6O_r2dUgmwl3x4wzSpulw1s,458
+pixelarraythirdparty/client.py,sha256=r63EDeyPhf3Y1sORW24tDSIqo2c8E3pwbik7r0Xy5zo,1678
+pixelarraythirdparty/celery/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pixelarraythirdparty/celery/celery.py,sha256=paZFSnWKvwNEDyi-tr4z2dwWxlLMX58WmS_hDezyuaE,5690
+pixelarraythirdparty/order/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pixelarraythirdparty/order/order.py,sha256=kBhpinympJjsu-4UmUazXhJTCLkGlMHcjmpOXbnVmek,27144
+pixelarraythirdparty/product/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pixelarraythirdparty/product/product.py,sha256=_rcAtsZEWA3Ta1R9SBWnzQmjab-vf3bnSEySb4PPU-c,10586
+pixelarraythirdparty/user/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pixelarraythirdparty/user/user.py,sha256=UY-O7qO8AIWo3GRQaHqC3AMQc4w3bD9KgmPLoUo-l0I,8380
+pixelarraythirdparty-1.0.5.dist-info/licenses/LICENSE,sha256=O-g1dUr0U50rSIvmWE9toiVkSgFpVt72_MHITbWvAqA,1067
+pixelarraythirdparty-1.0.5.dist-info/METADATA,sha256=s86-xWcTp2UgdmJP2hLTpW4rZU91cjUU-8WLKjGq3SI,993
+pixelarraythirdparty-1.0.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pixelarraythirdparty-1.0.5.dist-info/top_level.txt,sha256=dzG2Ut8j7noUqj_0ZQjcIDAeHYCh_9WtlxjAxtoyufo,21
+pixelarraythirdparty-1.0.5.dist-info/RECORD,,

pixelarraythirdparty-1.0.3.dist-info/RECORD

@@ -1,15 +0,0 @@
-pixelarraythirdparty/__init__.py,sha256=TYuj96ZwZ4VXhB9Xn4KoEWpoJVsChUjzoWSRZONmC-U,458
-pixelarraythirdparty/client.py,sha256=dJlIrMlr1M4AGHvaLw191uaPnQbQ12_BGx8DTDTPkZQ,802
-pixelarraythirdparty/celery/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pixelarraythirdparty/celery/celery.py,sha256=Oaa7pBztL-FM0X5NSCjjfZP80AUsnnme5Z3RxXIJsZg,1178
-pixelarraythirdparty/order/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pixelarraythirdparty/order/order.py,sha256=kmJNAvfiXxhjOhRbD3JTl1saE8aetMZ0TFR9NjPsaIM,3208
-pixelarraythirdparty/product/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pixelarraythirdparty/product/product.py,sha256=eHU0VKal1QpJs6F4_VxLoBYeeqQ19elEogH2Qpw7IDo,3029
-pixelarraythirdparty/user/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pixelarraythirdparty/user/user.py,sha256=tbcFsrNEdWz4op7V_zJ5o8neBuI4ogl4dgHS-uSIAX0,2155
-pixelarraythirdparty-1.0.3.dist-info/licenses/LICENSE,sha256=O-g1dUr0U50rSIvmWE9toiVkSgFpVt72_MHITbWvAqA,1067
-pixelarraythirdparty-1.0.3.dist-info/METADATA,sha256=_BcKEA0W8joCfUZcvDqyKBkBXKGyWUwIDVI16boT7s4,993
-pixelarraythirdparty-1.0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pixelarraythirdparty-1.0.3.dist-info/top_level.txt,sha256=dzG2Ut8j7noUqj_0ZQjcIDAeHYCh_9WtlxjAxtoyufo,21
-pixelarraythirdparty-1.0.3.dist-info/RECORD,,