nanopy-bank 1.0.8__py3-none-any.whl

nanopy_bank/core/branch.py

@@ -0,0 +1,319 @@
+"""
+Branch and Employee models - Bank organization structure
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, date, time
+from decimal import Decimal
+from enum import Enum
+from typing import Optional, List, Dict
+import uuid
+
+
+class BranchType(Enum):
+    """Types of branches"""
+    HEADQUARTERS = "headquarters"   # Siège social
+    REGIONAL = "regional"           # Direction régionale
+    BRANCH = "branch"               # Agence
+    ONLINE = "online"               # Banque en ligne
+    ATM_ONLY = "atm_only"           # Point automatique
+
+
+class EmployeeRole(Enum):
+    """Employee roles"""
+    DIRECTOR = "director"           # Directeur
+    MANAGER = "manager"             # Responsable
+    ADVISOR = "advisor"             # Conseiller
+    TELLER = "teller"               # Guichetier
+    ANALYST = "analyst"             # Analyste
+    SUPPORT = "support"             # Support client
+    IT = "it"                       # Informatique
+    COMPLIANCE = "compliance"       # Conformité
+    RISK = "risk"                   # Risques
+
+
+class EmployeeStatus(Enum):
+    """Employee status"""
+    ACTIVE = "active"
+    ON_LEAVE = "on_leave"
+    SUSPENDED = "suspended"
+    TERMINATED = "terminated"
+
+
+@dataclass
+class Branch:
+    """
+    Bank branch / Agency
+    """
+    branch_id: str = field(default_factory=lambda: f"BR{uuid.uuid4().hex[:6].upper()}")
+    branch_code: str = ""  # Code guichet (5 digits in France)
+
+    # Branch info
+    name: str = ""
+    branch_type: BranchType = BranchType.BRANCH
+
+    # Location
+    address: str = ""
+    city: str = ""
+    postal_code: str = ""
+    country: str = "FR"
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+
+    # Contact
+    phone: str = ""
+    fax: str = ""
+    email: str = ""
+
+    # Opening hours
+    opening_hours: Dict[str, Dict[str, str]] = field(default_factory=lambda: {
+        "monday": {"open": "09:00", "close": "17:00"},
+        "tuesday": {"open": "09:00", "close": "17:00"},
+        "wednesday": {"open": "09:00", "close": "17:00"},
+        "thursday": {"open": "09:00", "close": "17:00"},
+        "friday": {"open": "09:00", "close": "17:00"},
+        "saturday": {"open": "09:00", "close": "12:00"},
+        "sunday": {"open": "", "close": ""},  # Closed
+    })
+
+    # Services
+    services: List[str] = field(default_factory=lambda: [
+        "accounts", "cards", "loans", "insurance", "savings"
+    ])
+    has_atm: bool = True
+    has_safe_deposit: bool = False  # Coffres
+    wheelchair_accessible: bool = True
+
+    # Hierarchy
+    parent_branch_id: Optional[str] = None  # For regional structure
+    manager_employee_id: Optional[str] = None
+
+    # Statistics
+    customer_count: int = 0
+    account_count: int = 0
+    total_deposits: Decimal = Decimal("0.00")
+    total_loans: Decimal = Decimal("0.00")
+
+    # Status
+    is_active: bool = True
+    opened_date: date = field(default_factory=date.today)
+    closed_date: Optional[date] = None
+
+    # Metadata
+    created_at: datetime = field(default_factory=datetime.now)
+
+    def is_open_now(self) -> bool:
+        """Check if branch is currently open"""
+        now = datetime.now()
+        day = now.strftime("%A").lower()
+        hours = self.opening_hours.get(day, {})
+
+        if not hours.get("open") or not hours.get("close"):
+            return False
+
+        open_time = datetime.strptime(hours["open"], "%H:%M").time()
+        close_time = datetime.strptime(hours["close"], "%H:%M").time()
+        current_time = now.time()
+
+        return open_time <= current_time <= close_time
+
+    def to_dict(self) -> dict:
+        return {
+            "branch_id": self.branch_id,
+            "branch_code": self.branch_code,
+            "name": self.name,
+            "branch_type": self.branch_type.value,
+            "address": self.address,
+            "city": self.city,
+            "postal_code": self.postal_code,
+            "country": self.country,
+            "latitude": self.latitude,
+            "longitude": self.longitude,
+            "phone": self.phone,
+            "fax": self.fax,
+            "email": self.email,
+            "opening_hours": self.opening_hours,
+            "services": self.services,
+            "has_atm": self.has_atm,
+            "has_safe_deposit": self.has_safe_deposit,
+            "wheelchair_accessible": self.wheelchair_accessible,
+            "parent_branch_id": self.parent_branch_id,
+            "manager_employee_id": self.manager_employee_id,
+            "customer_count": self.customer_count,
+            "account_count": self.account_count,
+            "total_deposits": str(self.total_deposits),
+            "total_loans": str(self.total_loans),
+            "is_active": self.is_active,
+            "is_open_now": self.is_open_now(),
+            "opened_date": self.opened_date.isoformat(),
+            "closed_date": self.closed_date.isoformat() if self.closed_date else None,
+            "created_at": self.created_at.isoformat(),
+        }
+
+
+@dataclass
+class Employee:
+    """
+    Bank employee
+    """
+    employee_id: str = field(default_factory=lambda: f"EMP{uuid.uuid4().hex[:8].upper()}")
+    employee_number: str = ""  # Matricule
+
+    # Personal info
+    first_name: str = ""
+    last_name: str = ""
+    email: str = ""
+    phone: str = ""
+    mobile: str = ""
+
+    # Role
+    role: EmployeeRole = EmployeeRole.ADVISOR
+    title: str = ""  # Job title
+    department: str = ""
+    branch_id: Optional[str] = None
+    manager_id: Optional[str] = None
+
+    # Permissions
+    permissions: List[str] = field(default_factory=list)
+    max_approval_amount: Decimal = Decimal("0.00")  # Max amount they can approve
+    can_approve_loans: bool = False
+    can_manage_accounts: bool = True
+    can_view_all_customers: bool = False
+
+    # Work info
+    hire_date: date = field(default_factory=date.today)
+    contract_type: str = "permanent"  # permanent, temporary, intern
+    work_schedule: str = "full_time"  # full_time, part_time
+
+    # Status
+    status: EmployeeStatus = EmployeeStatus.ACTIVE
+
+    # Performance
+    customers_managed: int = 0
+    transactions_processed: int = 0
+    loans_approved: int = 0
+    total_loan_amount_approved: Decimal = Decimal("0.00")
+
+    # Metadata
+    created_at: datetime = field(default_factory=datetime.now)
+    last_login: Optional[datetime] = None
+
+    @property
+    def full_name(self) -> str:
+        return f"{self.first_name} {self.last_name}"
+
+    def can_approve(self, amount: Decimal) -> bool:
+        """Check if employee can approve this amount"""
+        return self.can_approve_loans and amount <= self.max_approval_amount
+
+    def to_dict(self) -> dict:
+        return {
+            "employee_id": self.employee_id,
+            "employee_number": self.employee_number,
+            "first_name": self.first_name,
+            "last_name": self.last_name,
+            "full_name": self.full_name,
+            "email": self.email,
+            "phone": self.phone,
+            "mobile": self.mobile,
+            "role": self.role.value,
+            "title": self.title,
+            "department": self.department,
+            "branch_id": self.branch_id,
+            "manager_id": self.manager_id,
+            "permissions": self.permissions,
+            "max_approval_amount": str(self.max_approval_amount),
+            "can_approve_loans": self.can_approve_loans,
+            "can_manage_accounts": self.can_manage_accounts,
+            "can_view_all_customers": self.can_view_all_customers,
+            "hire_date": self.hire_date.isoformat(),
+            "contract_type": self.contract_type,
+            "work_schedule": self.work_schedule,
+            "status": self.status.value,
+            "customers_managed": self.customers_managed,
+            "transactions_processed": self.transactions_processed,
+            "loans_approved": self.loans_approved,
+            "total_loan_amount_approved": str(self.total_loan_amount_approved),
+            "created_at": self.created_at.isoformat(),
+            "last_login": self.last_login.isoformat() if self.last_login else None,
+        }
+
+
+@dataclass
+class ATM:
+    """
+    ATM / Distributeur automatique
+    """
+    atm_id: str = field(default_factory=lambda: f"ATM{uuid.uuid4().hex[:6].upper()}")
+    branch_id: Optional[str] = None
+
+    # Location
+    name: str = ""
+    address: str = ""
+    city: str = ""
+    postal_code: str = ""
+    country: str = "FR"
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+    location_type: str = "indoor"  # indoor, outdoor, mall, station
+
+    # Services
+    can_withdraw: bool = True
+    can_deposit_cash: bool = False
+    can_deposit_check: bool = False
+    can_check_balance: bool = True
+    can_transfer: bool = False
+    can_print_statement: bool = True
+
+    # Limits
+    max_withdrawal: Decimal = Decimal("500.00")
+    max_deposit: Decimal = Decimal("3000.00")
+
+    # Status
+    is_active: bool = True
+    is_online: bool = True
+    last_maintenance: Optional[datetime] = None
+    next_maintenance: Optional[date] = None
+
+    # Cash levels
+    cash_level: int = 100  # Percentage
+    low_cash_threshold: int = 20
+
+    # Statistics
+    transactions_today: int = 0
+    total_withdrawn_today: Decimal = Decimal("0.00")
+
+    # Metadata
+    created_at: datetime = field(default_factory=datetime.now)
+
+    def to_dict(self) -> dict:
+        return {
+            "atm_id": self.atm_id,
+            "branch_id": self.branch_id,
+            "name": self.name,
+            "address": self.address,
+            "city": self.city,
+            "postal_code": self.postal_code,
+            "country": self.country,
+            "latitude": self.latitude,
+            "longitude": self.longitude,
+            "location_type": self.location_type,
+            "can_withdraw": self.can_withdraw,
+            "can_deposit_cash": self.can_deposit_cash,
+            "can_deposit_check": self.can_deposit_check,
+            "can_check_balance": self.can_check_balance,
+            "can_transfer": self.can_transfer,
+            "can_print_statement": self.can_print_statement,
+            "max_withdrawal": str(self.max_withdrawal),
+            "max_deposit": str(self.max_deposit),
+            "is_active": self.is_active,
+            "is_online": self.is_online,
+            "last_maintenance": self.last_maintenance.isoformat() if self.last_maintenance else None,
+            "next_maintenance": self.next_maintenance.isoformat() if self.next_maintenance else None,
+            "cash_level": self.cash_level,
+            "low_cash_threshold": self.low_cash_threshold,
+            "needs_cash": self.cash_level < self.low_cash_threshold,
+            "transactions_today": self.transactions_today,
+            "total_withdrawn_today": str(self.total_withdrawn_today),
+            "created_at": self.created_at.isoformat(),
+        }

nanopy_bank/core/fees.py

@@ -0,0 +1,243 @@
+"""
+Fees and Rates - Interest rates, commissions, banking fees
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, date
+from decimal import Decimal
+from enum import Enum
+from typing import Optional, List
+import uuid
+
+
+class FeeType(Enum):
+    """Types of banking fees"""
+    # Account fees
+    ACCOUNT_MAINTENANCE = "account_maintenance"     # Frais de tenue de compte
+    CARD_ANNUAL = "card_annual"                     # Cotisation carte
+    CARD_REPLACEMENT = "card_replacement"           # Remplacement carte
+
+    # Transaction fees
+    TRANSFER_DOMESTIC = "transfer_domestic"         # Virement national
+    TRANSFER_SEPA = "transfer_sepa"                 # Virement SEPA
+    TRANSFER_INTERNATIONAL = "transfer_international"  # Virement international
+    DIRECT_DEBIT = "direct_debit"                   # Prélèvement
+    CHECK_PROCESSING = "check_processing"           # Traitement chèque
+
+    # Overdraft fees
+    OVERDRAFT_INTEREST = "overdraft_interest"       # Agios
+    OVERDRAFT_FEE = "overdraft_fee"                 # Commission d'intervention
+    REJECTED_PAYMENT = "rejected_payment"           # Rejet de prélèvement
+
+    # Service fees
+    STATEMENT_PAPER = "statement_paper"             # Relevé papier
+    CERTIFICATE = "certificate"                     # Attestation
+    WIRE_TRANSFER = "wire_transfer"                 # Virement urgent
+
+    # ATM fees
+    ATM_WITHDRAWAL_OTHER = "atm_withdrawal_other"   # Retrait autre banque
+    ATM_WITHDRAWAL_FOREIGN = "atm_withdrawal_foreign"  # Retrait étranger
+
+    # FX fees
+    CURRENCY_CONVERSION = "currency_conversion"     # Conversion devise
+
+
+class RateType(Enum):
+    """Types of interest rates"""
+    SAVINGS = "savings"             # Taux épargne
+    LOAN = "loan"                   # Taux crédit
+    OVERDRAFT = "overdraft"         # Taux découvert
+    MORTGAGE = "mortgage"           # Taux immobilier
+    DEPOSIT = "deposit"             # Taux dépôt
+
+
+@dataclass
+class Fee:
+    """
+    Banking fee definition
+    """
+    fee_id: str = field(default_factory=lambda: f"FEE{uuid.uuid4().hex[:8].upper()}")
+
+    # Fee details
+    fee_type: FeeType = FeeType.ACCOUNT_MAINTENANCE
+    name: str = ""
+    description: str = ""
+
+    # Amount
+    amount: Decimal = Decimal("0.00")
+    is_percentage: bool = False  # True = percentage, False = fixed amount
+    min_amount: Optional[Decimal] = None  # Minimum if percentage
+    max_amount: Optional[Decimal] = None  # Maximum if percentage
+
+    # Applicability
+    currency: str = "EUR"
+    account_types: List[str] = field(default_factory=list)  # Empty = all types
+    customer_types: List[str] = field(default_factory=list)  # "individual", "business"
+
+    # Frequency
+    frequency: str = "per_transaction"  # per_transaction, monthly, yearly
+
+    # Tax
+    vat_rate: Decimal = Decimal("20.00")  # TVA
+    vat_included: bool = True
+
+    # Status
+    is_active: bool = True
+    effective_from: date = field(default_factory=date.today)
+    effective_until: Optional[date] = None
+
+    # Metadata
+    created_at: datetime = field(default_factory=datetime.now)
+
+    def calculate(self, base_amount: Decimal = Decimal("0.00")) -> Decimal:
+        """Calculate fee amount"""
+        if self.is_percentage:
+            fee = base_amount * self.amount / 100
+            if self.min_amount and fee < self.min_amount:
+                fee = self.min_amount
+            if self.max_amount and fee > self.max_amount:
+                fee = self.max_amount
+            return fee
+        return self.amount
+
+    def to_dict(self) -> dict:
+        return {
+            "fee_id": self.fee_id,
+            "fee_type": self.fee_type.value,
+            "name": self.name,
+            "description": self.description,
+            "amount": str(self.amount),
+            "is_percentage": self.is_percentage,
+            "min_amount": str(self.min_amount) if self.min_amount else None,
+            "max_amount": str(self.max_amount) if self.max_amount else None,
+            "currency": self.currency,
+            "account_types": self.account_types,
+            "customer_types": self.customer_types,
+            "frequency": self.frequency,
+            "vat_rate": str(self.vat_rate),
+            "vat_included": self.vat_included,
+            "is_active": self.is_active,
+            "effective_from": self.effective_from.isoformat(),
+            "effective_until": self.effective_until.isoformat() if self.effective_until else None,
+            "created_at": self.created_at.isoformat(),
+        }
+
+
+@dataclass
+class InterestRate:
+    """
+    Interest rate definition
+    """
+    rate_id: str = field(default_factory=lambda: f"RATE{uuid.uuid4().hex[:8].upper()}")
+
+    # Rate details
+    rate_type: RateType = RateType.SAVINGS
+    name: str = ""
+    description: str = ""
+
+    # Rate value
+    rate: Decimal = Decimal("0.00")  # Annual rate (e.g., 3.00 = 3%)
+    is_variable: bool = False
+    base_rate: str = ""  # Reference rate (EURIBOR, etc.)
+    margin: Decimal = Decimal("0.00")  # Margin over base rate
+
+    # Tiered rates (optional)
+    tiers: List[dict] = field(default_factory=list)  # [{"min": 0, "max": 10000, "rate": 2.0}, ...]
+
+    # Applicability
+    product_types: List[str] = field(default_factory=list)
+    min_amount: Optional[Decimal] = None
+    max_amount: Optional[Decimal] = None
+    min_duration_months: Optional[int] = None
+    max_duration_months: Optional[int] = None
+
+    # Status
+    is_active: bool = True
+    effective_from: date = field(default_factory=date.today)
+    effective_until: Optional[date] = None
+
+    # Metadata
+    created_at: datetime = field(default_factory=datetime.now)
+
+    def get_rate_for_amount(self, amount: Decimal) -> Decimal:
+        """Get applicable rate for an amount (considering tiers)"""
+        if not self.tiers:
+            return self.rate
+
+        for tier in sorted(self.tiers, key=lambda t: t.get("min", 0)):
+            tier_min = Decimal(str(tier.get("min", 0)))
+            tier_max = Decimal(str(tier.get("max", float("inf"))))
+            if tier_min <= amount < tier_max:
+                return Decimal(str(tier.get("rate", self.rate)))
+
+        return self.rate
+
+    def to_dict(self) -> dict:
+        return {
+            "rate_id": self.rate_id,
+            "rate_type": self.rate_type.value,
+            "name": self.name,
+            "description": self.description,
+            "rate": str(self.rate),
+            "is_variable": self.is_variable,
+            "base_rate": self.base_rate,
+            "margin": str(self.margin),
+            "tiers": self.tiers,
+            "product_types": self.product_types,
+            "min_amount": str(self.min_amount) if self.min_amount else None,
+            "max_amount": str(self.max_amount) if self.max_amount else None,
+            "min_duration_months": self.min_duration_months,
+            "max_duration_months": self.max_duration_months,
+            "is_active": self.is_active,
+            "effective_from": self.effective_from.isoformat(),
+            "effective_until": self.effective_until.isoformat() if self.effective_until else None,
+            "created_at": self.created_at.isoformat(),
+        }
+
+
+@dataclass
+class AppliedFee:
+    """
+    A fee that was applied to an account/transaction
+    """
+    applied_fee_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    fee_id: str = ""
+    account_iban: str = ""
+    transaction_id: Optional[str] = None
+
+    # Amount
+    amount: Decimal = Decimal("0.00")
+    vat_amount: Decimal = Decimal("0.00")
+    total_amount: Decimal = Decimal("0.00")
+
+    # Details
+    description: str = ""
+    period: str = ""  # "2024-01" for monthly fees
+
+    # Status
+    status: str = "pending"  # pending, applied, reversed
+    applied_at: Optional[datetime] = None
+    reversed_at: Optional[datetime] = None
+
+    # Metadata
+    created_at: datetime = field(default_factory=datetime.now)
+
+    def to_dict(self) -> dict:
+        return {
+            "applied_fee_id": self.applied_fee_id,
+            "fee_id": self.fee_id,
+            "account_iban": self.account_iban,
+            "transaction_id": self.transaction_id,
+            "amount": str(self.amount),
+            "vat_amount": str(self.vat_amount),
+            "total_amount": str(self.total_amount),
+            "description": self.description,
+            "period": self.period,
+            "status": self.status,
+            "applied_at": self.applied_at.isoformat() if self.applied_at else None,
+            "reversed_at": self.reversed_at.isoformat() if self.reversed_at else None,
+            "created_at": self.created_at.isoformat(),
+        }
+
+
+# Note: Demo fees and rates are in nanopy_bank/data/demo.py