Focolari-Voting-System/ai-prompts/02-frontend-plan.md

# 📋 Piano Sviluppo Frontend

## Obiettivo

Applicazione React per tablet che gestisce il flusso di accesso ai varchi votazione, con lettura badge RFID.
Ottimizzata per tablet in orizzontale.

---

## Checklist Sviluppo

### 1. Setup Progetto

- [x] Inizializzare Vite + React + TypeScript
- [x] Installare Tailwind CSS 4
- [x] Configurare `tsconfig.json`
- [x] Configurare `vite.config.ts` con proxy API
- [x] Configurare `.gitignore`
- [x] Path relativi per build (base: './')
- [x] Output build in `frontend/dist/`
- [x] Favicon con logo Focolari

### 2. Design System

- [x] Configurare colori custom in Tailwind
    - [x] `focolare-blue: #0072CE`
    - [x] `focolare-orange: #F5A623`
    - [x] `focolare-yellow: #FFD700`
- [x] Stili globali in `index.css`
- [x] Animazioni custom (fade-in, slide-up, pulse-error, blink)
- [x] Classe `.glass` per effetto glassmorphism

### 3. Tipi TypeScript (`types/index.ts`)

- [x] `RoomInfo` - info sala + **server_start_time**
- [x] `User` - dati utente
- [x] `LoginRequest/Response` (senza token)
- [x] `EntryRequest/Response` (SENZA welcome_message)
- [x] `AppState` - stati applicazione
- [x] `ValidatorSession` - sessione validatore (badge, password, serverStartTime)
- [x] `RFIDScannerState` - stato scanner
- [x] `RFIDScanResult` - risultato scan

### 4. API Service (`services/api.ts`)

- [x] Classe `ApiError` custom
- [x] Funzione `apiFetch` generica con error handling
- [x] `getRoomInfo()` - GET /info-room
- [x] `loginValidator()` - POST /login-validate
- [x] `getUserByBadge()` - GET /anagrafica/{badge}
- [x] `requestEntry()` - POST /entry-request
- [x] Logging con prefisso `[API]`
- [x] Path relativi (proxy Vite in dev, stesso server in prod)

### 5. Hook RFID Scanner (`hooks/useRFIDScanner.ts`)

- [x] Supporto pattern multipli (US: `;?`, IT: `ò_`)
- [x] Rilevamento automatico pattern in uso
- [x] Gestione Enter post-completamento
- [x] Timeout 2.5s per scansioni accidentali
- [x] ESC annulla scansione in corso
- [x] Logging avanzato con prefisso `[RFID]`
- [x] Export `keyLog` per debug

### 6. Componenti UI (`components/`)

- [x] `Logo.tsx` - logo Focolari
- [x] `Button.tsx` - varianti primary/secondary/danger
- [x] `Input.tsx` - campo input styled + **toggle password visibility**
- [x] `Modal.tsx` - modale base
- [x] `RFIDStatus.tsx` - indicatore stato scanner
- [x] `UserCard.tsx` - card utente con foto e ruolo
- [x] `CountdownTimer.tsx` - timer con progress bar
- [x] `WelcomeCarousel.tsx` - carosello messaggi multilingua con **animazione smooth sliding**
- [x] `NumLockBanner.tsx` - avviso NumLock per desktop

### 7. Schermate (`screens/`)

- [x] `LoadingScreen.tsx` - caricamento iniziale + ping automatico
- [x] `ValidatorLoginScreen.tsx` - attesa badge + password + NumLockBanner
- [x] `ActiveGateScreen.tsx` - varco attivo:
    - [x] Card utente (layout largo per tablet)
    - [x] **Schermata "badge non trovato"** con countdown barra visiva (30s)
    - [x] **Pulsante "Annulla" nella schermata badge non trovato**
    - [x] **Badge diverso durante errore "non trovato" → ricarica nuovo utente/errore**
    - [x] **Notifica badge validatore ignorato**
    - [x] NumLockBanner
- [x] `SuccessModal.tsx` - conferma ingresso con carosello:
    - [x] **Carosello fullwidth** (nessun troncamento testo)
    - [x] **Scorrimento lento** (più rilassato, meno ansioso)
    - [x] **Durata aumentata 8s**
- [x] `ErrorModal.tsx` - errore fullscreen
- [x] `DebugScreen.tsx` - pagina diagnostica RFID

### 8. State Machine (`App.tsx`)

- [x] Stati applicazione gestiti
- [x] Integrazione `useRFIDScanner`
- [x] Gestione sessione validatore (localStorage)
- [x] **Qualsiasi badge può essere validatore** (verificato con password)
- [x] Password salvata in sessione per conferme ingresso
- [x] **Invalidazione sessione se server riparte** (serverStartTime)
- [x] **Polling periodico (30s) per verificare server restart**
- [x] Timeout sessione 30 minuti
- [x] Timeout utente 60 secondi
- [x] **Timeout badge non trovato 30 secondi**
- [x] **Ignora stesso badge passato più volte** (no ricaricamento)
- [x] Cambio rapido badge partecipante
- [x] **Badge durante success modal chiude modal e carica nuovo utente** (fix dipendenze useCallback)
- [x] Conferma con badge validatore (quello della sessione)
- [x] **Notifica se badge validatore rippassato senza utente**
- [x] Logging transizioni con prefisso `[FLOW]`

### 9. Modale Successo - Carosello Internazionale

