# Visitor Kiosk - Escort Handoff Mode Specification

## Overview

This document specifies the "Escort Handoff Mode" for the mobile visitor kiosk. In this mode, a staff member hands their tablet/phone to the visitor for registration, but the digital badge remains on the staff device rather than transferring to the visitor's personal phone.

## Use Case

In controlled facilities, staff may prefer to:

1. Hand their mobile device to a visitor for self-registration
2. Keep the visitor badge displayed on the staff device
3. Maintain "escort mode" where staff carries the badge throughout the visit

## User Flow

### 1. Staff Initiates Handoff

```
Staff Device (Kiosk Mode)
├── Staff taps "Register Visitor"
├── Device locks into "Handoff Mode"
│   └── Shows: "Please hand device to visitor"
└── Optional: Staff enters their ID as escort
```

### 2. Visitor Self-Registration (On Staff Device)

```
Visitor receives device
├── Fills in:
│   ├── Name (required)
│   ├── Company
│   ├── Purpose (required)
│   └── Type (Visitor, Contractor, etc.)
├── Takes selfie using front camera
├── Accepts NDA (checkbox)
└── Taps "Complete Registration"
```

### 3. Badge Display (Stays on Staff Device)

```
After successful check-in:
├── Badge displays on staff's device
├── Shows: "Return device to staff" overlay
├── QR code for security scan
├── Staff name shown as "Escort"
└── NO auto-redirect to visitor's phone
```

### Key Differences from Standard Mode

| Feature | Standard Kiosk | Escort Handoff |
|---------|---------------|----------------|
| Badge Location | Visitor's phone (via QR scan) | Staff's device |
| Escort Assignment | Optional | Automatic (logged-in staff) |
| Device Return | Not applicable | Required step |
| Badge Portability | On visitor's device | Carried by escort |

## Technical Implementation

### 1. Mode Detection

```typescript
type KioskMode = 
  | 'standard'      // Fixed tablet kiosk
  | 'escort-handoff' // Mobile escort mode
  | 'self-service';  // Visitor's own device

interface HandoffSession {
  escortId: string;      // Staff user ID
  escortName: string;    // For display
  startedAt: Date;
  deviceId?: string;     // For audit
}
```

### 2. API Changes

```typescript
// POST /api/visitors/:id/check-in
{
  escortId: string;       // Required in handoff mode
  handoffMode: boolean;   // Flag for escort mode
  ndaAccepted: boolean;
  photoUrl?: string;
}

// Response includes escortRequired: true
```

### 3. Badge Page Updates

When in escort-handoff mode, the badge page should:

- Display "Escorted by: [Staff Name]"
- Show a prominent "ESCORT REQUIRED" badge
- Add "Return Device to Staff" button after registration
- Disable "Send to My Phone" option

### 4. Staff Authentication

For staff to initiate handoff mode, they should:

- Be logged into the app on their device
- Have appropriate permissions (e.g., `can_escort_visitors`)
- Their user ID auto-populates as escort

## UI Mockup Concepts

### Handoff Initiation Screen (Staff View)

```
┌─────────────────────────────────────┐
│     777 Wolfpack Visitor Kiosk      │
│                                     │
│   ┌─────────────────────────────┐   │
│   │    📱 Escort Mode Active    │   │
│   │                             │   │
│   │   Hand this device to the   │   │
│   │   visitor for registration  │   │
│   │                             │   │
│   │   Escort: John Smith        │   │
│   │   Badge will stay on device │   │
│   │                             │   │
│   │      [Cancel Handoff]       │   │
│   └─────────────────────────────┘   │
│                                     │
└─────────────────────────────────────┘
```

### Post-Registration Screen (Visitor View on Staff Device)

```
┌─────────────────────────────────────┐
│         ✓ Registration Complete     │
│                                     │
│        [Visitor Photo]              │
│        Jane Doe                     │
│        ACME Corp                    │
│                                     │
│   ┌─────────────────────────────┐   │
│   │   🔒 ESCORT REQUIRED        │   │
│   │   Badge: V-20251211-042     │   │
│   │   Escort: John Smith        │   │
│   └─────────────────────────────┘   │
│                                     │
│   Please return this device to      │
│   your escort to complete check-in  │
│                                     │
│     [ Return to Escort View ]       │
│                                     │
└─────────────────────────────────────┘
```

## Security Considerations

1. **Session Timeout**: Handoff mode should timeout after 5 minutes of inactivity
2. **Escort Validation**: Staff must be logged in with valid credentials
3. **Audit Trail**: Log device handoffs for compliance
4. **Data Isolation**: Visitor cannot access staff's other data on device
5. **Photo Storage**: Photos stored securely, not accessible via device gallery

## Future Enhancements

1. **Geofencing**: Alert if escorted visitor moves outside allowed zones
2. **NFC Badge Tap**: Staff can tap NFC to transfer badge to facility kiosk for checkout
3. **Multi-Visitor Escort**: Staff manages multiple visitors on one device
4. **Offline Mode**: Queue registrations when network is unavailable

## Implementation Priority

| Phase | Feature | Effort |
|-------|---------|--------|
| P1 | Basic handoff mode toggle | Low |
| P1 | Escort auto-assignment | Low |
| P1 | Badge stays on device | Medium |
| P2 | "Return device" confirmation | Low |
| P2 | Session timeout | Low |
| P3 | Staff authentication | Medium |
| P3 | Geofencing | High |