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
• EntryRequest/Response (SENZA welcome_message)
• AppState - stati applicazione
• ValidatorSession - sessione validatore + 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
• 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 30s
  • Notifica badge validatore ignorato
  • NumLockBanner
• SuccessModal.tsx - conferma ingresso con carosello
• 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)
• Timeout sessione 30 minuti
• Timeout utente 60 secondi
• Timeout badge non trovato 30 secondi
• Cambio rapido badge partecipante
• 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
• Scorrimento automatico ogni 800ms
• Modale fullscreen verde
• Durata totale: 5 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	Votante	✅ Sì
0007399575	Laura Rossi	Votante	✅ Sì
0000514162	Giuseppe Verdi	Tecnico	❌ No
0006478281	-	-	⚠️ Non nel DB

---

✅ FRONTEND COMPLETATO