Samir Boulahtit
b5a803cde8
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>
115 lines
2.5 KiB
Python
115 lines
2.5 KiB
Python
# app/modules/loyalty/schemas/stamp.py
|
|
"""
|
|
Pydantic schemas for stamp operations.
|
|
"""
|
|
|
|
from datetime import datetime
|
|
|
|
from pydantic import BaseModel, Field
|
|
|
|
|
|
class StampRequest(BaseModel):
|
|
"""Schema for adding a stamp to a card."""
|
|
|
|
card_id: int | None = Field(
|
|
None,
|
|
description="Card ID (use this or qr_code)",
|
|
)
|
|
qr_code: str | None = Field(
|
|
None,
|
|
description="QR code data from card scan",
|
|
)
|
|
card_number: str | None = Field(
|
|
None,
|
|
description="Card number (manual entry)",
|
|
)
|
|
|
|
# Authentication
|
|
staff_pin: str | None = Field(
|
|
None,
|
|
min_length=4,
|
|
max_length=6,
|
|
description="Staff PIN for verification",
|
|
)
|
|
|
|
# Optional metadata
|
|
notes: str | None = Field(
|
|
None,
|
|
max_length=500,
|
|
description="Optional note about this stamp",
|
|
)
|
|
|
|
|
|
class StampResponse(BaseModel):
|
|
"""Schema for stamp operation response."""
|
|
|
|
success: bool = True
|
|
message: str = "Stamp added successfully"
|
|
|
|
# Card state after stamp
|
|
card_id: int
|
|
card_number: str
|
|
stamp_count: int
|
|
stamps_target: int
|
|
stamps_until_reward: int
|
|
|
|
# Did this trigger a reward?
|
|
reward_earned: bool = False
|
|
reward_description: str | None = None
|
|
|
|
# Cooldown info
|
|
next_stamp_available_at: datetime | None = None
|
|
|
|
# Today's activity
|
|
stamps_today: int
|
|
stamps_remaining_today: int
|
|
|
|
|
|
class StampRedeemRequest(BaseModel):
|
|
"""Schema for redeeming stamps for a reward."""
|
|
|
|
card_id: int | None = Field(
|
|
None,
|
|
description="Card ID (use this or qr_code)",
|
|
)
|
|
qr_code: str | None = Field(
|
|
None,
|
|
description="QR code data from card scan",
|
|
)
|
|
card_number: str | None = Field(
|
|
None,
|
|
description="Card number (manual entry)",
|
|
)
|
|
|
|
# Authentication
|
|
staff_pin: str | None = Field(
|
|
None,
|
|
min_length=4,
|
|
max_length=6,
|
|
description="Staff PIN for verification",
|
|
)
|
|
|
|
# Optional metadata
|
|
notes: str | None = Field(
|
|
None,
|
|
max_length=500,
|
|
description="Optional note about this redemption",
|
|
)
|
|
|
|
|
|
class StampRedeemResponse(BaseModel):
|
|
"""Schema for stamp redemption response."""
|
|
|
|
success: bool = True
|
|
message: str = "Reward redeemed successfully"
|
|
|
|
# Card state after redemption
|
|
card_id: int
|
|
card_number: str
|
|
stamp_count: int # Should be 0 after redemption
|
|
stamps_target: int
|
|
|
|
# Reward info
|
|
reward_description: str
|
|
total_redemptions: int # Lifetime redemptions for this card
|