refaktorálás javításai

backend/app/services/financial_interfaces.py

@@ -0,0 +1,187 @@
+"""
+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