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. Include sistema di test automatici per validazione e regression detection.

---

Checklist Sviluppo

1. Setup Progetto

• Inizializzare Vite + React + TypeScript
• Installare Tailwind CSS 4
• Configurare tsconfig.json
• Configurare vite.config.ts
• Configurare .gitignore

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
• User - dati utente
• LoginRequest/Response
• EntryRequest/Response (SENZA welcome_message)
• AppState - stati applicazione
• ValidatorSession - sessione validatore
• RFIDScannerState - stato scanner
• RFIDScanResult - risultato scan
• DA FARE: Aggiornare EntryResponse rimuovendo welcome_message

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
• DA FARE: Logging con prefisso [API]

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

Implementazione Base (v1)

• Listener keydown globale
• Stati: idle → scanning → idle
• Singolo pattern (; / ?)
• Timeout sicurezza (3s)
• preventDefault durante scan
• Callback onScan, onTimeout, onScanStart

⚠️ AGGIORNAMENTO RICHIESTO (v2) - Multi-Pattern

• Supporto pattern multipli (US, IT, altri)

  const VALID_PATTERNS = [
    { start: ';', end: '?' }, // Layout US
    { start: 'ò', end: '_' }, // Layout IT
  ];
  

• Rilevamento automatico pattern in uso
• Memorizzazione pattern attivo durante scan
• Validazione end solo per pattern corretto
• Logging avanzato con prefisso [RFID]
• Esportare info pattern attivo per debug page

6. Componenti UI (components/)

• Logo.tsx - logo Focolari
• Button.tsx - varianti primary/secondary/danger
• Input.tsx - campo input styled
• Modal.tsx - modale base
• RFIDStatus.tsx - indicatore stato scanner
• UserCard.tsx - card utente con foto e ruolo
• CountdownTimer.tsx - timer con progress bar
• index.ts - barrel export
• DA FARE: WelcomeCarousel.tsx - carosello messaggi multilingua

7. Schermate (screens/)

• LoadingScreen.tsx - caricamento iniziale
• ValidatorLoginScreen.tsx - attesa badge + password
• ActiveGateScreen.tsx - varco attivo + scheda utente
• SuccessModal.tsx - conferma ingresso fullscreen
• ErrorModal.tsx - errore fullscreen
• index.ts - barrel export
• DA FARE: DebugScreen.tsx - pagina diagnostica RFID

8. State Machine (App.tsx)

• Stati applicazione gestiti
• Integrazione useRFIDScanner
• Gestione sessione validatore (localStorage)
• Timeout sessione 30 minuti
• Timeout utente 60 secondi
• Cambio rapido badge partecipante
• Conferma con badge validatore
• DA FARE: Logging transizioni con prefisso [FLOW]

9. Modale Successo - Carosello Internazionale

⚠️ MODIFICA RICHIESTA

Il backend NON restituisce più messaggi multilingua. Il frontend gestisce autonomamente la visualizzazione con un carosello automatico.

Specifiche:

• Creare componente WelcomeCarousel.tsx
• Lista messaggi di benvenuto in diverse lingue:

  const WELCOME_MESSAGES = [
    { lang: 'it', text: 'Benvenuto!' },
    { lang: 'en', text: 'Welcome!' },
    { lang: 'fr', text: 'Bienvenue!' },
    { lang: 'de', text: 'Willkommen!' },
    { lang: 'es', text: 'Bienvenido!' },
    { lang: 'pt', text: 'Bem-vindo!' },
    { lang: 'zh', text: '欢迎!' },
    { lang: 'ja', text: 'ようこそ!' },
  ];
  

• Scorrimento automatico (es. ogni 2 secondi)
• Animazione transizione fluida (fade o slide)
• Modale fullscreen verde con carosello al centro
• Durata totale modale: 5 secondi

10. Debug & Diagnostica

⚠️ DA IMPLEMENTARE

• Pagina /debug dedicata
  • Log ultimi 20 tasti premuti (key + code)
  • Stato scanner real-time (idle/scanning)
  • Buffer corrente
  • Pattern attivo (US/IT/...)
  • Ultimo codice rilevato
  • Timestamp eventi
