25. గ్రాండ్ ఫినాలే — రియల్-వరల్డ్ పైథాన్ క్యాప్‌స్టోన్ ప్రాజెక్ట్ (Enterprise Academy Engine)

# డొమైన్ ఎక్సెప్షన్స్
class AcademyError(Exception): pass
class CourseCapacityFullError(AcademyError): pass
class InsufficientFundsError(AcademyError): pass
class StudentAlreadyEnrolledError(AcademyError): pass

# పర్సన్ బేస్ క్లాస్
class Person:
    def __init__(self, person_id: str, name: str, email: str):
        self.person_id = person_id
        self.name = name
        self.email = email

    def __repr__(self):
        return f"{self.__class__.__name__}(id='{self.person_id}', name='{self.name}')"

# స్టూడెంట్ మోడల్
class Student(Person):
    def __init__(self, student_id: str, name: str, email: str, wallet_balance: float = 0.0):
        super().__init__(student_id, name, email)
        self.wallet_balance = float(wallet_balance)
        self.enrolled_courses = []

    def deduct_fee(self, amount: float):
        if self.wallet_balance < amount:
            shortfall = amount - self.wallet_balance
            raise InsufficientFundsError(f"వాలెట్‌లో ₹{shortfall:,.2f} తక్కువగా ఉంది!")
        self.wallet_balance -= amount

    def to_dict(self):
        return {
            "id": self.person_id,
            "name": self.name,
            "email": self.email,
            "wallet": self.wallet_balance,
            "courses": self.enrolled_courses
        }

# కోర్సు మోడల్
class Course:
    def __init__(self, code: str, title: str, fee: float, max_capacity: int = 30):
        self.code = code
        self.title = title
        self.fee = float(fee)
        self.max_capacity = max_capacity
        self.enrolled_students = []

    @property
    def is_full(self) -> bool:
        return len(self.enrolled_students) >= self.max_capacity

    def enroll_student(self, student: Student):
        if self.is_full:
            raise CourseCapacityFullError(f"కోర్సు '{self.title}' లో సీట్లు నిండిపోయాయి! (పరిమితి: {self.max_capacity})")
        if student.person_id in self.enrolled_students:
            raise StudentAlreadyEnrolledError(f"విద్యార్థి {student.name} ఇప్పటికే ఈ కోర్సులో ఉన్నారు!")
        
        # ఫీజు కట్ చేయడం
        student.deduct_fee(self.fee)
        self.enrolled_students.append(student.person_id)
        student.enrolled_courses.append(self.code)

    def to_dict(self):
        return {
            "code": self.code,
            "title": self.title,
            "fee": self.fee,
            "capacity": self.max_capacity,
            "enrolled": self.enrolled_students
        }

import json
import os

class AcademyRepository:
    def __init__(self, storage_path: str = "academy_db.json"):
        self.storage_path = storage_path

    def save_academy_state(self, students: dict, courses: dict):
        payload = {
            "version": "2026.1",
            "students": {sid: s.to_dict() for sid, s in students.items()},
            "courses": {cid: c.to_dict() for cid, c in courses.items()}
        }
        temp_file = f"{self.storage_path}.tmp"
        with open(temp_file, "w", encoding="utf-8") as f:
            json.dump(payload, f, indent=2, ensure_ascii=False)
        
        # అటామిక్ రీప్లేస్‌మెంట్ (క్రాష్-ప్రూఫ్)
        os.replace(temp_file, self.storage_path)
        print(f"💾 డేటాబేస్ సురక్షితంగా '{self.storage_path}' లో సేవ్ చేయబడింది.")

    def load_academy_state(self):
        if not os.path.exists(self.storage_path):
            return {}, {}
        with open(self.storage_path, "r", encoding="utf-8") as f:
            data = json.load(f)
        return data.get("students", {}), data.get("courses", {})

# =====================================================================
# చాప్టర్ 25 గ్రాండ్ ఫినాలే: NextGen Cyber Academy Management Engine
# 25 చాప్టర్ల ఫీచర్లు: OOP, Dunder Methods, Custom Exceptions,
#                      Audit Decorators, Generators, JSON Persistence
# =====================================================================
import json
import functools
import time

