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

---

🧪 TODO: Test Automatici

Test da Implementare

• Test RFID Scanner:

  • Rilevamento pattern US (; → ?)
  • Rilevamento pattern IT (ò → _)
  • Timeout scansione incompleta
  • ESC annulla scansione
  • Enter post-completamento ignorato

• Test Flow Validatore:

  • Login con password corretta
  • Login con password errata
  • Sessione persistente in localStorage
  • Invalidazione sessione al riavvio server
  • Logout manuale

• Test Flow Partecipante:

  • Badge trovato ammesso → mostra card verde
  • Badge trovato non ammesso → mostra card rossa + warning
  • Badge non trovato → mostra schermata errore con countdown
  • Stesso badge passato più volte → ignorato
  • Badge diverso passato → cambia utente visualizzato
  • Timeout 60s → torna in attesa

• Test Conferma Ingresso:

  • Badge validatore su utente ammesso → success modal
  • Badge validatore su utente NON ammesso → notifica ignorato
  • Badge validatore senza utente → notifica ignorato
  • ⚠️ IMPORTANTE: Simulare bug che bypassa frontend → backend DEVE bloccare

• Test Success Modal:

  • Carosello scorre tutte le lingue
  • Durata corretta (8s)
  • Badge durante modal → chiude modal e carica nuovo utente

---

✅ FRONTEND COMPLETATO

Tutte le funzionalità principali sono state implementate. Rimangono da sviluppare i test automatici.