│ 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)