Samir Boulahtit
eeafe6389f
- Update models/database/__init__.py to import from module locations - Update models/schema/__init__.py to remove deleted modules - Update models/__init__.py to import Inventory from module - Remove duplicate AdminNotification from models/database/admin.py - Fix monitoring module to import AdminNotification from messaging - Update stats schema imports in admin/vendor API - Update notification schema imports - Add order_item_exception.py schema to orders module - Fix app/api/v1/__init__.py to use storefront instead of shop - Add cms_admin_pages import to main.py - Fix password_reset_token imports - Fix AdminNotification test imports Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
229 lines
51 KiB
Plaintext
229 lines
51 KiB
Plaintext
│ 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) |