feat(loyalty): implement complete loyalty module MVP
Add stamp-based and points-based loyalty programs for vendors with: Database Models (5 tables): - loyalty_programs: Vendor program configuration - loyalty_cards: Customer cards with stamp/point balances - loyalty_transactions: Immutable audit log - staff_pins: Fraud prevention PINs (bcrypt hashed) - apple_device_registrations: Apple Wallet push tokens Services: - program_service: Program CRUD and statistics - card_service: Customer enrollment and card lookup - stamp_service: Stamp operations with anti-fraud checks - points_service: Points earning and redemption - pin_service: Staff PIN management with lockout - wallet_service: Unified wallet abstraction - google_wallet_service: Google Wallet API integration - apple_wallet_service: Apple Wallet .pkpass generation API Routes: - Admin: /api/v1/admin/loyalty/* (programs list, stats) - Vendor: /api/v1/vendor/loyalty/* (stamp, points, cards, PINs) - Public: /api/v1/loyalty/* (enrollment, Apple Web Service) Anti-Fraud Features: - Staff PIN verification (configurable per program) - Cooldown period between stamps (default 15 min) - Daily stamp limits (default 5/day) - PIN lockout after failed attempts Wallet Integration: - Google Wallet: LoyaltyClass and LoyaltyObject management - Apple Wallet: .pkpass generation with PKCS#7 signing - Apple Web Service endpoints for device registration/updates Also includes: - Alembic migration for all tables with indexes - Localization files (en, fr, de, lu) - Module documentation - Phase 2 interface and user journey plan Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
288
app/modules/loyalty/exceptions.py
Normal file
288
app/modules/loyalty/exceptions.py
Normal file
@@ -0,0 +1,288 @@
|
||||
# app/modules/loyalty/exceptions.py
|
||||
"""
|
||||
Loyalty module exceptions.
|
||||
|
||||
Custom exceptions for loyalty program operations including
|
||||
stamp/points management, card operations, and wallet integration.
|
||||
"""
|
||||
|
||||
from typing import Any
|
||||
|
||||
from app.exceptions.base import (
|
||||
BusinessLogicException,
|
||||
ConflictException,
|
||||
ResourceNotFoundException,
|
||||
ValidationException,
|
||||
)
|
||||
|
||||
|
||||
class LoyaltyException(BusinessLogicException):
|
||||
"""Base exception for loyalty module errors."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
message: str,
|
||||
error_code: str = "LOYALTY_ERROR",
|
||||
details: dict[str, Any] | None = None,
|
||||
):
|
||||
super().__init__(message=message, error_code=error_code, details=details)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Program Exceptions
|
||||
# =============================================================================
|
||||
|
||||
|
||||
class LoyaltyProgramNotFoundException(ResourceNotFoundException):
|
||||
"""Raised when a loyalty program is not found."""
|
||||
|
||||
def __init__(self, identifier: str):
|
||||
super().__init__("LoyaltyProgram", identifier)
|
||||
|
||||
|
||||
class LoyaltyProgramAlreadyExistsException(ConflictException):
|
||||
"""Raised when vendor already has a loyalty program."""
|
||||
|
||||
def __init__(self, vendor_id: int):
|
||||
super().__init__(
|
||||
message=f"Vendor {vendor_id} already has a loyalty program",
|
||||
error_code="LOYALTY_PROGRAM_ALREADY_EXISTS",
|
||||
details={"vendor_id": vendor_id},
|
||||
)
|
||||
|
||||
|
||||
class LoyaltyProgramInactiveException(LoyaltyException):
|
||||
"""Raised when trying to use an inactive loyalty program."""
|
||||
|
||||
def __init__(self, program_id: int):
|
||||
super().__init__(
|
||||
message="Loyalty program is not active",
|
||||
error_code="LOYALTY_PROGRAM_INACTIVE",
|
||||
details={"program_id": program_id},
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Card Exceptions
|
||||
# =============================================================================
|
||||
|
||||
|
||||
class LoyaltyCardNotFoundException(ResourceNotFoundException):
|
||||
"""Raised when a loyalty card is not found."""
|
||||
|
||||
def __init__(self, identifier: str):
|
||||
super().__init__("LoyaltyCard", identifier)
|
||||
|
||||
|
||||
class LoyaltyCardAlreadyExistsException(ConflictException):
|
||||
"""Raised when customer already has a card for this program."""
|
||||
|
||||
def __init__(self, customer_id: int, program_id: int):
|
||||
super().__init__(
|
||||
message="Customer already enrolled in this loyalty program",
|
||||
error_code="LOYALTY_CARD_ALREADY_EXISTS",
|
||||
details={"customer_id": customer_id, "program_id": program_id},
|
||||
)
|
||||
|
||||
|
||||
class LoyaltyCardInactiveException(LoyaltyException):
|
||||
"""Raised when trying to use an inactive loyalty card."""
|
||||
|
||||
def __init__(self, card_id: int):
|
||||
super().__init__(
|
||||
message="Loyalty card is not active",
|
||||
error_code="LOYALTY_CARD_INACTIVE",
|
||||
details={"card_id": card_id},
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Anti-Fraud Exceptions
|
||||
# =============================================================================
|
||||
|
||||
|
||||
class StaffPinNotFoundException(ResourceNotFoundException):
|
||||
"""Raised when a staff PIN is not found."""
|
||||
|
||||
def __init__(self, identifier: str):
|
||||
super().__init__("StaffPin", identifier)
|
||||
|
||||
|
||||
class StaffPinRequiredException(LoyaltyException):
|
||||
"""Raised when staff PIN is required but not provided."""
|
||||
|
||||
def __init__(self):
|
||||
super().__init__(
|
||||
message="Staff PIN is required for this operation",
|
||||
error_code="STAFF_PIN_REQUIRED",
|
||||
)
|
||||
|
||||
|
||||
class InvalidStaffPinException(LoyaltyException):
|
||||
"""Raised when staff PIN is invalid."""
|
||||
|
||||
def __init__(self, remaining_attempts: int | None = None):
|
||||
details = {}
|
||||
if remaining_attempts is not None:
|
||||
details["remaining_attempts"] = remaining_attempts
|
||||
super().__init__(
|
||||
message="Invalid staff PIN",
|
||||
error_code="INVALID_STAFF_PIN",
|
||||
details=details if details else None,
|
||||
)
|
||||
|
||||
|
||||
class StaffPinLockedException(LoyaltyException):
|
||||
"""Raised when staff PIN is locked due to too many failed attempts."""
|
||||
|
||||
def __init__(self, locked_until: str):
|
||||
super().__init__(
|
||||
message="Staff PIN is locked due to too many failed attempts",
|
||||
error_code="STAFF_PIN_LOCKED",
|
||||
details={"locked_until": locked_until},
|
||||
)
|
||||
|
||||
|
||||
class StampCooldownException(LoyaltyException):
|
||||
"""Raised when trying to stamp before cooldown period ends."""
|
||||
|
||||
def __init__(self, cooldown_ends: str, cooldown_minutes: int):
|
||||
super().__init__(
|
||||
message=f"Please wait {cooldown_minutes} minutes between stamps",
|
||||
error_code="STAMP_COOLDOWN",
|
||||
details={"cooldown_ends": cooldown_ends, "cooldown_minutes": cooldown_minutes},
|
||||
)
|
||||
|
||||
|
||||
class DailyStampLimitException(LoyaltyException):
|
||||
"""Raised when daily stamp limit is exceeded."""
|
||||
|
||||
def __init__(self, max_daily_stamps: int, stamps_today: int):
|
||||
super().__init__(
|
||||
message=f"Daily stamp limit of {max_daily_stamps} reached",
|
||||
error_code="DAILY_STAMP_LIMIT",
|
||||
details={"max_daily_stamps": max_daily_stamps, "stamps_today": stamps_today},
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Redemption Exceptions
|
||||
# =============================================================================
|
||||
|
||||
|
||||
class InsufficientStampsException(LoyaltyException):
|
||||
"""Raised when card doesn't have enough stamps to redeem."""
|
||||
|
||||
def __init__(self, current_stamps: int, required_stamps: int):
|
||||
super().__init__(
|
||||
message=f"Insufficient stamps: {current_stamps}/{required_stamps}",
|
||||
error_code="INSUFFICIENT_STAMPS",
|
||||
details={"current_stamps": current_stamps, "required_stamps": required_stamps},
|
||||
)
|
||||
|
||||
|
||||
class InsufficientPointsException(LoyaltyException):
|
||||
"""Raised when card doesn't have enough points to redeem."""
|
||||
|
||||
def __init__(self, current_points: int, required_points: int):
|
||||
super().__init__(
|
||||
message=f"Insufficient points: {current_points}/{required_points}",
|
||||
error_code="INSUFFICIENT_POINTS",
|
||||
details={"current_points": current_points, "required_points": required_points},
|
||||
)
|
||||
|
||||
|
||||
class InvalidRewardException(LoyaltyException):
|
||||
"""Raised when trying to redeem an invalid or unavailable reward."""
|
||||
|
||||
def __init__(self, reward_id: str):
|
||||
super().__init__(
|
||||
message="Invalid or unavailable reward",
|
||||
error_code="INVALID_REWARD",
|
||||
details={"reward_id": reward_id},
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Wallet Exceptions
|
||||
# =============================================================================
|
||||
|
||||
|
||||
class WalletIntegrationException(LoyaltyException):
|
||||
"""Raised when wallet integration fails."""
|
||||
|
||||
def __init__(self, provider: str, message: str):
|
||||
super().__init__(
|
||||
message=f"Wallet integration error: {message}",
|
||||
error_code="WALLET_INTEGRATION_ERROR",
|
||||
details={"provider": provider},
|
||||
)
|
||||
|
||||
|
||||
class GoogleWalletNotConfiguredException(LoyaltyException):
|
||||
"""Raised when Google Wallet is not configured."""
|
||||
|
||||
def __init__(self):
|
||||
super().__init__(
|
||||
message="Google Wallet is not configured for this program",
|
||||
error_code="GOOGLE_WALLET_NOT_CONFIGURED",
|
||||
)
|
||||
|
||||
|
||||
class AppleWalletNotConfiguredException(LoyaltyException):
|
||||
"""Raised when Apple Wallet is not configured."""
|
||||
|
||||
def __init__(self):
|
||||
super().__init__(
|
||||
message="Apple Wallet is not configured for this program",
|
||||
error_code="APPLE_WALLET_NOT_CONFIGURED",
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Validation Exceptions
|
||||
# =============================================================================
|
||||
|
||||
|
||||
class LoyaltyValidationException(ValidationException):
|
||||
"""Raised when loyalty data validation fails."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
message: str = "Loyalty validation failed",
|
||||
field: str | None = None,
|
||||
details: dict[str, Any] | None = None,
|
||||
):
|
||||
super().__init__(message=message, field=field, details=details)
|
||||
self.error_code = "LOYALTY_VALIDATION_FAILED"
|
||||
|
||||
|
||||
__all__ = [
|
||||
# Base
|
||||
"LoyaltyException",
|
||||
# Program
|
||||
"LoyaltyProgramNotFoundException",
|
||||
"LoyaltyProgramAlreadyExistsException",
|
||||
"LoyaltyProgramInactiveException",
|
||||
# Card
|
||||
"LoyaltyCardNotFoundException",
|
||||
"LoyaltyCardAlreadyExistsException",
|
||||
"LoyaltyCardInactiveException",
|
||||
# Anti-Fraud
|
||||
"StaffPinNotFoundException",
|
||||
"StaffPinRequiredException",
|
||||
"InvalidStaffPinException",
|
||||
"StaffPinLockedException",
|
||||
"StampCooldownException",
|
||||
"DailyStampLimitException",
|
||||
# Redemption
|
||||
"InsufficientStampsException",
|
||||
"InsufficientPointsException",
|
||||
"InvalidRewardException",
|
||||
# Wallet
|
||||
"WalletIntegrationException",
|
||||
"GoogleWalletNotConfiguredException",
|
||||
"AppleWalletNotConfiguredException",
|
||||
# Validation
|
||||
"LoyaltyValidationException",
|
||||
]
|
||||
Reference in New Issue
Block a user