# 📋 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