# app/modules/loyalty/routes/api/admin.py """ Loyalty module admin routes. Platform admin endpoints for: - Viewing all loyalty programs (company-based) - Company loyalty settings management - Platform-wide analytics """ import logging from fastapi import APIRouter, Depends, HTTPException, Path, Query from sqlalchemy.orm import Session from app.api.deps import get_current_admin_api, require_module_access from app.core.database import get_db from app.modules.enums import FrontendType from app.modules.loyalty.schemas import ( ProgramListResponse, ProgramResponse, ProgramStatsResponse, CompanyStatsResponse, CompanySettingsResponse, CompanySettingsUpdate, ) from app.modules.loyalty.services import program_service from app.modules.tenancy.models import User logger = logging.getLogger(__name__) # Admin router with module access control admin_router = APIRouter( prefix="/loyalty", dependencies=[Depends(require_module_access("loyalty", FrontendType.ADMIN))], ) # ============================================================================= # Program Management # ============================================================================= @admin_router.get("/programs", response_model=ProgramListResponse) def list_programs( skip: int = Query(0, ge=0), limit: int = Query(50, ge=1, le=100), is_active: bool | None = Query(None), search: str | None = Query(None, description="Search by company name"), current_user: User = Depends(get_current_admin_api), db: Session = Depends(get_db), ): """List all loyalty programs (platform admin).""" from sqlalchemy import func from app.modules.loyalty.models import LoyaltyCard, LoyaltyTransaction from app.modules.tenancy.models import Company programs, total = program_service.list_programs( db, skip=skip, limit=limit, is_active=is_active, search=search, ) program_responses = [] for program in programs: response = ProgramResponse.model_validate(program) response.is_stamps_enabled = program.is_stamps_enabled response.is_points_enabled = program.is_points_enabled response.display_name = program.display_name # Get company name company = db.query(Company).filter(Company.id == program.company_id).first() if company: response.company_name = company.name # Get basic stats for this program response.total_cards = ( db.query(func.count(LoyaltyCard.id)) .filter(LoyaltyCard.company_id == program.company_id) .scalar() or 0 ) response.active_cards = ( db.query(func.count(LoyaltyCard.id)) .filter( LoyaltyCard.company_id == program.company_id, LoyaltyCard.is_active == True, ) .scalar() or 0 ) response.total_points_issued = ( db.query(func.sum(LoyaltyTransaction.points_delta)) .filter( LoyaltyTransaction.company_id == program.company_id, LoyaltyTransaction.points_delta > 0, ) .scalar() or 0 ) response.total_points_redeemed = ( db.query(func.sum(func.abs(LoyaltyTransaction.points_delta))) .filter( LoyaltyTransaction.company_id == program.company_id, LoyaltyTransaction.points_delta < 0, ) .scalar() or 0 ) program_responses.append(response) return ProgramListResponse(programs=program_responses, total=total) @admin_router.get("/programs/{program_id}", response_model=ProgramResponse) def get_program( program_id: int, current_user: User = Depends(get_current_admin_api), db: Session = Depends(get_db), ): """Get a specific loyalty program.""" program = program_service.require_program(db, program_id) response = ProgramResponse.model_validate(program) response.is_stamps_enabled = program.is_stamps_enabled response.is_points_enabled = program.is_points_enabled response.display_name = program.display_name return response @admin_router.get("/programs/{program_id}/stats", response_model=ProgramStatsResponse) def get_program_stats( program_id: int, current_user: User = Depends(get_current_admin_api), db: Session = Depends(get_db), ): """Get statistics for a loyalty program.""" stats = program_service.get_program_stats(db, program_id) return ProgramStatsResponse(**stats) # ============================================================================= # Company Management # ============================================================================= @admin_router.get("/companies/{company_id}/stats", response_model=CompanyStatsResponse) def get_company_stats( company_id: int = Path(..., gt=0), current_user: User = Depends(get_current_admin_api), db: Session = Depends(get_db), ): """Get company-wide loyalty statistics across all locations.""" stats = program_service.get_company_stats(db, company_id) if "error" in stats: raise HTTPException(status_code=404, detail=stats["error"]) return CompanyStatsResponse(**stats) @admin_router.get("/companies/{company_id}/settings", response_model=CompanySettingsResponse) def get_company_settings( company_id: int = Path(..., gt=0), current_user: User = Depends(get_current_admin_api), db: Session = Depends(get_db), ): """Get company loyalty settings.""" settings = program_service.get_or_create_company_settings(db, company_id) return CompanySettingsResponse.model_validate(settings) @admin_router.patch("/companies/{company_id}/settings", response_model=CompanySettingsResponse) def update_company_settings( data: CompanySettingsUpdate, company_id: int = Path(..., gt=0), current_user: User = Depends(get_current_admin_api), db: Session = Depends(get_db), ): """Update company loyalty settings (admin only).""" from app.modules.loyalty.models import CompanyLoyaltySettings settings = program_service.get_or_create_company_settings(db, company_id) update_data = data.model_dump(exclude_unset=True) for field, value in update_data.items(): setattr(settings, field, value) db.commit() db.refresh(settings) logger.info(f"Updated company {company_id} loyalty settings: {list(update_data.keys())}") return CompanySettingsResponse.model_validate(settings) # ============================================================================= # Platform Stats # ============================================================================= @admin_router.get("/stats") def get_platform_stats( current_user: User = Depends(get_current_admin_api), db: Session = Depends(get_db), ): """Get platform-wide loyalty statistics.""" from sqlalchemy import func from app.modules.loyalty.models import LoyaltyCard, LoyaltyProgram, LoyaltyTransaction # Program counts total_programs = db.query(func.count(LoyaltyProgram.id)).scalar() or 0 active_programs = ( db.query(func.count(LoyaltyProgram.id)) .filter(LoyaltyProgram.is_active == True) .scalar() or 0 ) # Card counts total_cards = db.query(func.count(LoyaltyCard.id)).scalar() or 0 active_cards = ( db.query(func.count(LoyaltyCard.id)) .filter(LoyaltyCard.is_active == True) .scalar() or 0 ) # Transaction counts (last 30 days) from datetime import UTC, datetime, timedelta thirty_days_ago = datetime.now(UTC) - timedelta(days=30) transactions_30d = ( db.query(func.count(LoyaltyTransaction.id)) .filter(LoyaltyTransaction.transaction_at >= thirty_days_ago) .scalar() or 0 ) # Points issued/redeemed (last 30 days) points_issued_30d = ( db.query(func.sum(LoyaltyTransaction.points_delta)) .filter( LoyaltyTransaction.transaction_at >= thirty_days_ago, LoyaltyTransaction.points_delta > 0, ) .scalar() or 0 ) points_redeemed_30d = ( db.query(func.sum(func.abs(LoyaltyTransaction.points_delta))) .filter( LoyaltyTransaction.transaction_at >= thirty_days_ago, LoyaltyTransaction.points_delta < 0, ) .scalar() or 0 ) # Company count with programs companies_with_programs = ( db.query(func.count(func.distinct(LoyaltyProgram.company_id))).scalar() or 0 ) return { "total_programs": total_programs, "active_programs": active_programs, "companies_with_programs": companies_with_programs, "total_cards": total_cards, "active_cards": active_cards, "transactions_30d": transactions_30d, "points_issued_30d": points_issued_30d, "points_redeemed_30d": points_redeemed_30d, }