• Link/pulsante nascosto per accesso debug (es. logo cliccabile 5 volte)
• Logging console strutturato:
  • [RFID] - eventi scanner
  • [FLOW] - transizioni stato
  • [API] - chiamate HTTP

11. Routing

• Installare React Router
• Route principale /
• Route debug /debug

12. Test Automatici (E2E / Use Case Validation)

⚠️ NUOVA SEZIONE

Sistema di test per validazione formale dei flussi e regression detection.

Struttura:

frontend/
├── src/
│   └── tests/
│       ├── usecase/
│       │   ├── UC01_ValidatorLogin.test.ts
│       │   ├── UC02_ParticipantAccess.test.ts
│       │   ├── UC03_DeniedAccess.test.ts
│       │   ├── UC04_SessionTimeout.test.ts
│       │   ├── UC05_QuickBadgeSwitch.test.ts
│       │   └── UC06_RFIDMultiPattern.test.ts
│       └── helpers/
│           ├── mockRFID.ts       # Simulatore eventi tastiera RFID
│           └── testUtils.ts      # Utility comuni

Use Case da Testare:

• UC01 - Login Validatore

  • Simula badge validatore (;999999?)
  • Inserisce password corretta
  • Verifica transizione a stato gate-active
  • Verifica sessione salvata in localStorage

• UC02 - Accesso Partecipante Ammesso

  • Da stato gate-active
  • Simula badge partecipante ammesso
  • Verifica caricamento dati utente
  • Simula badge validatore per conferma
  • Verifica modale successo con carosello
  • Verifica ritorno a gate-active

• UC03 - Accesso Negato

  • Simula badge partecipante NON ammesso
  • Verifica visualizzazione warning rosso
  • Verifica che conferma validatore sia bloccata
  • Verifica pulsante annulla funzionante

• UC04 - Timeout Sessione

  • Verifica scadenza sessione 30 minuti
  • Verifica redirect a login validatore
  • Verifica pulizia localStorage

• UC05 - Cambio Rapido Badge

  • Con utente a schermo
  • Simula nuovo badge partecipante
  • Verifica sostituzione immediata dati

• UC06 - Pattern RFID Multipli

  • Testa pattern US (; / ?)
  • Testa pattern IT (ò / _)
  • Verifica stesso risultato finale

Dipendenze Test:

npm install -D vitest @testing-library/react @testing-library/user-event jsdom

Script npm:

{
  "scripts": {
    "test": "vitest",
    "test:ui": "vitest --ui",
    "test:coverage": "vitest --coverage"
  }
}

---

Correzioni Necessarie

Hook RFID - Da Aggiornare

Il file useRFIDScanner.ts attualmente supporta solo il pattern US (; / ?).

Modifiche richieste:

1. Aggiungere costante VALID_PATTERNS con pattern multipli
2. Modificare logica handleKeyDown per:
   • Riconoscere qualsiasi start sentinel
   • Memorizzare quale pattern è in uso
   • Validare solo con l'end corrispondente
3. Aggiungere stato activePattern per debug
4. Migliorare logging

Success Modal - Da Aggiornare

Attualmente usa welcome_message dal backend.

Modifiche richieste:

1. Rimuovere dipendenza da welcome_message API
2. Implementare WelcomeCarousel con messaggi hardcoded
3. Carosello auto-scroll ogni 2 secondi
4. Animazioni fluide tra messaggi

Logging Console

Attualmente i log usano messaggi generici. Aggiornare tutti i console.log con prefissi standardizzati.

---

Dipendenze da Aggiungere

# Routing
npm install react-router-dom

# Testing
npm install -D vitest @testing-library/react @testing-library/user-event jsdom @vitest/ui @vitest/coverage-v8

---

Comandi Esecuzione

cd frontend
npm install
npm run dev          # Sviluppo
npm run build        # Build produzione
npm run test         # Test suite
npm run test:ui      # Test con UI interattiva
npm run test:coverage # Coverage report

---

Note UI/UX

• Font grandi per leggibilità tablet
• Pulsanti touch-friendly (min 48px)
• Feedback visivo immediato su azioni
• Animazioni fluide ma non invasive
• Supporto landscape e portrait
• Carosello benvenuto: transizioni smooth, leggibilità massima