feat: setup iniziale sistema controllo accessi Focolari

Struttura progetto: - Backend mock Python (FastAPI) con API per gestione varchi - Frontend React + TypeScript + Vite + Tailwind CSS - Documentazione e piani di sviluppo Backend (backend-mock/): - API REST: /info-room, /login-validate, /anagrafica, /entry-request - Dati mock: 7 utenti, validatore (999999/focolari) - CORS abilitato, docs OpenAPI automatiche - Configurazione pipenv per ambiente virtuale Frontend (frontend/): - State machine completa per flusso accesso varco - Hook useRFIDScanner per lettura badge (pattern singolo) - Componenti UI: Logo, Button, Input, Modal, UserCard, Timer - Schermate: Loading, Login, ActiveGate, Success/Error Modal - Design system con colori Focolari - Ottimizzato per tablet touch Documentazione (ai-prompts/): - Welcome guide per futuri agenti - Piano sviluppo backend e frontend con checklist DA COMPLETARE: - Hook RFID multi-pattern (US/IT/altri layout tastiera) - Pagina /debug per diagnostica in loco - Logging console strutturato
2026-01-17 18:20:55 +01:00
commit 21b509c6ba
40 changed files with 7453 additions and 0 deletions
--- a/ai-prompts/02-frontend-plan.md
+++ b/ai-prompts/02-frontend-plan.md
@@ -0,0 +1,305 @@
+# 📋 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
+
+- [x] Inizializzare Vite + React + TypeScript
+- [x] Installare Tailwind CSS 4
+- [x] Configurare `tsconfig.json`
+- [x] Configurare `vite.config.ts`
+- [x] Configurare `.gitignore`
+
+### 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
+- [x] `User` - dati utente
+- [x] `LoginRequest/Response`
+- [x] `EntryRequest/Response` (SENZA welcome_message)
+- [x] `AppState` - stati applicazione
+- [x] `ValidatorSession` - sessione validatore
+- [x] `RFIDScannerState` - stato scanner
+- [x] `RFIDScanResult` - risultato scan
+- [ ] **DA FARE:** Aggiornare `EntryResponse` rimuovendo `welcome_message`
+
+### 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
+- [ ] **DA FARE:** Logging con prefisso `[API]`
+
+### 5. Hook RFID Scanner (`hooks/useRFIDScanner.ts`)
+
+#### Implementazione Base (v1)
+
+- [x] Listener `keydown` globale
+- [x] Stati: idle → scanning → idle
+- [x] Singolo pattern (`;` / `?`)
+- [x] Timeout sicurezza (3s)
+- [x] `preventDefault` durante scan
+- [x] Callback `onScan`, `onTimeout`, `onScanStart`
+
+#### ⚠️ AGGIORNAMENTO RICHIESTO (v2) - Multi-Pattern
+
+- [ ] Supporto pattern multipli (US, IT, altri)
+  ```typescript
+  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/`)
+
+- [x] `Logo.tsx` - logo Focolari
+- [x] `Button.tsx` - varianti primary/secondary/danger
+- [x] `Input.tsx` - campo input styled
+- [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] `index.ts` - barrel export
+- [ ] **DA FARE:** `WelcomeCarousel.tsx` - carosello messaggi multilingua
+
+### 7. Schermate (`screens/`)
+
+- [x] `LoadingScreen.tsx` - caricamento iniziale
+- [x] `ValidatorLoginScreen.tsx` - attesa badge + password
+- [x] `ActiveGateScreen.tsx` - varco attivo + scheda utente
+- [x] `SuccessModal.tsx` - conferma ingresso fullscreen
+- [x] `ErrorModal.tsx` - errore fullscreen
+- [x] `index.ts` - barrel export
+- [ ] **DA FARE:** `DebugScreen.tsx` - pagina diagnostica RFID
+
+### 8. State Machine (`App.tsx`)
+
+- [x] Stati applicazione gestiti
+- [x] Integrazione `useRFIDScanner`
+- [x] Gestione sessione validatore (localStorage)
+- [x] Timeout sessione 30 minuti
+- [x] Timeout utente 60 secondi
+- [x] Cambio rapido badge partecipante
+- [x] 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:
+  ```typescript
+  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:**
+```bash
+npm install -D vitest @testing-library/react @testing-library/user-event jsdom
+```
+
+**Script npm:**
+```json
+{
+  "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
+
+```bash
+# 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
+
+```bash
+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