# 🗳️ Focolari Voting System - Welcome Agent

## Panoramica Progetto

Sistema di controllo accessi per le assemblee di voto del **Movimento dei Focolari**.
Applicazione web ottimizzata per **tablet in orizzontale** che gestisce i varchi d'ingresso alle sale votazione tramite
**lettori RFID USB** (emulano tastiera).

---

## Stack Tecnologico

### Backend Mock

- **Python 3.11+** con **FastAPI**
- **Pydantic** per validazione dati
- **Uvicorn** come server ASGI
- **Pipenv** per gestione dipendenze

### Frontend

- **React 18** + **TypeScript**
- **Vite** come build tool
- **Tailwind CSS 4** per styling
- **React Router** per navigazione

---

## Struttura Progetto

```
VotoFocolari/
├── dev.sh                    # Script di sviluppo (install, dev, server, ...)
├── README.md
├── ai-prompts/               # Documentazione sviluppo
│   ├── 00-welcome-agent.md   # Questo file
│   ├── 01-backend-plan.md    # Piano backend
│   └── 02-frontend-plan.md   # Piano frontend
├── backend-mock/
│   ├── main.py               # Entry point con argparse
│   ├── Pipfile               # Dipendenze Python
│   ├── API_SPECIFICATION.md  # Specifiche per backend reale
│   ├── api/routes.py         # Endpoint API
│   ├── schemas/models.py     # Modelli Pydantic
│   └── data/
│       ├── users_default.json
│       └── users_test.json
└── frontend/
    ├── package.json
    ├── vite.config.ts
    └── src/
        ├── App.tsx           # State machine principale
        ├── hooks/            # useRFIDScanner
        ├── components/       # UI components
        ├── screens/          # Schermate
        ├── services/         # API client
        └── types/            # TypeScript types
```

---

## Funzionalità Principali

### Flusso Utente

1. **Login Validatore**: Passa badge + inserisci password → Sessione 30 min
2. **Attesa Partecipante**: Schermata grande "Passa il badge"
3. **Visualizzazione Utente**: Card con foto, nome, ruolo, stato ammissione
4. **Conferma Ingresso**: Validatore ripassa il badge → Carosello benvenuto multilingua (8s)

### Gestione RFID

- **Multi-pattern**: Supporta layout tastiera US (`;?`) e IT (`ò_`), con `\n` dopo fine sequenza
- **Timeout 2.5s**: Per scansioni accidentali
- **ESC annulla**: Scansione in corso
- **Enter handling**: Gestito automaticamente
- **Stesso badge ignorato**: Se passato più volte di seguito

### Sicurezza Sessioni

- Sessione salvata in localStorage
- **Invalidazione automatica** se il server riparte
- Timeout 30 minuti

---

## Comandi Rapidi

```bash
# Setup iniziale
./dev.sh install

# Sviluppo (hot reload)
./dev.sh dev
# Frontend: http://localhost:5173
# Backend: http://localhost:8000

# Produzione locale
./dev.sh server
# App completa: http://localhost:8000

# Debug RFID
# Vai a http://localhost:8000/debug
```

---

## Badge di Test

| Badge        | Nome           | Ruolo   | Ammesso       |
|--------------|----------------|---------|---------------|
| `0008988288` | Marco Bianchi  | Votante | ✅             |
| `0007399575` | Laura Rossi    | Votante | ✅             |
| `0000514162` | Giuseppe Verdi | Tecnico | ❌             |
| `0006478281` | -              | -       | ⚠️ Non nel DB |

**Password validatore:** `focolari`

---

## Dove Trovare Cosa

| Cosa cerchi                | Dove guardare                          |
|----------------------------|----------------------------------------|
| Logica flusso applicazione | `frontend/src/App.tsx`                 |
| Hook lettura RFID          | `frontend/src/hooks/useRFIDScanner.ts` |
| Chiamate API               | `frontend/src/services/api.ts`         |
| Endpoint backend           | `backend-mock/api/routes.py`           |
| Dati mock utenti           | `backend-mock/data/users_default.json` |
| Specifiche API produzione  | `backend-mock/API_SPECIFICATION.md`    |
| Configurazione Vite        | `frontend/vite.config.ts`              |

---

## Note Importanti

1. **Layout Tastiera**: Il lettore RFID potrebbe inviare caratteri diversi in base al layout OS. La pagina `/debug`
   aiuta a diagnosticare.

2. **Server Restart**: Quando il server riparte, tutte le sessioni frontend vengono invalidate (controllato via
   `server_start_time`).

3. **Badge Validatore**: Qualsiasi badge può diventare validatore se la password è corretta. Il badge viene memorizzato
   nella sessione.

4. **NumLock**: Su desktop, viene mostrato un banner per ricordare di attivare NumLock.

5. **Badge Duplicati**: Se lo stesso badge viene passato più volte di seguito, viene ignorato (no ricaricamento).

6. **Success Modal Interrompibile**: Se durante il carosello di benvenuto si passa un nuovo badge, la modal si chiude e viene caricato subito il nuovo utente.

---

## TODO (da concordare con committenti)

- [ ] Verificare se il badge validatore debba essere validato anche lato server
- [ ] Test automatici E2E per regression detection