orion/app/modules/loyalty/routes/pages/admin.py

# app/modules/loyalty/routes/pages/admin.py
"""
Loyalty Admin Page Routes (HTML rendering).

Admin pages for:
- Platform loyalty programs dashboard
- Merchant loyalty program detail/configuration
- Platform-wide loyalty statistics
"""

from fastapi import APIRouter, Depends, Path, Request
from fastapi.responses import HTMLResponse
from sqlalchemy.orm import Session

from app.api.deps import get_db, require_menu_access
from app.modules.core.utils.page_context import get_admin_context
from app.modules.enums import FrontendType
from app.modules.tenancy.models import Merchant, User
from app.templates_config import templates


def _get_merchant_name(db: Session, merchant_id: int) -> str:
    """Look up merchant name for page header context."""
    merchant = db.query(Merchant).filter(Merchant.id == merchant_id).first()
    return merchant.name if merchant else ""

router = APIRouter()

# Route configuration for module route discovery
ROUTE_CONFIG = {
    "prefix": "/loyalty",
    "tags": ["admin-loyalty"],
}


# ============================================================================
# LOYALTY PROGRAMS DASHBOARD
# ============================================================================


@router.get("/programs", response_class=HTMLResponse, include_in_schema=False)
async def admin_loyalty_programs(
    request: Request,
    current_user: User = Depends(require_menu_access("loyalty-programs", FrontendType.ADMIN)),
    db: Session = Depends(get_db),
):
    """
    Render loyalty programs dashboard.
    Shows all merchants with loyalty programs and platform-wide statistics.
    """
    return templates.TemplateResponse(
        "loyalty/admin/programs.html",
        get_admin_context(request, db, current_user),
    )


@router.get("/analytics", response_class=HTMLResponse, include_in_schema=False)
async def admin_loyalty_analytics(
    request: Request,
    current_user: User = Depends(require_menu_access("loyalty-analytics", FrontendType.ADMIN)),
    db: Session = Depends(get_db),
):
    """
    Render loyalty analytics dashboard.
    Shows platform-wide loyalty statistics and trends.
    """
    return templates.TemplateResponse(
        "loyalty/admin/analytics.html",
        get_admin_context(request, db, current_user),
    )


# ============================================================================
# MERCHANT LOYALTY DETAIL
# ============================================================================


@router.get("/wallet-debug", response_class=HTMLResponse, include_in_schema=False)
async def admin_wallet_debug(
    request: Request,
    current_user: User = Depends(require_menu_access("wallet-debug", FrontendType.ADMIN)),
    db: Session = Depends(get_db),
):
    """Render wallet diagnostics debug page (super admin only)."""
    return templates.TemplateResponse(
        "loyalty/admin/wallet-debug.html",
        get_admin_context(request, db, current_user),
    )


@router.get(
    "/merchants/{merchant_id}",
    response_class=HTMLResponse,
    include_in_schema=False,
)
async def admin_loyalty_merchant_detail(
    request: Request,
    merchant_id: int = Path(..., description="Merchant ID"),
    current_user: User = Depends(require_menu_access("loyalty-programs", FrontendType.ADMIN)),
    db: Session = Depends(get_db),
):
    """
    Render merchant loyalty program detail page.
    Shows merchant's loyalty program configuration and location breakdown.
    """
    return templates.TemplateResponse(
        "loyalty/admin/merchant-detail.html",
        get_admin_context(request, db, current_user, merchant_id=merchant_id),
    )


@router.get(
    "/merchants/{merchant_id}/program",
    response_class=HTMLResponse,
    include_in_schema=False,
)
async def admin_loyalty_program_edit(
    request: Request,
    merchant_id: int = Path(..., description="Merchant ID"),
    current_user: User = Depends(require_menu_access("loyalty-programs", FrontendType.ADMIN)),
    db: Session = Depends(get_db),
):
    """
    Render program configuration edit page for a merchant.
    Allows admin to create or edit the merchant's loyalty program settings.
    """
    return templates.TemplateResponse(
        "loyalty/admin/program-edit.html",
        get_admin_context(request, db, current_user, merchant_id=merchant_id),
    )


