21. ఎక్సెప్షన్ హ్యాండ్లింగ్ & కస్టమ్ ఎర్రర్స్ (Robust Fault-Tolerant Code)

# =====================================================================
# చాప్టర్ 21 డెమో 1: try - except - else - finally ఆర్కిటెక్చర్
# =====================================================================

def transfer_funds(sender_bal: float, amount: float):
    print(f"
--- లావాదేవీ ప్రారంభం: మొత్తం ₹{amount:,.2f} ---")
    connection_open = True
    print("🔌 బ్యాంకింగ్ సెక్యూర్ గేట్‌వే కనెక్ట్ చేయబడింది.")

    try:
        if amount <= 0:
            raise ValueError("బదిలీ మొత్తం ₹0 కంటే ఎక్కువ ఉండాలి!")
        if amount > sender_bal:
            raise ArithmeticError("ఖాతాలో తగినంత నగదు నిల్వ లేదు!")

        new_balance = sender_bal - amount

    except ValueError as ve:
        print(f"❌ ఇన్‌పుట్ లోపం: {ve}")
    except ArithmeticError as ae:
        print(f"❌ బ్యాంకింగ్ నిల్వ లోపం: {ae}")
    else:
        # ఎర్రర్ రాకపోతేనే ఎగ్జిక్యూట్ అవుతుంది!
        print(f"✅ లావాదేవీ విజయవంతం! తాజా బ్యాలెన్స్: ₹{new_balance:,.2f}")
    finally:
        # ఎర్రర్ వచ్చినా రాకపోయినా ఖచ్చితంగా రన్ అవుతుంది!
        connection_open = False
        print("🔒 సెక్యూర్ గేట్‌వే కనెక్షన్ క్లోజ్ చేయబడింది (Cleaned up).")

# టెస్ట్ 1: విజయవంతమైన బదిలీ
transfer_funds(50000.0, 15000.0)

# టెస్ట్ 2: తగినంత నిల్వ లేని సందర్భం
transfer_funds(10000.0, 25000.0)

# కస్టమ్ ఎక్సెప్షన్ క్లాసెస్
class OutOfStockError(Exception):
    """ఉత్పత్తి నిల్వ లేనప్పుడు వచ్చే ఎర్రర్."""
    pass

class InsufficientBalanceError(Exception):
    """యూజర్ వాలెట్‌లో తగినంత నగదు లేనప్పుడు వచ్చే ఎర్రర్."""
    pass

def checkout_order(item_name: str, requested_qty: int, available_stock: int, total_price: float, wallet_bal: float):
    if requested_qty > available_stock:
        raise OutOfStockError(f"క్షమించండి! '{item_name}' స్టాక్ కేవలం {available_stock} మాత్రమే ఉంది.")
    if total_price > wallet_bal:
        shortfall = total_price - wallet_bal
        raise InsufficientBalanceError(f"వాలెట్‌లో ₹{shortfall:,.2f} తక్కువగా ఉంది!")

    print(f"🎉 ఆర్డర్ కన్ఫర్మ్ అయింది! వస్తువు: {item_name} (పరిమాణం: {requested_qty})")

# టెస్టింగ్
try:
    checkout_order("స్మార్ట్‌ఫోన్", requested_qty=3, available_stock=1, total_price=45000, wallet_bal=50000)
except OutOfStockError as ose:
    print(f"🚨 ఇన్వెంటరీ హెచ్చరిక: {ose}")
except InsufficientBalanceError as ibe:
    print(f"🚨 పేమెంట్ హెచ్చరిక: {ibe}")

# =====================================================================
# చాప్టర్ 21 మినీ ప్రాజెక్ట్: FinTech Resilient Payment Gateway Engine
# కాన్సెప్ట్స్: try-except-else-finally, Custom Domain Exceptions,
#             Retry Logic, Circuit Breaker Basics, Audit Logging
# =====================================================================
import time

# 1. కస్టమ్ బ్యాంకింగ్ ఎక్సెప్షన్ క్లాసెస్
class PaymentException(Exception):
    """అన్ని పేమెంట్ వైఫల్యాలకు బేస్ క్లాస్."""
    pass

class CardExpiredError(PaymentException):
    pass

class InsufficientFundsError(PaymentException):
    pass

class NetworkGatewayTimeoutError(PaymentException):
    pass

class FinTechPaymentProcessor:
    def __init__(self, merchant_id: str):
        self.merchant_id = merchant_id
        self.audit_log = []

    def log_event(self, txn_id: str, status: str, message: str):
        entry = {
            "txn_id": txn_id,
            "status": status,
            "message": message,
            "timestamp": time.strftime("%Y-%m-%d %H:%M:%S")
        }
        self.audit_log.append(entry)

    def authorize_card(self, card_number: str, expiry_year: int) -> bool:
        if expiry_year < 2026:
            raise CardExpiredError("కార్డ్ గడువు ముగిసింది! దయచేసి చెల్లుబాటు అయ్యే కార్డును ఉపయోగించండి.")
        return True

    def deduct_balance(self, current_balance: float, amount: float) -> float:
        if amount > current_balance:
            shortfall = amount - current_balance
            raise InsufficientFundsError(f"ఖాతాలో సరిపడా నిల్వ లేదు! కొరత: ₹{shortfall:,.2f}")
        return current_balance - amount

    def simulate_bank_network_call(self, attempt_number: int):
        # 1వ ప్రయత్నంలో నెట్‌వర్క్ ఫెయిల్యూర్ సిమ్యులేషన్
        if attempt_number == 1:
            raise NetworkGatewayTimeoutError("బ్యాంక్ సర్వర్ నుండి రెస్పాన్స్ రాలేదు (HTTP 504 Timeout)")
        return True

    def process_transaction(self, txn_id: str, card_no: str, exp_year: int, balance: float, amount: float):
        print(f"
==================================================")
        print(f"💳 ప్రాసెసింగ్ లావాదేవీ: {txn_id} (మొత్తం: ₹{amount:,.2f})")
        print(f"==================================================")
        
        session_active = True
        try:
            # దశ 1: కార్డ్ వ్యాలిడేషన్
            self.authorize_card(card_no, exp_year)

            # దశ 2: బ్యాలెన్స్ తనిఖీ & డిడక్షన్
            new_bal = self.deduct_balance(balance, amount)

            # దశ 3: ఆటోమేటిక్ రీట్రైతో కూడిన నెట్‌వర్క్ కాల్
            max_retries = 2
            for attempt in range(1, max_retries + 1):
                try:
                    print(f"  📡 బ్యాంక్ గేట్‌వేకు కనెక్ట్ అవుతోంది (ప్రయత్నం {attempt}/{max_retries})...")
                    self.simulate_bank_network_call(attempt)
                    break
                except NetworkGatewayTimeoutError as nte:
                    print(f"  ⚠️ హెచ్చరిక: {nte}")
                    if attempt == max_retries:
                        raise  # రీట్రైలు ముగిస్తే బయట except కి పంపడం

        except CardExpiredError as cee:
            self.log_event(txn_id, "FAILED", f"కార్డ్ ఎక్స్‌పైరీ లోపం: {cee}")
            print(f"❌ లావాదేవీ విఫలం: {cee}")
        except InsufficientFundsError as ife:
            self.log_event(txn_id, "FAILED", f"నిధుల కొరత: {ife}")
            print(f"❌ లావాదేవీ విఫలం: {ife}")
        except NetworkGatewayTimeoutError as nge:
            self.log_event(txn_id, "RETRY_EXHAUSTED", "నెట్‌వర్క్ టైమ్‌అవుట్ కారణంగా విఫలమైంది")
            print(f"🚨 క్రిటికల్ ఎర్రర్: గేట్‌వే అందుబాటులో లేదు. నగదు కట్ కాలేదు.")
        except Exception as unk:
            self.log_event(txn_id, "CRITICAL", f"ఊహించని లోపం: {unk}")
            print(f"💥 అన్‌ఎక్స్‌పెక్టెడ్ సిస్టమ్ ఎర్రర్: {unk}")
        else:
            # ఎటువంటి ఎర్రర్ రాకపోతేనే ఎగ్జిక్యూట్ అవుతుంది!
            self.log_event(txn_id, "SUCCESS", f"విజయవంతంగా పూర్తయింది. మిగిలిన బ్యాలెన్స్: ₹{new_bal:,.2f}")
            print(f"✅ లావాదేవీ విజయవంతం! మర్చంట్: {self.merchant_id}")
            print(f"💰 కస్టమర్ తాజా బ్యాలెన్స్: ₹{new_bal:,.2f}")
        finally:
            # సెషన్ క్లీనప్
            session_active = False
            print(f"🔒 [AUDIT] సెక్యూర్ సెషన్ క్లోజ్ చేయబడింది. ఆడిట్ లాగ్ అప్‌డేట్ అయింది.")


# =====================================================================
# సిస్టమ్ టెస్టింగ్ డ్రైవర్
# =====================================================================
processor = FinTechPaymentProcessor(merchant_id="TELUGU_PAY_MERCHANT_007")

# కేస్ 1: కార్డ్ గడువు ముగిసిన కేసు
processor.process_transaction("TXN_1001", "4532-XXXX-XXXX-8901", exp_year=2024, balance=50000, amount=4500)

# కేస్ 2: సరిపడా బ్యాలెన్స్ లేని కేసు
processor.process_transaction("TXN_1002", "4532-XXXX-XXXX-8901", exp_year=2028, balance=2000, amount=8500)

# కేస్ 3: మొదటిసారి ఫెయిల్ అయి ఆటో-రీట్రైతో సక్సెస్ అయ్యే కేసు
processor.process_transaction("TXN_1003", "4532-XXXX-XXXX-8901", exp_year=2029, balance=75000, amount=12000)

# పూర్తి ఆడిట్ లాగ్ ప్రింట్ చేయడం
print("
" + "=" * 55)
print("📊 FINTECH AUDIT TRAIL LOGS:")
print("=" * 55)
for log in processor.audit_log:
    print(f"• [{log['timestamp']}] {log['txn_id']} | {log['status']} | {log['message']}")
print("=" * 55)