Wiltlover Cafe Loyalty Program

# Wiltlover Cafe Loyalty Program - Complete Documentation ## Table of Contents 1. App Overview 2. User Roles & Features 3. Customer Features 4. Staff Features 5. Admin Features 6. SuperAdmin Features 7. Key Workflows 8. Data Management 9. Security Features --- ## App Overview Wiltlover Cafe Loyalty Program is a comprehensive points-based loyalty system with role-based access control. Customers earn points on purchases, unlock tier benefits, and redeem rewards. Staff scan QR codes to add points, admins manage operations, and superadmins oversee the entire system. ### Core Concepts - **Points**: Currency earned through purchases, redeemable for rewards - **Tiers**: Bronze → Silver → Gold (based on lifetime points) - **Multipliers**: Tier-based earning multipliers (1x, 1.1x, 1.2x) - **QR Code**: Unique per customer, expires after 5 minutes - **Redemptions**: Rewards redeemed with points, confirmed by staff --- ## User Roles & Features | Role | Key Pages | Permissions | |------|-----------|-------------| | **Customer** | News, Dashboard, Rewards, MyQR, History, Help, Profile | View points, redeem rewards | | **Staff** | Scanner, Summary | Add points, process redemptions | | **Admin** | Dashboard, Analytics, Customers, Transactions, Rewards, Staff, Branches, Audit Log | Manage branch operations | | **SuperAdmin** | All pages + Marketing, Security, Ban Management, Role Assignment | System-wide control | --- ## Customer Features ### 1. News (/News) View latest announcements and promotions from the cafe. Filter by type and browse stories. ### 2. Dashboard (/CustomerDashboard) Home screen with current points, lifetime points, tier badge, quick actions, and recent activity. ### 3. My QR (/MyQR) Display unique QR code for staff to scan (auto-refreshes every 5 minutes). ### 4. Rewards (/Rewards) Browse all available rewards by category with points cost and availability. ### 5. Active Redemptions (/ActiveRedemptions) View pending and confirmed reward redemptions with validation codes. ### 6. Points History (/PointsHistory) Chronological list of all earn/redeem/adjust transactions with filtering. ### 7. Help Center (/HelpCenter) AI-powered customer support chat for instant assistance. ### 8. Profile (/Profile) Manage personal account information (phone, birthday, view member since date). --- ## Staff Features ### 1. Smart Scanner (/StaffScanner) **Purpose**: Scan customer QR codes to add points or process redemptions **Points Mode**: - Enter purchase amount in PHP - Optional receipt number - System auto-calculates points based on customer tier - Confirmation required before applying **Redeem Mode**: - List pending redemptions (valid for 1 month) - Verify redemption code - Confirm completion ### 2. Today's Summary (/StaffSummary) View daily branch statistics: points issued, transactions, redemptions, unique customers served. --- ## Admin Features **Dashboard** - Branch operations overview with key metrics and charts **Analytics** - Business intelligence with trends and customer segmentation **Customers** - Search, adjust points, view transaction history **Transactions** - View, filter, and export all points transactions **Rewards** - Create/manage reward catalog with limits and categories **Staff** - Create staff accounts, assign branches, set permissions **Branches** - Manage locations, operating hours, contact info **Audit Log** - Track all system actions for compliance **Settings** - Configure points earning rules and tier thresholds --- ## SuperAdmin Features **Dashboard** - System-wide overview with fraud alerts **Marketing** - AI-powered campaign generation for customer engagement **Role Assignment** - Manage all user roles (promote to admin/superadmin) **Security Alerts** - Monitor suspicious activity (excessive points, duplicate accounts, behavior anomalies) **Ban Management** - Ban/unban users with reason tracking **Points Correction** - Manual point adjustments with full audit trail **Audit Log** - System-wide audit trail for all actions **News Management** - Create/publish announcements to customers --- ## Key Workflows ### Workflow 1: Customer Earning Points 1. Customer visits cafe 2. Staff scans customer's QR code using Smart Scanner 3. Staff enters purchase amount (₱) 4. System auto-calculates points based on tier 5. Staff confirms transaction 6. Points added to customer's account 7. Notification sent to customer ### Workflow 2: Customer Redeeming Reward 1. Customer browses Rewards page 2. Customer clicks "Redeem" 3. System generates redemption code (1-month validity) 4. Customer shows code to staff 5. Staff uses Smart Scanner → Redeem mode 6. Staff confirms redemption with code 7. Reward status changes to "Confirmed" 8. Customer receives notification ### Workflow 3: Tier Progression 1. Customer earns points through purchases 2. System tracks lifetime_points separately from total_points 3. When lifetime_points crosses tier threshold: - Bronze (0 pts) → Silver (500 pts) - Silver (500 pts) → Gold (1,500 pts) 4. Multiplier automatically applies to future earnings 5. Customer sees tier upgrade in Dashboard ### Workflow 4: Admin Managing Points 1. Admin accesses Customers page 2. Searches for customer 3. Clicks "Adjust Points" 4. Enters adjustment amount + reason 5. System logs action in Audit Log 6. Customer receives notification 7. Full audit trail maintained --- ## Data Management ### Customer Profile Entity - user_id: Linked user email - total_points: Current points balance - lifetime_points: Total earned (for tier calculation) - tier: bronze | silver | gold - qr_token: Unique QR code identifier - qr_token_expires: Auto-refresh after 5 min - phone: Customer phone - birthday: For special offers - is_suspended: Account ban status ### Points Transaction Entity - customer_id: Customer user ID - type: earn | redeem | adjust - points: Amount (positive/negative) - staff_id: Who processed - branch_id: Which branch - receipt_number: Purchase receipt ref - amount_spent: PHP amount (for earn only) ### Redemption Entity - customer_id: Customer user ID - reward_id: Which reward - reward_name: Snapshot of reward name - points_spent: Points deducted - redemption_code: One-time validation code - code_expires_at: 1 month validity - status: pending | confirmed | expired | cancelled - staff_id: Who confirmed - confirmed_at: Confirmation timestamp ### Audit Log Entity - action_type: ADD_POINTS | REDEEM | ADJUST | ROLE_CHANGE | etc. - performed_by_user_id: Actor user ID - performed_by_email: Actor email - performed_by_role: staff | admin | superadmin - branch_id: Location of action - target_user_id: Customer affected - points_delta: Point change - ip_address: Request origin --- ## Security Features ### AI-Driven Fraud Detection The system includes advanced fraud detection mechanisms that run daily: 1. **Excessive Points Manipulation**: Detects customers earning >5,000 points in 24 hours 2. **Unusual Redemption Patterns**: Flags >10 redemptions in 7 days 3. **Duplicate Account Detection**: Identifies multiple accounts per email/phone 4. **Behavior Anomalies**: AI analyzes earning velocity, tier upgrade speed, redemption timing 5. **Suspicious Staff Activity**: Monitors staff adding large points without receipt verification All alerts are reviewed and resolved by SuperAdmins. ### Other Security Measures - QR codes expire after 5 minutes - All actions logged in Audit Log - Banned users cannot earn/redeem points - Staff restricted to their assigned branch - Redemption codes valid for 1 month only --- ## Points Calculation Formula: points = amount_spent × points_per_peso × tier_multiplier Tier Multipliers: - Bronze (0-499 lifetime points): 1.0x - Silver (500-1,499 lifetime points): 1.1x - Gold (1,500+ lifetime points): 1.2x Example: - Customer (Silver tier) spends ₱1,000 - points_per_peso = 0.04 (1 point per ₱25) - Calculation: 1,000 × 0.04 × 1.1 = 44 points --- ## Important Notes ### Branch Assignment - Staff must have branch_id assigned - Staff can only process transactions for their branch - Admins see only their assigned branch data - SuperAdmins see all branches ### QR Code Management - QR codes expire after 5 minutes of generation - Customers can refresh QR from MyQR page - Auto-expires based on qr_token_expires timestamp ### Redemption Process - Redemption codes valid for exactly 1 month - Once confirmed by staff, reward is finalized - Expired codes can be cancelled by admin - Each code is one-time use only ### Support & Help - Customers: Use Help Center chat for AI-powered support - Staff: Contact admin for training on Scanner - Admins: Check Audit Log for troubleshooting - SuperAdmins: Review Security Alerts for fraud issues --- ## Contact & Support For technical issues, contact the SuperAdmin team. For feature requests, submit through Help Center. For compliance questions, review Audit Log section.