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

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

2. Design System

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

3. Tipi TypeScript (types/index.ts)

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

4. API Service (services/api.ts)

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

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

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

6. Componenti UI (components/)

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

7. Schermate (screens/)

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

8. State Machine (App.tsx)

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

9. Modale Successo - Carosello Internazionale

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

10. Debug & Diagnostica

• Pagina /debug dedicata
• Logging console strutturato [RFID], [FLOW], [API]

11. Routing

• React Router
• Route principale /
• 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

• Vitest configurato
• React Testing Library installata
• Setup file con mock globali
• Script npm per test (npm run test, npm run test:run)
• Comando dev.sh per test (./dev.sh test, ./dev.sh test:watch)

Test useRFIDScanner (20 test) ✅

• Rilevamento pattern US (; → ?)
• Rilevamento pattern IT (ò → _)
• Timeout scansione incompleta (2.5s)
• ESC annulla scansione
• Enter post-completamento ignorato
• Cambio pattern durante scansione
• Codici vuoti scartati
• Reset manuale
• Key log limitato a 20 entries
• Stato disabled

Test API Service (12 test) ✅

• getRoomInfo - success
• getRoomInfo - server error
• getRoomInfo - connection error
• loginValidator - success
• loginValidator - wrong password
• loginValidator - badge as string (leading zeros)
• getUserByBadge - ammesso
• getUserByBadge - non ammesso con warning
• getUserByBadge - 404 badge non trovato
• requestEntry - success
• requestEntry - non ammesso
• ApiError properties

Test UserCard (9 test) ✅

• Render nome utente
• Render badge code
• Render ruolo
• Status AMMESSO visibile
• Status NON AMMESSO visibile
• Warning message visibile
• Alt text foto corretto
• Border success per ammesso
• Border error per non ammesso

Test Configurazione (14 test) ✅

• Session storage key corretto
• Session structure corretta
• Session timeout 30 minuti
• User display timeout 60 secondi
• Badge not found timeout 30 secondi
• Invalidazione sessione su server restart
• Sessione valida con stesso server_start_time
• Badge trattato come stringa
• Comparazione badge esatta
• Ruoli supportati (Convocato, Invitato, Tecnico, Staff)
• Polling interval 30 secondi
• Pattern US configurato
• Pattern IT configurato
• 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

• Playwright installato
• Configurazione playwright.config.ts
• Cartella e2e/ per test
• Script npm per E2E (npm run test:e2e, npm run test:e2e:ui)
• Comandi dev.sh (./dev.sh test:e2e, ./dev.sh test:e2e:ui)

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

Flusso Validatore:

• Mostra schermata attesa badge validatore
• Mostra input password dopo scansione badge
• Login con password corretta porta a varco attivo
• Login con password errata mostra errore
• Pulsante annulla torna a attesa badge

Flusso Partecipante:

• Badge ammesso mostra card verde
• Badge non ammesso mostra card rossa
• Badge non trovato mostra errore con countdown
• Stesso badge passato più volte non ricarica
• Badge diverso sostituisce utente corrente

Conferma Ingresso:

• Badge validatore su utente ammesso mostra success modal
• Badge validatore su utente NON ammesso mostra warning

Sicurezza Backend:

• Backend blocca non-ammesso → frontend mostra errore (intercept API)

Debug & Session:

• Pagina debug accessibile
• Debug mostra log tastiera
• Logout cancella sessione
• Refresh mantiene sessione

Comandi E2E

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