# 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
```bash
npm run dev
```

### 2. Open Browser Console
Open Developer Tools in your browser and run:
```javascript
setupTestScenario()
```

This will log the test commands and URLs you need.

### 3. Create Test Event
In the browser console, run:
```javascript
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):

```javascript
// 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.