"""
支付渠道抽象基类
定义统一的支付接口，便于切换不同支付渠道（XorPay、ZPAY 等）
"""
from abc import ABC, abstractmethod
from typing import Any, Dict, Optional


class PaymentProvider(ABC):
    """支付渠道抽象基类"""

    @property
    @abstractmethod
    def name(self) -> str:
        """支付渠道名称"""
        pass

    @abstractmethod
    def create_order(
        self,
        *,
        order_id: str,
        name: str,
        total_fee_yuan: str,
        pay_type: str,
        notify_url: str,
        return_url: Optional[str] = None,
        client_ip: Optional[str] = None,
        extra: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """
        创建支付订单
        :return: 包含支付跳转信息等，格式由各渠道自定义
        """
        pass

    @abstractmethod
    def verify_notify(self, data: Dict[str, Any]) -> bool:
        """验证异步通知签名"""
        pass

    @abstractmethod
    def parse_notify(self, data: Dict[str, Any]) -> Dict[str, Any]:
        """
        解析异步通知，提取统一字段
        :return: {
            "order_id": str,      # 商户订单号
            "trade_no": str,      # 渠道订单号
            "pay_price": str,     # 实付金额（元）
            "pay_time": str,      # 支付时间
            "trade_status": str,  # 支付状态
        }
        """
        pass

    @abstractmethod
    def success_response(self) -> str:
        """异步通知成功时需返回的字符串（如 'ok' 或 'success'）"""
        pass