# 🎯 Focolari Voting System - Guida Agente

## Panoramica Progetto

**Nome:** Sistema Controllo Accessi "Focolari Voting System"  
**Committente:** Movimento dei Focolari  
**Scopo:** Gestione dei varchi di accesso per le assemblee di voto del Movimento.

### Contesto d'Uso

Il sistema funziona su **tablet Android** (via browser Chrome) posizionati ai varchi d'ingresso delle sale votazione. Ogni tablet è collegato a un **lettore RFID USB** che emula tastiera.

---

## 🏗️ Architettura

```
VotoFocolari/
├── ai-prompts/           # Documentazione e piani di sviluppo
├── backend-mock/         # Python FastAPI (server mock)
│   ├── main.py           # Entry point con argparse
│   ├── Pipfile           # Dipendenze pipenv
│   ├── api/              # Routes FastAPI
│   ├── schemas/          # Modelli Pydantic
│   └── data/             # Dataset JSON (default, test)
└── frontend/             # React + TypeScript + Vite + Tailwind
    └── src/
        ├── App.tsx           # State machine principale
        ├── hooks/            # Custom hooks (RFID scanner)
        ├── components/       # UI components
        ├── screens/          # Schermate complete
        ├── services/         # API layer
        ├── types/            # TypeScript definitions
        └── tests/            # Test automatici use case
```

---

## 🔧 Stack Tecnologico

### Backend Mock
- **Python 3.10+**
- **FastAPI** - Framework web asincrono
- **Uvicorn** - ASGI server
- **Pydantic** - Validazione dati
- **pipenv** - Gestione ambiente virtuale
- **argparse** - Parametri CLI (porta, dataset)

### Frontend
- **React 19** - UI Library
- **TypeScript 5.9** - Type safety
- **Vite 7** - Build tool
- **Tailwind CSS 4** - Styling utility-first
- **React Router** - Routing (/, /debug)
- **Vitest** - Testing framework
- **Design:** Ottimizzato per touch tablet

---

## 🎨 Design System

| Colore | Hex | Uso |
|--------|-----|-----|
| Blu Istituzionale | `#0072CE` | Colore primario, brand |
| Arancio Accento | `#F5A623` | Azioni secondarie |
| Giallo | `#FFD700` | Evidenze |
| Verde Success | `#22C55E` | Conferme, ammesso |
| Rosso Error | `#EF4444` | Errori, non ammesso |

---

## 📟 Logica RFID (CRITICA)

Il lettore RFID simula una tastiera. **Non possiamo distinguerlo dalla digitazione umana** in base alla velocità.

### Protocollo
- **Formato:** `<start_sentinel><codice><end_sentinel>`
- **Esempio US:** `;00012345?`
- **Esempio IT:** `ò00012345_`

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

### Strategia
1. Ascolto globale `keydown`
2. Se ricevo un carattere `start` → avvio buffer + timeout (2.5s)
3. Accumulo caratteri nel buffer
4. Se ricevo il corretto `end` → emetto codice pulito
5. Se timeout scade → scarto buffer

---

## 🔄 State Machine Applicativa

```
LOADING → WAITING_VALIDATOR → [badge validatore]
                            → VALIDATOR_PASSWORD → [password OK]
                            → GATE_ACTIVE → [badge partecipante]
                            → SHOWING_USER → [badge validatore]
                            → SUCCESS_MODAL (5s, carosello multilingua) → GATE_ACTIVE
```

---

## 🌍 Messaggi Benvenuto (Frontend)

Il backend risponde in modo **asettico** (solo `success: true`).
Il frontend mostra un **carosello automatico** di messaggi multilingua:

- Italiano, English, Français, Deutsch, Español, Português, 中文, 日本語

Scorrimento ogni ~2 secondi, durata modale 5 secondi.

---

## 📁 File Chiave

| File | Descrizione |
|------|-------------|
| `backend-mock/main.py` | Entry point con argparse |
| `backend-mock/api/routes.py` | Definizione endpoint |
| `backend-mock/schemas/models.py` | Modelli Pydantic |
| `backend-mock/data/*.json` | Dataset utenti |
| `frontend/src/hooks/useRFIDScanner.ts` | Cuore del sistema - gestione lettore |
| `frontend/src/App.tsx` | State machine e orchestrazione |
| `frontend/src/components/WelcomeCarousel.tsx` | Carosello multilingua |
| `frontend/src/screens/DebugScreen.tsx` | Diagnostica RFID |
| `frontend/src/tests/` | Test automatici use case |

---

## 🚀 Quick Start

### Backend
```bash
cd backend-mock
pipenv install
pipenv run python main.py                    # Default
pipenv run python main.py -p 9000            # Porta custom
pipenv run python main.py -d data/test.json  # Dataset test
```

### Frontend
```bash
cd frontend
npm install
npm run dev           # Sviluppo
npm run test          # Test suite
npm run test:ui       # Test con UI
```

---

## 🧪 Test Automatici

Suite di test per validazione use case:

| Test | Descrizione |
|------|-------------|
| UC01 | Login validatore |
| UC02 | Accesso partecipante ammesso |
| UC03 | Accesso negato |
| UC04 | Timeout sessione |
| UC05 | Cambio rapido badge |
| UC06 | Pattern RFID multipli |

---

## 🔍 Debug

### Console Browser
Tutti i log sono prefissati:
- `[RFID]` - Eventi lettore badge
- `[FLOW]` - Transizioni stato
- `[API]` - Chiamate HTTP

### Pagina Debug (`/debug`)
Accesso: logo cliccabile 5 volte.
Mostra in tempo reale:
- Ultimi 20 tasti premuti
- Stato scanner (idle/scanning)
- Buffer corrente
- Pattern attivo

---

## ⚠️ Note Importanti

1. **Badge Validatore:** `999999` con password `focolari`
2. **Sessione:** 30 minuti di timeout, salvata in localStorage
3. **Timeout utente:** 60 secondi sulla schermata decisione
4. **Multi-layout:** Il sistema supporta RFID su tastiera US e IT
5. **Backend asettico:** Nessun messaggio multilingua dal server
6. **Git:** Il progetto sfrutta un Repository per versionare e sviluppare, ma solo l'utente può eseguire comandi git, eccetto se richiesto diversamente, l'agente può solo chiedere di eseguire o suggerire cosa fare, ma mai prendere iniziative

---

## 📚 Documentazione Correlata

- `01-backend-plan.md` - Piano sviluppo backend
- `02-frontend-plan.md` - Piano sviluppo frontend