service-finder/backend/app/services/financial_interfaces.py

"""
Financial Interfaces - Absztrakt alaposztályok a fizetési és számlázási szolgáltatásokhoz.

Ez a modul definiálja a kötelező interfészeket, amelyeket minden konkrét implementációnak
követnie kell a fizetési átjárók és számlázási szolgáltatások esetében.
"""

from abc import ABC, abstractmethod
from typing import Optional, Dict, Any
from decimal import Decimal


class BasePaymentGateway(ABC):
    """
    Absztrakt osztály fizetési átjárók számára.
    
    Minden fizetési szolgáltató (Stripe, PayPal, stb.) implementálja ezt az interfészt,
    hogy a FinancialOrchestrator egységesen kezelhesse őket.
    """
    
    @abstractmethod
    async def create_intent(
        self,
        amount: Decimal,
        currency: str = "HUF",
        metadata: Optional[Dict[str, Any]] = None,
        **kwargs
    ) -> Dict[str, Any]:
        """
        Fizetési szándék létrehozása a külső szolgáltatónál.
        
        Args:
            amount: A fizetendő összeg
            currency: Pénznem (alapértelmezett: HUF)
            metadata: Egyéni metaadatok
            **kwargs: További paraméterek a konkrét implementáció számára
            
        Returns:
            Szótár a fizetési szándék adataival (pl. client_secret, id, status)
            
        Raises:
            PaymentGatewayError: Ha a fizetési szándék létrehozása sikertelen
        """
        pass
    
    @abstractmethod
    async def verify_payment(
        self,
        payment_intent_id: str,
        **kwargs
    ) -> Dict[str, Any]:
        """
        Fizetés státuszának ellenőrzése a külső szolgáltatónál.
        
        Args:
            payment_intent_id: A fizetési szándék azonosítója
            **kwargs: További paraméterek
            
        Returns:
            Szótár a fizetés részleteivel (pl. status, amount, customer)
            
        Raises:
            PaymentGatewayError: Ha az ellenőrzés sikertelen
        """
        pass
    
    @abstractmethod
    async def refund_payment(
        self,
        payment_intent_id: str,
        amount: Optional[Decimal] = None,
        **kwargs
    ) -> Dict[str, Any]:
        """
        Fizetés visszatérítése.
        
        Args:
            payment_intent_id: A fizetési szándék azonosítója
            amount: Visszatérítendő összeg (ha None, akkor teljes összeg)
            **kwargs: További paraméterek
            
        Returns:
            Szótár a visszatérítés részleteivel
            
        Raises:
            PaymentGatewayError: Ha a visszatérítés sikertelen
        """
        pass


class BaseInvoicingService(ABC):
    """
    Absztrakt osztály számlázási szolgáltatások számára.
    
    Minden számlázási rendszer (számlázz.hu, NAV Online Számla, stb.) implementálja
    ezt az interfészt a számlák egységes kezeléséhez.
    """
    
    @abstractmethod
    async def issue_invoice(
        self,
        issuer_id: int,
        customer_data: Dict[str, Any],
        items: list[Dict[str, Any]],
        **kwargs
    ) -> Dict[str, Any]:
        """
        Szála kiállítása.
        
        Args:
            issuer_id: A számlakiállító (Issuer) azonosítója
            customer_data: Ügyfél adatok (név, cím, adószám, stb.)
            items: Számla tételek listája
            **kwargs: További paraméterek
            
        Returns:
            Szótár a számla részleteivel (pl. invoice_number, issue_date, total_amount)
            
        Raises:
            InvoicingError: Ha a számla kiállítása sikertelen
        """
        pass
    
    @abstractmethod
    async def get_invoice_status(
        self,
        invoice_id: str,
        **kwargs
    ) -> Dict[str, Any]:
        """
        Számla státuszának lekérdezése.
        
        Args:
            invoice_id: A számla azonosítója
            **kwargs: További paraméterek
            
        Returns:
            Szótár a számla státuszával és további adatokkal
            
        Raises:
            InvoicingError: Ha a státusz lekérdezése sikertelen
        """
        pass
    
    @abstractmethod
    async def cancel_invoice(
        self,
        invoice_id: str,
        reason: Optional[str] = None,
        **kwargs
    ) -> Dict[str, Any]:
        """
        Számla érvénytelenítése.
        
        Args:
            invoice_id: A számla azonosítója
            reason: Érvénytelenítés oka
            **kwargs: További paraméterek
            
        Returns:
            Szótár az érvénytelenítés eredményével
            
        Raises:
            InvoicingError: Ha az érvénytelenítés sikertelen
        """
        pass


# Egyéni kivételek a finanszírozási szolgáltatásokhoz
class FinancialServiceError(Exception):
    """Alap kivétel az összes finanszírozási szolgáltatási hibához."""
    pass


class PaymentGatewayError(FinancialServiceError):
    """Kivétel fizetési átjáró hibákhoz."""
    pass


class InvoicingError(FinancialServiceError):
    """Kivétel számlázási hibákhoz."""
    pass


class InsufficientFundsError(FinancialServiceError):
    """Kivétel elégtelen egyenleg esetén."""
    pass