blackcanyontickets/reactrebuild0825/SCANNING_CONTROL_TEST.md

Scanning Control System - Testing Guide

This guide explains how to test the real-time scanning control system that allows admins to pause/resume ticket scanning across all scanner devices.

Features Implemented

✅ Event Data Fetching: Scanner fetches event document from Firestore with real-time onSnapshot listener
✅ Scanning Control: Admin can toggle scanningEnabled flag in event document
✅ Blocking Banner: Scanner shows prominent disabled banner when scanning is paused
✅ Verify Call Prevention: All scan attempts are blocked when scanningEnabled is false
✅ Real-time Updates: Changes in GateOpsPage instantly reflect in Scanner via onSnapshot
✅ UI Feedback: Clear visual indicators in both Scanner and GateOps interfaces

Test Setup

1. Start the Development Server

npm run dev

2. Open Browser Console

Open Developer Tools in your browser and run:

setupTestScenario()

This will log the test commands and URLs you need.

3. Create Test Event

In the browser console, run:

await createTestEvent()

This creates a test event with ID test-event-123 in Firestore.

Testing Real-time Updates

Open Two Browser Windows/Tabs:

1. Scanner Interface: http://localhost:5173/scan?eventId=test-event-123
2. Gate Operations: http://localhost:5173/gate-ops/test-event-123

Test Commands (Browser Console):

// Disable scanning - Scanner should show blocking banner immediately
await toggleTestEventScanning("test-event-123", false)

// Enable scanning - Scanner should return to normal immediately  
await toggleTestEventScanning("test-event-123", true)

Expected Behavior

When Scanning is Enabled:

• ✅ Scanner shows normal interface
• ✅ Camera controls are active
• ✅ QR scanning works normally
• ✅ GateOps shows "Resume Scanning" button (red)

When Scanning is Disabled:

• ✅ Scanner shows prominent red "Scanning Disabled by Admin" banner
• ✅ Camera overlay shows "Scanning Disabled" message
• ✅ All camera controls (manual entry, torch) are disabled
• ✅ Header shows "Paused by Admin" badge
• ✅ Scan attempts are blocked with vibration feedback
• ✅ GateOps shows "Pause Scanning" button (green)

Real-time Updates:

• ✅ Changes in GateOps reflect instantly in Scanner (< 1 second)
• ✅ Multiple scanner devices update simultaneously
• ✅ No page refresh required
• ✅ Works across different browser tabs/windows

Technical Implementation

Firebase Integration:

• Uses Firestore onSnapshot() for real-time listeners
• Event document path: events/{eventId}
• Field: scanningEnabled (boolean, defaults to true)

Scanner Hook Updates:

• Added event data fetching with real-time listener
• Added scanningEnabled state management
• Blocks scan processing when disabled
• Provides loading and error states

UI Components:

• ScanningDisabledBanner: Prominent blocking banner
• Camera overlay with disabled state
• Header badges for status indication
• Disabled camera controls

GateOps Integration:

• Real-time event data subscription
• Firestore document updates
• Loading states during updates
• Permission-based controls

Permissions

Only users with orgAdmin or superadmin roles can control scanning:

• Other users see "View Only - Contact Admin" message
• Button is disabled for unauthorized users

Error Handling

• Graceful fallback if event doesn't exist
• Network error handling for Firestore operations
• Loading states during operations
• Console logging for debugging

Production Considerations

✅ Security: Firestore security rules should restrict scanning control to authorized users
✅ Performance: Uses efficient onSnapshot listeners with proper cleanup
✅ UX: Clear feedback and immediate visual updates
✅ Reliability: Graceful error handling and fallback states
✅ Scalability: Works with multiple scanner devices simultaneously

---

Note: This implementation uses the actual Black Canyon Tickets Firebase project for realistic testing. The scanning control system is ready for production deployment.