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:
11
app/modules/loyalty/routes/api/__init__.py
Normal file
11
app/modules/loyalty/routes/api/__init__.py
Normal file
@@ -0,0 +1,11 @@
|
||||
# app/modules/loyalty/routes/api/__init__.py
|
||||
"""
|
||||
Loyalty module API routes.
|
||||
|
||||
Provides REST API endpoints for:
|
||||
- Admin: Platform-wide loyalty program management
|
||||
- Vendor: Store loyalty operations (stamps, points, cards)
|
||||
- Public: Customer enrollment and wallet passes
|
||||
"""
|
||||
|
||||
__all__: list[str] = []
|
||||
144
app/modules/loyalty/routes/api/admin.py
Normal file
144
app/modules/loyalty/routes/api/admin.py
Normal file
@@ -0,0 +1,144 @@
|
||||
# app/modules/loyalty/routes/api/admin.py
|
||||
"""
|
||||
Loyalty module admin routes.
|
||||
|
||||
Platform admin endpoints for:
|
||||
- Viewing all loyalty programs
|
||||
- Platform-wide analytics
|
||||
"""
|
||||
|
||||
import logging
|
||||
|
||||
from fastapi import APIRouter, Depends, 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.loyalty.schemas import (
|
||||
ProgramListResponse,
|
||||
ProgramResponse,
|
||||
ProgramStatsResponse,
|
||||
)
|
||||
from app.modules.loyalty.services import program_service
|
||||
from models.database.user import User
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Admin router with module access control
|
||||
admin_router = APIRouter(
|
||||
prefix="/loyalty",
|
||||
dependencies=[Depends(require_module_access("loyalty"))],
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# 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),
|
||||
current_user: User = Depends(get_current_admin_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""List all loyalty programs (platform admin)."""
|
||||
programs, total = program_service.list_programs(
|
||||
db,
|
||||
skip=skip,
|
||||
limit=limit,
|
||||
is_active=is_active,
|
||||
)
|
||||
|
||||
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
|
||||
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)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# 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
|
||||
)
|
||||
|
||||
return {
|
||||
"total_programs": total_programs,
|
||||
"active_programs": active_programs,
|
||||
"total_cards": total_cards,
|
||||
"active_cards": active_cards,
|
||||
"transactions_30d": transactions_30d,
|
||||
}
|
||||
313
app/modules/loyalty/routes/api/public.py
Normal file
313
app/modules/loyalty/routes/api/public.py
Normal file
@@ -0,0 +1,313 @@
|
||||
# app/modules/loyalty/routes/api/public.py
|
||||
"""
|
||||
Loyalty module public routes.
|
||||
|
||||
Public endpoints for:
|
||||
- Customer enrollment (by vendor code)
|
||||
- Apple Wallet pass download
|
||||
- Apple Web Service endpoints for device registration/updates
|
||||
"""
|
||||
|
||||
import logging
|
||||
from datetime import UTC, datetime
|
||||
|
||||
from fastapi import APIRouter, Depends, Header, HTTPException, Path, Response
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.core.database import get_db
|
||||
from app.modules.loyalty.exceptions import (
|
||||
LoyaltyCardNotFoundException,
|
||||
LoyaltyException,
|
||||
LoyaltyProgramNotFoundException,
|
||||
)
|
||||
from app.modules.loyalty.models import LoyaltyCard, LoyaltyProgram
|
||||
from app.modules.loyalty.services import (
|
||||
apple_wallet_service,
|
||||
card_service,
|
||||
program_service,
|
||||
)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Public router (no auth required for some endpoints)
|
||||
public_router = APIRouter(prefix="/loyalty")
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Enrollment
|
||||
# =============================================================================
|
||||
|
||||
|
||||
@public_router.get("/programs/{vendor_code}")
|
||||
def get_program_by_vendor_code(
|
||||
vendor_code: str = Path(..., min_length=1, max_length=50),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Get loyalty program info by vendor code (for enrollment page)."""
|
||||
from models.database.vendor import Vendor
|
||||
|
||||
# Find vendor by code (vendor_code or subdomain)
|
||||
vendor = (
|
||||
db.query(Vendor)
|
||||
.filter(
|
||||
(Vendor.vendor_code == vendor_code) | (Vendor.subdomain == vendor_code)
|
||||
)
|
||||
.first()
|
||||
)
|
||||
if not vendor:
|
||||
raise HTTPException(status_code=404, detail="Vendor not found")
|
||||
|
||||
# Get program
|
||||
program = program_service.get_active_program_by_vendor(db, vendor.id)
|
||||
if not program:
|
||||
raise HTTPException(status_code=404, detail="No active loyalty program")
|
||||
|
||||
return {
|
||||
"vendor_name": vendor.name,
|
||||
"vendor_code": vendor.vendor_code,
|
||||
"program": {
|
||||
"id": program.id,
|
||||
"type": program.loyalty_type,
|
||||
"name": program.display_name,
|
||||
"card_color": program.card_color,
|
||||
"logo_url": program.logo_url,
|
||||
"stamps_target": program.stamps_target if program.is_stamps_enabled else None,
|
||||
"stamps_reward": program.stamps_reward_description if program.is_stamps_enabled else None,
|
||||
"points_per_euro": program.points_per_euro if program.is_points_enabled else None,
|
||||
"terms_text": program.terms_text,
|
||||
"privacy_url": program.privacy_url,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Apple Wallet Pass Download
|
||||
# =============================================================================
|
||||
|
||||
|
||||
@public_router.get("/passes/apple/{serial_number}.pkpass")
|
||||
def download_apple_pass(
|
||||
serial_number: str = Path(...),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Download Apple Wallet pass for a card."""
|
||||
# Find card by serial number
|
||||
card = (
|
||||
db.query(LoyaltyCard)
|
||||
.filter(LoyaltyCard.apple_serial_number == serial_number)
|
||||
.first()
|
||||
)
|
||||
|
||||
if not card:
|
||||
raise HTTPException(status_code=404, detail="Pass not found")
|
||||
|
||||
try:
|
||||
pass_data = apple_wallet_service.generate_pass(db, card)
|
||||
except LoyaltyException as e:
|
||||
logger.error(f"Failed to generate Apple pass for card {card.id}: {e}")
|
||||
raise HTTPException(status_code=500, detail="Failed to generate pass")
|
||||
|
||||
return Response(
|
||||
content=pass_data,
|
||||
media_type="application/vnd.apple.pkpass",
|
||||
headers={
|
||||
"Content-Disposition": f'attachment; filename="{serial_number}.pkpass"',
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Apple Web Service Endpoints
|
||||
# (Required for Apple Wallet to register devices and get updates)
|
||||
# =============================================================================
|
||||
|
||||
|
||||
@public_router.post("/apple/v1/devices/{device_id}/registrations/{pass_type_id}/{serial_number}")
|
||||
def register_device(
|
||||
device_id: str = Path(...),
|
||||
pass_type_id: str = Path(...),
|
||||
serial_number: str = Path(...),
|
||||
authorization: str | None = Header(None),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""
|
||||
Register a device for push notifications.
|
||||
|
||||
Called by Apple when user adds pass to wallet.
|
||||
"""
|
||||
# Validate authorization token
|
||||
auth_token = None
|
||||
if authorization and authorization.startswith("ApplePass "):
|
||||
auth_token = authorization.split(" ", 1)[1]
|
||||
|
||||
# Find card
|
||||
card = (
|
||||
db.query(LoyaltyCard)
|
||||
.filter(LoyaltyCard.apple_serial_number == serial_number)
|
||||
.first()
|
||||
)
|
||||
|
||||
if not card:
|
||||
raise HTTPException(status_code=404)
|
||||
|
||||
# Verify auth token
|
||||
if not auth_token or auth_token != card.apple_auth_token:
|
||||
raise HTTPException(status_code=401)
|
||||
|
||||
# Get push token from request body
|
||||
# Note: In real implementation, parse the JSON body for pushToken
|
||||
# For now, use device_id as a placeholder
|
||||
try:
|
||||
apple_wallet_service.register_device(db, card, device_id, device_id)
|
||||
return Response(status_code=201)
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to register device: {e}")
|
||||
raise HTTPException(status_code=500)
|
||||
|
||||
|
||||
@public_router.delete("/apple/v1/devices/{device_id}/registrations/{pass_type_id}/{serial_number}")
|
||||
def unregister_device(
|
||||
device_id: str = Path(...),
|
||||
pass_type_id: str = Path(...),
|
||||
serial_number: str = Path(...),
|
||||
authorization: str | None = Header(None),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""
|
||||
Unregister a device.
|
||||
|
||||
Called by Apple when user removes pass from wallet.
|
||||
"""
|
||||
# Validate authorization token
|
||||
auth_token = None
|
||||
if authorization and authorization.startswith("ApplePass "):
|
||||
auth_token = authorization.split(" ", 1)[1]
|
||||
|
||||
# Find card
|
||||
card = (
|
||||
db.query(LoyaltyCard)
|
||||
.filter(LoyaltyCard.apple_serial_number == serial_number)
|
||||
.first()
|
||||
)
|
||||
|
||||
if not card:
|
||||
raise HTTPException(status_code=404)
|
||||
|
||||
# Verify auth token
|
||||
if not auth_token or auth_token != card.apple_auth_token:
|
||||
raise HTTPException(status_code=401)
|
||||
|
||||
try:
|
||||
apple_wallet_service.unregister_device(db, card, device_id)
|
||||
return Response(status_code=200)
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to unregister device: {e}")
|
||||
raise HTTPException(status_code=500)
|
||||
|
||||
|
||||
@public_router.get("/apple/v1/devices/{device_id}/registrations/{pass_type_id}")
|
||||
def get_serial_numbers(
|
||||
device_id: str = Path(...),
|
||||
pass_type_id: str = Path(...),
|
||||
passesUpdatedSince: str | None = None,
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""
|
||||
Get list of pass serial numbers to update.
|
||||
|
||||
Called by Apple to check for updated passes.
|
||||
"""
|
||||
from app.modules.loyalty.models import AppleDeviceRegistration
|
||||
|
||||
# Find all cards registered to this device
|
||||
registrations = (
|
||||
db.query(AppleDeviceRegistration)
|
||||
.filter(AppleDeviceRegistration.device_library_identifier == device_id)
|
||||
.all()
|
||||
)
|
||||
|
||||
if not registrations:
|
||||
return Response(status_code=204)
|
||||
|
||||
# Get cards that have been updated since the given timestamp
|
||||
card_ids = [r.card_id for r in registrations]
|
||||
|
||||
query = db.query(LoyaltyCard).filter(LoyaltyCard.id.in_(card_ids))
|
||||
|
||||
if passesUpdatedSince:
|
||||
try:
|
||||
since = datetime.fromisoformat(passesUpdatedSince.replace("Z", "+00:00"))
|
||||
query = query.filter(LoyaltyCard.updated_at > since)
|
||||
except ValueError:
|
||||
pass
|
||||
|
||||
cards = query.all()
|
||||
|
||||
if not cards:
|
||||
return Response(status_code=204)
|
||||
|
||||
# Return serial numbers
|
||||
serial_numbers = [card.apple_serial_number for card in cards if card.apple_serial_number]
|
||||
last_updated = max(card.updated_at for card in cards)
|
||||
|
||||
return {
|
||||
"serialNumbers": serial_numbers,
|
||||
"lastUpdated": last_updated.isoformat(),
|
||||
}
|
||||
|
||||
|
||||
@public_router.get("/apple/v1/passes/{pass_type_id}/{serial_number}")
|
||||
def get_latest_pass(
|
||||
pass_type_id: str = Path(...),
|
||||
serial_number: str = Path(...),
|
||||
authorization: str | None = Header(None),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""
|
||||
Get the latest version of a pass.
|
||||
|
||||
Called by Apple to fetch updated pass data.
|
||||
"""
|
||||
# Validate authorization token
|
||||
auth_token = None
|
||||
if authorization and authorization.startswith("ApplePass "):
|
||||
auth_token = authorization.split(" ", 1)[1]
|
||||
|
||||
# Find card
|
||||
card = (
|
||||
db.query(LoyaltyCard)
|
||||
.filter(LoyaltyCard.apple_serial_number == serial_number)
|
||||
.first()
|
||||
)
|
||||
|
||||
if not card:
|
||||
raise HTTPException(status_code=404)
|
||||
|
||||
# Verify auth token
|
||||
if not auth_token or auth_token != card.apple_auth_token:
|
||||
raise HTTPException(status_code=401)
|
||||
|
||||
try:
|
||||
pass_data = apple_wallet_service.generate_pass(db, card)
|
||||
except LoyaltyException as e:
|
||||
logger.error(f"Failed to generate Apple pass for card {card.id}: {e}")
|
||||
raise HTTPException(status_code=500, detail="Failed to generate pass")
|
||||
|
||||
return Response(
|
||||
content=pass_data,
|
||||
media_type="application/vnd.apple.pkpass",
|
||||
headers={
|
||||
"Last-Modified": card.updated_at.strftime("%a, %d %b %Y %H:%M:%S GMT"),
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
@public_router.post("/apple/v1/log")
|
||||
def log_errors():
|
||||
"""
|
||||
Receive error logs from Apple.
|
||||
|
||||
Apple sends error logs here when there are issues with passes.
|
||||
"""
|
||||
# Just acknowledge - in production you'd log these
|
||||
return Response(status_code=200)
|
||||
506
app/modules/loyalty/routes/api/vendor.py
Normal file
506
app/modules/loyalty/routes/api/vendor.py
Normal file
@@ -0,0 +1,506 @@
|
||||
# app/modules/loyalty/routes/api/vendor.py
|
||||
"""
|
||||
Loyalty module vendor routes.
|
||||
|
||||
Store/vendor endpoints for:
|
||||
- Program management
|
||||
- Staff PINs
|
||||
- Card operations (stamps, points, redemptions)
|
||||
- Customer cards lookup
|
||||
- Dashboard stats
|
||||
"""
|
||||
|
||||
import logging
|
||||
|
||||
from fastapi import APIRouter, Depends, HTTPException, Path, Query, Request
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.api.deps import get_current_vendor_api, require_module_access
|
||||
from app.core.database import get_db
|
||||
from app.modules.loyalty.exceptions import (
|
||||
LoyaltyCardNotFoundException,
|
||||
LoyaltyException,
|
||||
LoyaltyProgramNotFoundException,
|
||||
)
|
||||
from app.modules.loyalty.schemas import (
|
||||
CardDetailResponse,
|
||||
CardEnrollRequest,
|
||||
CardListResponse,
|
||||
CardLookupResponse,
|
||||
CardResponse,
|
||||
PinCreate,
|
||||
PinListResponse,
|
||||
PinResponse,
|
||||
PinUpdate,
|
||||
PointsEarnRequest,
|
||||
PointsEarnResponse,
|
||||
PointsRedeemRequest,
|
||||
PointsRedeemResponse,
|
||||
ProgramCreate,
|
||||
ProgramResponse,
|
||||
ProgramStatsResponse,
|
||||
ProgramUpdate,
|
||||
StampRedeemRequest,
|
||||
StampRedeemResponse,
|
||||
StampRequest,
|
||||
StampResponse,
|
||||
)
|
||||
from app.modules.loyalty.services import (
|
||||
card_service,
|
||||
pin_service,
|
||||
points_service,
|
||||
program_service,
|
||||
stamp_service,
|
||||
wallet_service,
|
||||
)
|
||||
from models.database.user import User
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Vendor router with module access control
|
||||
vendor_router = APIRouter(
|
||||
prefix="/loyalty",
|
||||
dependencies=[Depends(require_module_access("loyalty"))],
|
||||
)
|
||||
|
||||
|
||||
def get_client_info(request: Request) -> tuple[str | None, str | None]:
|
||||
"""Extract client IP and user agent from request."""
|
||||
ip = request.client.host if request.client else None
|
||||
user_agent = request.headers.get("user-agent")
|
||||
return ip, user_agent
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Program Management
|
||||
# =============================================================================
|
||||
|
||||
|
||||
@vendor_router.get("/program", response_model=ProgramResponse)
|
||||
def get_program(
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Get the vendor's loyalty program."""
|
||||
vendor_id = current_user.token_vendor_id
|
||||
|
||||
program = program_service.get_program_by_vendor(db, vendor_id)
|
||||
if not program:
|
||||
raise HTTPException(status_code=404, detail="No loyalty program configured")
|
||||
|
||||
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
|
||||
|
||||
|
||||
@vendor_router.post("/program", response_model=ProgramResponse, status_code=201)
|
||||
def create_program(
|
||||
data: ProgramCreate,
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Create a loyalty program for the vendor."""
|
||||
vendor_id = current_user.token_vendor_id
|
||||
|
||||
try:
|
||||
program = program_service.create_program(db, vendor_id, data)
|
||||
except LoyaltyException as e:
|
||||
raise HTTPException(status_code=e.status_code, detail=e.message)
|
||||
|
||||
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
|
||||
|
||||
|
||||
@vendor_router.patch("/program", response_model=ProgramResponse)
|
||||
def update_program(
|
||||
data: ProgramUpdate,
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Update the vendor's loyalty program."""
|
||||
vendor_id = current_user.token_vendor_id
|
||||
|
||||
program = program_service.get_program_by_vendor(db, vendor_id)
|
||||
if not program:
|
||||
raise HTTPException(status_code=404, detail="No loyalty program configured")
|
||||
|
||||
program = program_service.update_program(db, program.id, data)
|
||||
|
||||
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
|
||||
|
||||
|
||||
@vendor_router.get("/stats", response_model=ProgramStatsResponse)
|
||||
def get_stats(
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Get loyalty program statistics."""
|
||||
vendor_id = current_user.token_vendor_id
|
||||
|
||||
program = program_service.get_program_by_vendor(db, vendor_id)
|
||||
if not program:
|
||||
raise HTTPException(status_code=404, detail="No loyalty program configured")
|
||||
|
||||
stats = program_service.get_program_stats(db, program.id)
|
||||
return ProgramStatsResponse(**stats)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Staff PINs
|
||||
# =============================================================================
|
||||
|
||||
|
||||
@vendor_router.get("/pins", response_model=PinListResponse)
|
||||
def list_pins(
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""List all staff PINs for the loyalty program."""
|
||||
vendor_id = current_user.token_vendor_id
|
||||
|
||||
program = program_service.get_program_by_vendor(db, vendor_id)
|
||||
if not program:
|
||||
raise HTTPException(status_code=404, detail="No loyalty program configured")
|
||||
|
||||
pins = pin_service.list_pins(db, program.id)
|
||||
|
||||
return PinListResponse(
|
||||
pins=[PinResponse.model_validate(pin) for pin in pins],
|
||||
total=len(pins),
|
||||
)
|
||||
|
||||
|
||||
@vendor_router.post("/pins", response_model=PinResponse, status_code=201)
|
||||
def create_pin(
|
||||
data: PinCreate,
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Create a new staff PIN."""
|
||||
vendor_id = current_user.token_vendor_id
|
||||
|
||||
program = program_service.get_program_by_vendor(db, vendor_id)
|
||||
if not program:
|
||||
raise HTTPException(status_code=404, detail="No loyalty program configured")
|
||||
|
||||
pin = pin_service.create_pin(db, program.id, vendor_id, data)
|
||||
return PinResponse.model_validate(pin)
|
||||
|
||||
|
||||
@vendor_router.patch("/pins/{pin_id}", response_model=PinResponse)
|
||||
def update_pin(
|
||||
pin_id: int = Path(..., gt=0),
|
||||
data: PinUpdate = None,
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Update a staff PIN."""
|
||||
pin = pin_service.update_pin(db, pin_id, data)
|
||||
return PinResponse.model_validate(pin)
|
||||
|
||||
|
||||
@vendor_router.delete("/pins/{pin_id}", status_code=204)
|
||||
def delete_pin(
|
||||
pin_id: int = Path(..., gt=0),
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Delete a staff PIN."""
|
||||
pin_service.delete_pin(db, pin_id)
|
||||
|
||||
|
||||
@vendor_router.post("/pins/{pin_id}/unlock", response_model=PinResponse)
|
||||
def unlock_pin(
|
||||
pin_id: int = Path(..., gt=0),
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Unlock a locked staff PIN."""
|
||||
pin = pin_service.unlock_pin(db, pin_id)
|
||||
return PinResponse.model_validate(pin)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Card Management
|
||||
# =============================================================================
|
||||
|
||||
|
||||
@vendor_router.get("/cards", response_model=CardListResponse)
|
||||
def list_cards(
|
||||
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, max_length=100),
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""List loyalty cards for the vendor."""
|
||||
vendor_id = current_user.token_vendor_id
|
||||
|
||||
program = program_service.get_program_by_vendor(db, vendor_id)
|
||||
if not program:
|
||||
raise HTTPException(status_code=404, detail="No loyalty program configured")
|
||||
|
||||
cards, total = card_service.list_cards(
|
||||
db,
|
||||
vendor_id,
|
||||
skip=skip,
|
||||
limit=limit,
|
||||
is_active=is_active,
|
||||
search=search,
|
||||
)
|
||||
|
||||
card_responses = []
|
||||
for card in cards:
|
||||
response = CardResponse(
|
||||
id=card.id,
|
||||
card_number=card.card_number,
|
||||
customer_id=card.customer_id,
|
||||
vendor_id=card.vendor_id,
|
||||
program_id=card.program_id,
|
||||
stamp_count=card.stamp_count,
|
||||
stamps_target=program.stamps_target,
|
||||
stamps_until_reward=max(0, program.stamps_target - card.stamp_count),
|
||||
total_stamps_earned=card.total_stamps_earned,
|
||||
stamps_redeemed=card.stamps_redeemed,
|
||||
points_balance=card.points_balance,
|
||||
total_points_earned=card.total_points_earned,
|
||||
points_redeemed=card.points_redeemed,
|
||||
is_active=card.is_active,
|
||||
created_at=card.created_at,
|
||||
has_google_wallet=bool(card.google_object_id),
|
||||
has_apple_wallet=bool(card.apple_serial_number),
|
||||
)
|
||||
card_responses.append(response)
|
||||
|
||||
return CardListResponse(cards=card_responses, total=total)
|
||||
|
||||
|
||||
@vendor_router.post("/cards/lookup", response_model=CardLookupResponse)
|
||||
def lookup_card(
|
||||
request: Request,
|
||||
card_id: int | None = Query(None),
|
||||
qr_code: str | None = Query(None),
|
||||
card_number: str | None = Query(None),
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Look up a card by ID, QR code, or card number."""
|
||||
vendor_id = current_user.token_vendor_id
|
||||
|
||||
try:
|
||||
card = card_service.lookup_card(
|
||||
db,
|
||||
card_id=card_id,
|
||||
qr_code=qr_code,
|
||||
card_number=card_number,
|
||||
)
|
||||
except LoyaltyCardNotFoundException:
|
||||
raise HTTPException(status_code=404, detail="Card not found")
|
||||
|
||||
# Verify card belongs to this vendor
|
||||
if card.vendor_id != vendor_id:
|
||||
raise HTTPException(status_code=404, detail="Card not found")
|
||||
|
||||
program = card.program
|
||||
|
||||
# Check cooldown
|
||||
can_stamp, _ = card.can_stamp(program.cooldown_minutes)
|
||||
cooldown_ends = None
|
||||
if not can_stamp and card.last_stamp_at:
|
||||
from datetime import timedelta
|
||||
|
||||
cooldown_ends = card.last_stamp_at + timedelta(minutes=program.cooldown_minutes)
|
||||
|
||||
# Get stamps today
|
||||
stamps_today = card_service.get_stamps_today(db, card.id)
|
||||
|
||||
return CardLookupResponse(
|
||||
card_id=card.id,
|
||||
card_number=card.card_number,
|
||||
customer_id=card.customer_id,
|
||||
customer_name=card.customer.full_name if card.customer else None,
|
||||
customer_email=card.customer.email if card.customer else "",
|
||||
stamp_count=card.stamp_count,
|
||||
stamps_target=program.stamps_target,
|
||||
stamps_until_reward=max(0, program.stamps_target - card.stamp_count),
|
||||
points_balance=card.points_balance,
|
||||
can_redeem_stamps=card.stamp_count >= program.stamps_target,
|
||||
stamp_reward_description=program.stamps_reward_description,
|
||||
can_stamp=can_stamp,
|
||||
cooldown_ends_at=cooldown_ends,
|
||||
stamps_today=stamps_today,
|
||||
max_daily_stamps=program.max_daily_stamps,
|
||||
can_earn_more_stamps=stamps_today < program.max_daily_stamps,
|
||||
)
|
||||
|
||||
|
||||
@vendor_router.post("/cards/enroll", response_model=CardResponse, status_code=201)
|
||||
def enroll_customer(
|
||||
data: CardEnrollRequest,
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Enroll a customer in the loyalty program."""
|
||||
vendor_id = current_user.token_vendor_id
|
||||
|
||||
if not data.customer_id:
|
||||
raise HTTPException(status_code=400, detail="customer_id is required")
|
||||
|
||||
try:
|
||||
card = card_service.enroll_customer(db, data.customer_id, vendor_id)
|
||||
except LoyaltyException as e:
|
||||
raise HTTPException(status_code=e.status_code, detail=e.message)
|
||||
|
||||
program = card.program
|
||||
|
||||
return CardResponse(
|
||||
id=card.id,
|
||||
card_number=card.card_number,
|
||||
customer_id=card.customer_id,
|
||||
vendor_id=card.vendor_id,
|
||||
program_id=card.program_id,
|
||||
stamp_count=card.stamp_count,
|
||||
stamps_target=program.stamps_target,
|
||||
stamps_until_reward=program.stamps_target,
|
||||
total_stamps_earned=card.total_stamps_earned,
|
||||
stamps_redeemed=card.stamps_redeemed,
|
||||
points_balance=card.points_balance,
|
||||
total_points_earned=card.total_points_earned,
|
||||
points_redeemed=card.points_redeemed,
|
||||
is_active=card.is_active,
|
||||
created_at=card.created_at,
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Stamp Operations
|
||||
# =============================================================================
|
||||
|
||||
|
||||
@vendor_router.post("/stamp", response_model=StampResponse)
|
||||
def add_stamp(
|
||||
request: Request,
|
||||
data: StampRequest,
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Add a stamp to a loyalty card."""
|
||||
ip, user_agent = get_client_info(request)
|
||||
|
||||
try:
|
||||
result = stamp_service.add_stamp(
|
||||
db,
|
||||
card_id=data.card_id,
|
||||
qr_code=data.qr_code,
|
||||
card_number=data.card_number,
|
||||
staff_pin=data.staff_pin,
|
||||
ip_address=ip,
|
||||
user_agent=user_agent,
|
||||
notes=data.notes,
|
||||
)
|
||||
except LoyaltyException as e:
|
||||
raise HTTPException(status_code=e.status_code, detail=e.message)
|
||||
|
||||
return StampResponse(**result)
|
||||
|
||||
|
||||
@vendor_router.post("/stamp/redeem", response_model=StampRedeemResponse)
|
||||
def redeem_stamps(
|
||||
request: Request,
|
||||
data: StampRedeemRequest,
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Redeem stamps for a reward."""
|
||||
ip, user_agent = get_client_info(request)
|
||||
|
||||
try:
|
||||
result = stamp_service.redeem_stamps(
|
||||
db,
|
||||
card_id=data.card_id,
|
||||
qr_code=data.qr_code,
|
||||
card_number=data.card_number,
|
||||
staff_pin=data.staff_pin,
|
||||
ip_address=ip,
|
||||
user_agent=user_agent,
|
||||
notes=data.notes,
|
||||
)
|
||||
except LoyaltyException as e:
|
||||
raise HTTPException(status_code=e.status_code, detail=e.message)
|
||||
|
||||
return StampRedeemResponse(**result)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Points Operations
|
||||
# =============================================================================
|
||||
|
||||
|
||||
@vendor_router.post("/points", response_model=PointsEarnResponse)
|
||||
def earn_points(
|
||||
request: Request,
|
||||
data: PointsEarnRequest,
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Earn points from a purchase."""
|
||||
ip, user_agent = get_client_info(request)
|
||||
|
||||
try:
|
||||
result = points_service.earn_points(
|
||||
db,
|
||||
card_id=data.card_id,
|
||||
qr_code=data.qr_code,
|
||||
card_number=data.card_number,
|
||||
purchase_amount_cents=data.purchase_amount_cents,
|
||||
order_reference=data.order_reference,
|
||||
staff_pin=data.staff_pin,
|
||||
ip_address=ip,
|
||||
user_agent=user_agent,
|
||||
notes=data.notes,
|
||||
)
|
||||
except LoyaltyException as e:
|
||||
raise HTTPException(status_code=e.status_code, detail=e.message)
|
||||
|
||||
return PointsEarnResponse(**result)
|
||||
|
||||
|
||||
@vendor_router.post("/points/redeem", response_model=PointsRedeemResponse)
|
||||
def redeem_points(
|
||||
request: Request,
|
||||
data: PointsRedeemRequest,
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db),
|
||||
):
|
||||
"""Redeem points for a reward."""
|
||||
ip, user_agent = get_client_info(request)
|
||||
|
||||
try:
|
||||
result = points_service.redeem_points(
|
||||
db,
|
||||
card_id=data.card_id,
|
||||
qr_code=data.qr_code,
|
||||
card_number=data.card_number,
|
||||
reward_id=data.reward_id,
|
||||
staff_pin=data.staff_pin,
|
||||
ip_address=ip,
|
||||
user_agent=user_agent,
|
||||
notes=data.notes,
|
||||
)
|
||||
except LoyaltyException as e:
|
||||
raise HTTPException(status_code=e.status_code, detail=e.message)
|
||||
|
||||
return PointsRedeemResponse(**result)
|
||||
Reference in New Issue
Block a user