""" @router CreditRouter (Backend/app/api/v1/routers/CreditRouter.py) @purpose API endpoints for Store Credit & Cashback system: settings configuration, wallet lookup, customer wallet views, and manual adjustments. """ from fastapi import APIRouter, Depends, HTTPException, status from sqlalchemy.orm import Session from pydantic import BaseModel, Field from typing import Optional, Dict, Any, List from decimal import Decimal from app.core.database.db_session import get_db from app.core.permissions.RoleChecker import RoleChecker, get_current_user from app.models.UserModel import User from app.models.EcomCustomerModel import EcomCustomer from app.services.CreditService import CreditService from app.api.v1.routers.CustomerProfileRouter import get_current_customer router = APIRouter(prefix="/api/v1/credits", tags=["Store Credits & Cashback Engine"]) # --- Schemas --- class CreditSettingsResponse(BaseModel): credits_enabled: bool credits_sales_percentage: float credits_sales_return_window_days: int credits_service_percentage: float credits_service_claim_window_days: int credits_minimum_order_value: float credits_expiry_days: int class CreditSettingsUpdate(BaseModel): credits_enabled: Optional[bool] = None credits_sales_percentage: Optional[float] = Field(None, ge=0.0, le=100.0) credits_sales_return_window_days: Optional[int] = Field(None, ge=0, le=365) credits_service_percentage: Optional[float] = Field(None, ge=0.0, le=100.0) credits_service_claim_window_days: Optional[int] = Field(None, ge=0, le=365) credits_minimum_order_value: Optional[float] = Field(None, ge=0.0) credits_expiry_days: Optional[int] = Field(None, ge=0) class CreditAdjustmentRequest(BaseModel): amount: float = Field(..., gt=0.0, description="Amount to credit or debit") adjustment_type: str = Field(..., pattern="^(CREDIT|DEBIT)$") reason: str = Field(..., min_length=3, max_length=255) # --- Endpoints --- @router.get("/settings", response_model=CreditSettingsResponse) def get_credit_settings(db: Session = Depends(get_db)): """ Public / Admin endpoint to fetch active credit & return window configuration. """ settings = CreditService.get_credit_settings(db) return settings @router.put("/settings", response_model=CreditSettingsResponse) def update_credit_settings( payload: CreditSettingsUpdate, current_user: User = Depends(RoleChecker(["Super Admin", "Admin", "Manager"])), db: Session = Depends(get_db) ): """ Admin endpoint to update cashback percentages and return window durations dynamically. """ updates = {} if payload.credits_enabled is not None: updates["credits_enabled"] = payload.credits_enabled if payload.credits_sales_percentage is not None: updates["credits_sales_percentage"] = payload.credits_sales_percentage if payload.credits_sales_return_window_days is not None: updates["credits_sales_return_window_days"] = payload.credits_sales_return_window_days if payload.credits_service_percentage is not None: updates["credits_service_percentage"] = payload.credits_service_percentage if payload.credits_service_claim_window_days is not None: updates["credits_service_claim_window_days"] = payload.credits_service_claim_window_days if payload.credits_minimum_order_value is not None: updates["credits_minimum_order_value"] = payload.credits_minimum_order_value if payload.credits_expiry_days is not None: updates["credits_expiry_days"] = payload.credits_expiry_days updated = CreditService.update_credit_settings(db, updates) return updated @router.get("/wallets/{customer_id}") def get_customer_wallet_admin( customer_id: str, current_user: User = Depends(RoleChecker(["Super Admin", "Admin", "Manager"])), db: Session = Depends(get_db) ): """ Admin endpoint to inspect customer wallet balances, pending unlocks, and ledger history. """ return CreditService.get_wallet_summary(db, customer_id) @router.post("/wallets/{customer_id}/adjust") def adjust_customer_wallet_admin( customer_id: str, payload: CreditAdjustmentRequest, current_user: User = Depends(RoleChecker(["Super Admin", "Admin", "Manager"])), db: Session = Depends(get_db) ): """ Admin endpoint to manually credit or debit funds with an immutable audit entry. """ tx = CreditService.adjust_wallet_balance_manual( db=db, customer_id=customer_id, amount=Decimal(str(payload.amount)), adjustment_type=payload.adjustment_type, reason=payload.reason, admin_user=current_user.email ) return { "message": f"Successfully performed {payload.adjustment_type} of ₹{payload.amount}", "transaction_id": tx.transaction_id, "new_wallet": CreditService.get_wallet_summary(db, customer_id) } @router.get("/my-wallet") def get_my_wallet( customer: EcomCustomer = Depends(get_current_customer), db: Session = Depends(get_db) ): """ Storefront customer endpoint to view available spendable credits, pending credits, and history. """ return CreditService.get_wallet_summary(db, customer.customer_id)