# 1. ఆడిట్ & పెర్ఫార్మెన్స్ డెకరేటర్
def audit_logged(action_name: str):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            t0 = time.perf_counter()
            print(f"⚡ [ACTION] '{action_name}' ప్రారంభమైంది...")
            try:
                res = func(*args, **kwargs)
                elapsed = (time.perf_counter() - t0) * 1000
                print(f"✅ [SUCCESS] '{action_name}' ముగిసింది ({elapsed:.2f}ms)
")
                return res
            except Exception as e:
                print(f"❌ [ALERT] '{action_name}' లో లోపం: {e}
")
                raise
        return wrapper
    return decorator

# 2. కస్టమ్ ఎక్సెప్షన్స్
class AcademyDomainError(Exception): pass
class SeatFullError(AcademyDomainError): pass
class LowBalanceError(AcademyDomainError): pass
class DuplicateEnrollmentError(AcademyDomainError): pass

# 3. డేటా మోడల్స్
class Student:
    def __init__(self, sid: str, name: str, email: str, wallet: float):
        self.sid = sid
        self.name = name
        self.email = email
        self.wallet = float(wallet)
        self.courses = []

    def __repr__(self):
        return f"Student({self.sid}: {self.name}, వాలెట్: ₹{self.wallet:,.2f})"

class Course:
    def __init__(self, code: str, title: str, fee: float, capacity: int = 2):
        self.code = code
        self.title = title
        self.fee = float(fee)
        self.capacity = capacity
        self.roster = []

    def __repr__(self):
        return f"Course({self.code}: '{self.title}' | ఫీజు: ₹{self.fee:,.2f} | సీట్లు: {len(self.roster)}/{self.capacity})"

# 4. సెంట్రల్ అకాడమీ ఆర్కిటెక్చర్ ఇంజిన్
class CyberAcademyEngine:
    def __init__(self, academy_name: str):
        self.academy_name = academy_name
        self.students = {}
        self.courses = {}

    def register_student(self, student: Student):
        self.students[student.sid] = student
        print(f"👤 విద్యార్థి నమోదు అయ్యారు: {student}")

    def add_course(self, course: Course):
        self.courses[course.code] = course
        print(f"📚 కొత్త కోర్సు చేర్చబడింది: {course}")

    @audit_logged("Course Enrollment")
    def process_enrollment(self, sid: str, code: str):
        if sid not in self.students:
            raise KeyError(f"విద్యార్థి ఐడీ '{sid}' కనుగొనబడలేదు!")
        if code not in self.courses:
            raise KeyError(f"కోర్సు కోడ్ '{code}' కనుగొనబడలేదు!")

        student = self.students[sid]
        course = self.courses[code]

        # సీట్ల తనిఖీ
        if len(course.roster) >= course.capacity:
            raise SeatFullError(f"కోర్సు '{course.title}' లో సీట్లు నిండిపోయాయి! గరిష్ట పరిమితి: {course.capacity}")

        # డూప్లికేట్ తనిఖీ
        if code in student.courses:
            raise DuplicateEnrollmentError(f"{student.name} ఇప్పటికే '{course.title}' లో చేరారు!")

        # వాలెట్ తనిఖీ & ఫీజు కటింగ్
        if student.wallet < course.fee:
            shortfall = course.fee - student.wallet
            raise LowBalanceError(f"ఖాతాలో తగినంత నగదు లేదు! తక్కువ ఉన్న మొత్తం: ₹{shortfall:,.2f}")

        student.wallet -= course.fee
        student.courses.append(code)
        course.roster.append(student.sid)
        print(f"🎉 విజయవంతంగా ఎన్‌రోల్ అయ్యారు! {student.name} -> {course.title} (మిగిలిన వాలెట్: ₹{student.wallet:,.2f})")

    # జెనరేటర్: ఫైనాన్షియల్ రెవెన్యూ స్ట్రీమ్ విశ్లేషణ
    def revenue_stream(self):
        for c in self.courses.values():
            revenue = len(c.roster) * c.fee
            yield (c.code, c.title, len(c.roster), revenue)

    def print_executive_dashboard(self):
        print("=" * 70)
        print(f"🎓 {self.academy_name} — ఎగ్జిక్యూటివ్ అకాడమీ డాష్‌బోర్డ్")
        print("=" * 70)
        total_rev = 0.0
        print(f"{'కోర్సు కోడ్':<12} | {'కోర్సు పేరు':<24} | {'విద్యార్థులు':<12} | {'రాబడి'}")
        print("-" * 70)
        for code, title, count, rev in self.revenue_stream():
            total_rev += rev
            print(f"{code:<12} | {title:<24} | {count:<12} | ₹{rev:,.2f}")
        print("=" * 70)
        print(f"💰 మొత్తం అకాడమీ ఫీజు రాబడి (Total Revenue): ₹{total_rev:,.2f}")
        print("=" * 70 + "
")


# =====================================================================
# గ్రాండ్ ఫినాలే ఎగ్జిక్యూషన్ డ్రైవర్
# =====================================================================
print("🚀 NextGen Cyber Academy Management Engine ప్రారంభమవుతోంది...
")

engine = CyberAcademyEngine("హైదరాబాద్ ఇంటర్నేషనల్ పైథాన్ అకాడమీ")

# కోర్సుల సృష్టి (పరిమితి: 2 సీట్లు)
c1 = Course("PY-101", "Full Stack Modern Python", fee=4500.0, capacity=2)
c2 = Course("AI-201", "FastAPI & Generative AI", fee=8500.0, capacity=2)
engine.add_course(c1)
engine.add_course(c2)

print()
# విద్యార్థుల నమోదు
s1 = Student("STU-01", "రవితేజ", "ravi@telugu.dev", wallet=15000.0)
s2 = Student("STU-02", "అనిత వర్మ", "anitha@tech.in", wallet=5000.0)
s3 = Student("STU-03", "వంశీ కృష్ణ", "vamsi@code.org", wallet=1000.0)
engine.register_student(s1)
engine.register_student(s2)
engine.register_student(s3)

print("
--- ఎన్‌రోల్‌మెంట్ ప్రాసెసింగ్ మొదలైంది ---")

# 1. సక్సెస్ ఎన్‌రోల్‌మెంట్
engine.process_enrollment("STU-01", "PY-101")

# 2. సక్సెస్ ఎన్‌రోల్‌మెంట్ (2వ సీటు ఫిల్ అవుతుంది)
engine.process_enrollment("STU-02", "PY-101")

# 3. సీట్లు నిండినప్పుడు వచ్చే ఎర్రర్ తనిఖీ (SeatFullError)
try:
    engine.process_enrollment("STU-03", "PY-101")
except SeatFullError as sfe:
    print(f"హెచ్చరిక: {sfe}")

# 4. వాలెట్ బ్యాలెన్స్ లేనప్పుడు వచ్చే ఎర్రర్ తనిఖీ (LowBalanceError)
try:
    engine.process_enrollment("STU-03", "AI-201")  # ₹1000 మాత్రమే ఉంది, ఫీజు ₹8500
except LowBalanceError as lbe:
    print(f"హెచ్చరిక: {lbe}")

# డాష్‌బోర్డ్ ప్రదర్శన
engine.print_executive_dashboard()