│ Loyalty Platform & Module Implementation Plan │ │ │ │ Overview │ │ │ │ Create a Loyalty Module for Wizamart that provides stamp-based and points-based loyalty programs with Google Wallet and Apple Wallet integration. │ │ │ │ Entity Mapping │ │ ┌────────────────────┬────────────────────┬──────────────────────────────────────────────────────────┐ │ │ │ Loyalty Concept │ Wizamart Entity │ Notes │ │ │ ├────────────────────┼────────────────────┼──────────────────────────────────────────────────────────┤ │ │ │ Merchant │ Company │ Existing - legal business entity │ │ │ ├────────────────────┼────────────────────┼──────────────────────────────────────────────────────────┤ │ │ │ Store │ Vendor │ Existing - brand/location │ │ │ ├────────────────────┼────────────────────┼──────────────────────────────────────────────────────────┤ │ │ │ Customer │ Customer │ Existing - has vendor_id, total_spent, marketing_consent │ │ │ ├────────────────────┼────────────────────┼──────────────────────────────────────────────────────────┤ │ │ │ Pass Object │ LoyaltyCard │ NEW - links customer to vendor's program │ │ │ ├────────────────────┼────────────────────┼──────────────────────────────────────────────────────────┤ │ │ │ Stamp/Points Event │ LoyaltyTransaction │ NEW - records all operations │ │ │ ├────────────────────┼────────────────────┼──────────────────────────────────────────────────────────┤ │ │ │ Staff PIN │ StaffPin │ NEW - fraud prevention │ │ │ └────────────────────┴────────────────────┴──────────────────────────────────────────────────────────┘ │ │ Database Models │ │ │ │ Core Models (5 tables) │ │ │ │ 1. loyalty_programs - Vendor's program configuration │ │ - vendor_id (unique FK) │ │ - loyalty_type: stamps | points | hybrid │ │ - Stamps config: stamps_target, stamps_reward_description │ │ - Points config: points_per_euro, points_rewards (JSON) │ │ - Anti-fraud: cooldown_minutes, max_daily_stamps, require_staff_pin │ │ - Branding: card_name, card_color, logo_url │ │ - Wallet IDs: google_issuer_id, apple_pass_type_id │ │ 2. loyalty_cards - Customer's card (PassObject) │ │ - customer_id, program_id, vendor_id │ │ - card_number (unique), qr_code_data │ │ - Stamps: stamp_count, total_stamps_earned, stamps_redeemed │ │ - Points: points_balance, total_points_earned, points_redeemed │ │ - Wallet: google_object_id, apple_serial_number, apple_auth_token │ │ - Timestamps: last_stamp_at, last_points_at │ │ 3. loyalty_transactions - All loyalty events │ │ - card_id, vendor_id, staff_pin_id │ │ - transaction_type: stamp_earned | stamp_redeemed | points_earned | points_redeemed │ │ - stamps_delta, points_delta, purchase_amount_cents │ │ - Metadata: ip_address, user_agent, notes │ │ 4. staff_pins - Fraud prevention │ │ - program_id, vendor_id │ │ - name, pin_hash (bcrypt) │ │ - failed_attempts, locked_until │ │ 5. apple_device_registrations - Apple Wallet push │ │ - card_id, device_library_identifier, push_token │ │ │ │ Module Structure │ │ │ │ app/modules/loyalty/ │ │ ├── __init__.py │ │ ├── definition.py # ModuleDefinition (requires: customers) │ │ ├── config.py # LOYALTY_ env vars │ │ ├── exceptions.py │ │ ├── models/ │ │ │ ├── loyalty_program.py │ │ │ ├── loyalty_card.py │ │ │ ├── loyalty_transaction.py │ │ │ ├── staff_pin.py │ │ │ └── apple_device.py │ │ ├── schemas/ │ │ │ ├── program.py │ │ │ ├── card.py │ │ │ ├── stamp.py │ │ │ ├── points.py │ │ │ └── pin.py │ │ ├── services/ │ │ │ ├── program_service.py # Program CRUD │ │ │ ├── card_service.py # Card enrollment, lookup │ │ │ ├── stamp_service.py # Stamp logic + anti-fraud │ │ │ ├── points_service.py # Points logic │ │ │ ├── pin_service.py # PIN validation │ │ │ ├── wallet_service.py # Unified wallet abstraction │ │ │ ├── google_wallet_service.py │ │ │ └── apple_wallet_service.py │ │ ├── routes/ │ │ │ ├── api/ │ │ │ │ ├── admin.py # Platform admin │ │ │ │ ├── vendor.py # Vendor dashboard │ │ │ │ └── public.py # Enrollment, Apple web service │ │ │ └── pages/ │ │ ├── tasks/ │ │ │ ├── point_expiration.py │ │ │ └── wallet_sync.py │ │ ├── migrations/versions/ │ │ ├── locales/ │ │ └── templates/ │ │ │ │ Key API Endpoints │ │ │ │ Public (Customer) │ │ │ │ - POST /api/v1/loyalty/enroll/{vendor_code} - Enroll in program │ │ - GET /api/v1/loyalty/passes/apple/{serial}.pkpass - Download Apple pass │ │ - Apple Web Service endpoints for device registration/updates │ │ │ │ Vendor (Staff) │ │ │ │ - POST /api/v1/vendor/loyalty/stamp - Add stamp (requires PIN) │ │ - POST /api/v1/vendor/loyalty/points - Add points from purchase │ │ - POST /api/v1/vendor/loyalty/*/redeem - Redeem for reward │ │ - GET /api/v1/vendor/loyalty/cards - List customer cards │ │ - GET /api/v1/vendor/loyalty/pins - Manage staff PINs │ │ - GET /api/v1/vendor/loyalty/stats - Dashboard analytics │ │ │ │ Admin │ │ │ │ - GET /api/v1/admin/loyalty/programs - List all programs │ │ - GET /api/v1/admin/loyalty/stats - Platform-wide stats │ │ │ │ Anti-Fraud System │ │ │ │ 1. Staff PIN - Required for all stamp/points operations │ │ 2. Cooldown - Configurable minutes between stamps (default: 15) │ │ 3. Daily Limit - Max stamps per card per day (default: 5) │ │ 4. PIN Lockout - Lock after 5 failed attempts for 30 minutes │ │ 5. Audit Trail - All transactions logged with IP/user agent │ │ │ │ Wallet Integration │ │ │ │ Google Wallet │ │ │ │ - Create LoyaltyClass when program created │ │ - Create LoyaltyObject when customer enrolls │ │ - PATCH object on stamp/points change │ │ - Generate JWT-based "Add to Wallet" URL │ │ │ │ Apple Wallet │ │ │ │ - Generate .pkpass file (pass.json + images + signature) │ │ - Implement Apple Web Service for device registration │ │ - Send push notification on updates → device fetches new pass │ │ │ │ Implementation Phases │ │ │ │ Phase 1: MVP (Target) │ │ │ │ 1. Core Infrastructure │ │ - Module structure, definition, exceptions │ │ - Database models and migrations │ │ - Program service (CRUD) │ │ - Card service (enrollment, lookup) │ │ 2. Stamp Loyalty │ │ - Staff PIN service with lockout │ │ - Stamp service with anti-fraud │ │ - Transaction logging │ │ - Vendor API routes │ │ 3. Points Loyalty │ │ - Points service │ │ - Purchase-to-points calculation │ │ - Redemption flow │ │ 4. Wallet Integration │ │ - Google Wallet service │ │ - Apple .pkpass generation │ │ - Apple Web Service endpoints │ │ 5. Dashboard │ │ - Vendor stats endpoint │ │ - Transaction history │ │ - QR code generation │ │ │ │ Phase 2: Future Enhancements │ │ │ │ - Rewards catalog with configurable tiers │ │ - Customer tiers (Bronze/Silver/Gold) │ │ - Referral program │ │ - Gamification (spin wheel, scratch cards) │ │ - POS integration │ │ │ │ Files to Create │ │ │ │ app/modules/loyalty/ │ │ ├── __init__.py │ │ ├── definition.py │ │ ├── config.py │ │ ├── exceptions.py │ │ ├── models/__init__.py │ │ ├── models/loyalty_program.py │ │ ├── models/loyalty_card.py │ │ ├── models/loyalty_transaction.py │ │ ├── models/staff_pin.py │ │ ├── models/apple_device.py │ │ ├── schemas/__init__.py │ │ ├── schemas/program.py │ │ ├── schemas/card.py │ │ ├── schemas/stamp.py │ │ ├── schemas/points.py │ │ ├── schemas/pin.py │ │ ├── services/__init__.py │ │ ├── services/program_service.py │ │ ├── services/card_service.py │ │ ├── services/stamp_service.py │ │ ├── services/points_service.py │ │ ├── services/pin_service.py │ │ ├── services/wallet_service.py │ │ ├── services/google_wallet_service.py │ │ ├── services/apple_wallet_service.py │ │ ├── routes/__init__.py │ │ ├── routes/api/__init__.py │ │ ├── routes/api/admin.py │ │ ├── routes/api/vendor.py │ │ ├── routes/api/public.py │ │ ├── routes/pages/__init__.py │ │ ├── tasks/__init__.py │ │ ├── tasks/point_expiration.py │ │ ├── migrations/__init__.py │ │ ├── migrations/versions/__init__.py │ │ └── locales/{en,fr,de,lu}.json │ │ │ │ Reference Patterns │ │ │ │ - Module definition: app/modules/billing/definition.py │ │ - Models: app/modules/billing/models/subscription.py │ │ - Services: app/modules/billing/services/subscription_service.py │ │ - Customer integration: models/database/customer.py │ │ │ │ Verification │ │ │ │ 1. Run architecture validator: python scripts/validate_architecture.py │ │ 2. Run migrations: alembic upgrade head │ │ 3. Test enrollment flow via API │ │ 4. Test stamp/points operations with PIN │ │ 5. Verify wallet pass generation │ │ 6. Check anti-fraud (cooldown, limits, lockout)