- [x] Componente `WelcomeCarousel.tsx`
- [x] 10 lingue supportate
- [x] **Animazione smooth sliding** (slide up/down)
- [x] Scorrimento automatico lento (più rilassato)
- [x] Modale fullscreen verde
- [x] **Contenitore fullwidth** (nessun troncamento testo lungo)
- [x] **Durata totale: 8 secondi**

### 10. Debug & Diagnostica

- [x] Pagina `/debug` dedicata
- [x] Logging console strutturato `[RFID]`, `[FLOW]`, `[API]`

### 11. Routing

- [x] React Router
- [x] Route principale `/`
- [x] Route debug `/debug`

---

## Badge di Test

| Badge        | Nome           | Ruolo     | Ammesso       |
|--------------|----------------|-----------|---------------|
| `0008988288` | Marco Bianchi  | Convocato | ✅ Sì          |
| `0007399575` | Laura Rossi    | Invitato  | ✅ Sì          |
| `0000514162` | Giuseppe Verdi | Tecnico   | ❌ No          |
| `0006478281` | -              | -         | ⚠️ Non nel DB |

---

## 🧪 Test Automatici

### Setup Test
- [x] Vitest configurato
- [x] React Testing Library installata
- [x] Setup file con mock globali
- [x] Script npm per test (`npm run test`, `npm run test:run`)
- [x] Comando dev.sh per test (`./dev.sh test`, `./dev.sh test:watch`)

### Test useRFIDScanner (20 test) ✅
- [x] Rilevamento pattern US (`;` → `?`)
- [x] Rilevamento pattern IT (`ò` → `_`)
- [x] Timeout scansione incompleta (2.5s)
- [x] ESC annulla scansione
- [x] Enter post-completamento ignorato
- [x] Cambio pattern durante scansione
- [x] Codici vuoti scartati
- [x] Reset manuale
- [x] Key log limitato a 20 entries
- [x] Stato disabled

### Test API Service (12 test) ✅
- [x] getRoomInfo - success
- [x] getRoomInfo - server error
- [x] getRoomInfo - connection error
- [x] loginValidator - success
- [x] loginValidator - wrong password
- [x] loginValidator - badge as string (leading zeros)
- [x] getUserByBadge - ammesso
- [x] getUserByBadge - non ammesso con warning
- [x] getUserByBadge - 404 badge non trovato
- [x] requestEntry - success
- [x] requestEntry - non ammesso
- [x] ApiError properties

### Test UserCard (9 test) ✅
- [x] Render nome utente
- [x] Render badge code
- [x] Render ruolo
- [x] Status AMMESSO visibile
- [x] Status NON AMMESSO visibile
- [x] Warning message visibile
- [x] Alt text foto corretto
- [x] Border success per ammesso
- [x] Border error per non ammesso

### Test Configurazione (14 test) ✅
- [x] Session storage key corretto
- [x] Session structure corretta
- [x] Session timeout 30 minuti
- [x] User display timeout 60 secondi
- [x] Badge not found timeout 30 secondi
- [x] Invalidazione sessione su server restart
- [x] Sessione valida con stesso server_start_time
- [x] Badge trattato come stringa
- [x] Comparazione badge esatta
- [x] Ruoli supportati (Convocato, Invitato, Tecnico, Staff)
- [x] Polling interval 30 secondi
- [x] Pattern US configurato
- [x] Pattern IT configurato
- [x] Scan timeout 2.5 secondi

### Totale: 56 test ✅

---

## 🎭 Test E2E (Playwright)

Test End-to-End che aprono un browser reale e verificano i flussi completi.

### Setup E2E
- [x] Playwright installato
- [x] Configurazione `playwright.config.ts`
- [x] Cartella `e2e/` per test
- [x] Script npm per E2E (`npm run test:e2e`, `npm run test:e2e:ui`)
- [x] Comandi dev.sh (`./dev.sh test:e2e`, `./dev.sh test:e2e:ui`)

### Test E2E Implementati (`e2e/app.spec.ts`)

**Flusso Validatore:**
- [x] Mostra schermata attesa badge validatore
- [x] Mostra input password dopo scansione badge
- [x] Login con password corretta porta a varco attivo
- [x] Login con password errata mostra errore
- [x] Pulsante annulla torna a attesa badge

**Flusso Partecipante:**
- [x] Badge ammesso mostra card verde
- [x] Badge non ammesso mostra card rossa
- [x] Badge non trovato mostra errore con countdown
- [x] Stesso badge passato più volte non ricarica
- [x] Badge diverso sostituisce utente corrente

**Conferma Ingresso:**
- [x] Badge validatore su utente ammesso mostra success modal
- [x] Badge validatore su utente NON ammesso mostra warning

**Sicurezza Backend:**
- [x] **Backend blocca non-ammesso → frontend mostra errore** (intercept API)

**Debug & Session:**
- [x] Pagina debug accessibile
- [x] Debug mostra log tastiera
- [x] Logout cancella sessione
- [x] Refresh mantiene sessione

### Comandi E2E

```bash
./dev.sh test:e2e        # Esegue test E2E (headless)
./dev.sh test:e2e:ui     # Apre Playwright UI per debug
npm run test:e2e:headed  # Test con browser visibile
npm run test:e2e:report  # Mostra report HTML
```

---

## ✅ FRONTEND COMPLETATO

Tutte le funzionalità e i test sono stati implementati.