@router.get(
    "/merchants/{merchant_id}/cards",
    response_class=HTMLResponse,
    include_in_schema=False,
)
async def admin_loyalty_merchant_cards(
    request: Request,
    merchant_id: int = Path(..., description="Merchant ID"),
    current_user: User = Depends(require_menu_access("loyalty-programs", FrontendType.ADMIN)),
    db: Session = Depends(get_db),
):
    """
    Render merchant loyalty cards list page.
    Shows all loyalty cards for a specific merchant.
    """
    merchant_name = _get_merchant_name(db, merchant_id)
    return templates.TemplateResponse(
        "loyalty/admin/merchant-cards.html",
        get_admin_context(request, db, current_user, merchant_id=merchant_id, merchant_name=merchant_name),
    )


@router.get(
    "/merchants/{merchant_id}/cards/{card_id}",
    response_class=HTMLResponse,
    include_in_schema=False,
)
async def admin_loyalty_merchant_card_detail(
    request: Request,
    merchant_id: int = Path(..., description="Merchant ID"),
    card_id: int = Path(..., description="Card ID"),
    current_user: User = Depends(require_menu_access("loyalty-programs", FrontendType.ADMIN)),
    db: Session = Depends(get_db),
):
    """
    Render merchant loyalty card detail page.
    Shows detailed info for a specific loyalty card.
    """
    merchant_name = _get_merchant_name(db, merchant_id)
    return templates.TemplateResponse(
        "loyalty/admin/merchant-card-detail.html",
        get_admin_context(request, db, current_user, merchant_id=merchant_id, card_id=card_id, merchant_name=merchant_name),
    )


@router.get(
    "/merchants/{merchant_id}/transactions",
    response_class=HTMLResponse,
    include_in_schema=False,
)
async def admin_loyalty_merchant_transactions(
    request: Request,
    merchant_id: int = Path(..., description="Merchant ID"),
    current_user: User = Depends(require_menu_access("loyalty-programs", FrontendType.ADMIN)),
    db: Session = Depends(get_db),
):
    """
    Render merchant loyalty transactions list page.
    Shows all loyalty transactions for a specific merchant.
    """
    merchant_name = _get_merchant_name(db, merchant_id)
    return templates.TemplateResponse(
        "loyalty/admin/merchant-transactions.html",
        get_admin_context(request, db, current_user, merchant_id=merchant_id, merchant_name=merchant_name),
    )


@router.get(
    "/merchants/{merchant_id}/pins",
    response_class=HTMLResponse,
    include_in_schema=False,
)
async def admin_loyalty_merchant_pins(
    request: Request,
    merchant_id: int = Path(..., description="Merchant ID"),
    current_user: User = Depends(require_menu_access("loyalty-programs", FrontendType.ADMIN)),
    db: Session = Depends(get_db),
):
    """
    Render merchant staff PINs page (read-only).
    Shows all staff PINs for a specific merchant.
    """
    merchant_name = _get_merchant_name(db, merchant_id)
    return templates.TemplateResponse(
        "loyalty/admin/merchant-pins.html",
        get_admin_context(request, db, current_user, merchant_id=merchant_id, merchant_name=merchant_name),
    )


@router.get(
    "/merchants/{merchant_id}/settings",
    response_class=HTMLResponse,
    include_in_schema=False,
)
async def admin_loyalty_merchant_settings(
    request: Request,
    merchant_id: int = Path(..., description="Merchant ID"),
    current_user: User = Depends(require_menu_access("loyalty-programs", FrontendType.ADMIN)),
    db: Session = Depends(get_db),
):
    """
    Render merchant loyalty settings page.
    Admin-controlled settings like staff PIN policy.
    """
    return templates.TemplateResponse(
        "loyalty/admin/merchant-settings.html",
        get_admin_context(request, db, current_user, merchant_id=merchant_id),
    )


@router.get(
    "/merchants/{merchant_id}/devices",
    response_class=HTMLResponse,
    include_in_schema=False,
)
async def admin_loyalty_merchant_devices(
    request: Request,
    merchant_id: int = Path(..., description="Merchant ID"),
    current_user: User = Depends(require_menu_access("loyalty-programs", FrontendType.ADMIN)),
    db: Session = Depends(get_db),
):
    """List + pair POS terminal devices on behalf of a merchant."""
    merchant_name = _get_merchant_name(db, merchant_id)
    return templates.TemplateResponse(
        "loyalty/admin/merchant-devices.html",
        get_admin_context(
            request,
            db,
            current_user,
            merchant_id=merchant_id,
            merchant_name=merchant_name,
        ),
    )