# 🗳️ Focolari Voting System

Sistema di controllo accessi per le assemblee di voto del **Movimento dei Focolari**.

## 📖 Descrizione

Applicazione web ottimizzata per tablet che gestisce i varchi d'ingresso alle sale votazione. Il sistema utilizza
lettori RFID USB (che emulano tastiera) per identificare validatori e partecipanti.

## 🏗️ Struttura Progetto

```
VotoFocolari/
├── dev.sh            # Script sviluppo (install, dev, server, build, ...)
├── ai-prompts/       # Documentazione sviluppo e prompt
├── backend-mock/     # API mock in Python FastAPI
│   └── static/       # Frontend buildato (generato)
└── frontend/         # App React + TypeScript + Tailwind
```

## 🚀 Quick Start

### Setup Iniziale

```bash
./dev.sh install
```

### Sviluppo (hot reload)

```bash
./dev.sh dev
# Backend API: http://localhost:8000
# Frontend Dev: http://localhost:5173
```

### Produzione Locale

```bash
./dev.sh server
# App completa: http://localhost:8000/badge
```

### Altri Comandi

```bash
./dev.sh build      # Solo build frontend
./dev.sh backend    # Solo backend (API)
./dev.sh frontend   # Solo frontend dev
./dev.sh test       # Esegue i test frontend
./dev.sh test:watch # Test in watch mode
./dev.sh test:dev   # Server + test watch mode
./dev.sh shell      # Shell pipenv backend
./dev.sh clean      # Pulisce build e cache
./dev.sh help       # Mostra tutti i comandi
```

## 🧪 Test

Il progetto include una suite completa di **56 test automatici** per il frontend.

### Comandi Test

```bash
# Esegue tutti i test una volta (CI/CD)
./dev.sh test

# Test in watch mode - riesegue automaticamente quando modifichi i file
./dev.sh test:watch

# Server + Test watch mode - utile per test manuali + automatici insieme
./dev.sh test:dev
```

### Come usare `test:watch`

Il watch mode è utile durante lo sviluppo:

1. **Avvia i test in watch mode:**
   ```bash
   ./dev.sh test:watch
   ```

2. **Cosa succede:**
    - I test vengono eseguiti immediatamente
    - Vitest rimane in ascolto dei cambiamenti
    - Quando salvi un file `.ts` o `.tsx`, i test correlati vengono rieseguiti automaticamente

3. **Comandi interattivi** (mentre è in esecuzione):
    - `a` - Riesegui tutti i test
    - `f` - Riesegui solo i test falliti
    - `p` - Filtra per nome file
    - `t` - Filtra per nome test
    - `q` - Esci

4. **Per test manuali + automatici insieme:**
   ```bash
   ./dev.sh test:dev
   ```
   Questo avvia sia il server (http://localhost:8000/badge) che i test in watch mode, così puoi:
    - Testare manualmente nel browser
    - Vedere i test automatici aggiornarsi in tempo reale

### Copertura Test (56 test)

| Categoria          | Test | Descrizione                                                    |
|--------------------|------|----------------------------------------------------------------|
| **useRFIDScanner** | 20   | Pattern US/IT, timeout, ESC, Enter handling                    |
| **API Service**    | 13   | Endpoint, error handling, badge stringa, **bypass protection** |
| **UserCard**       | 9    | Rendering, stati ammesso/non ammesso                           |
| **Configurazione** | 14   | Timeout, sessione, invalidazione server restart                |

### Test Critico: Backend Safety

Il test `should block non-ammesso user even if frontend bug sends request` verifica che:

- Anche se un bug nel frontend permette di inviare una richiesta per un utente NON ammesso
- Il **backend** risponde comunque con `success: false`
- Questo è un controllo di sicurezza a livello server

### Tipi di Test

⚠️ **Nota:** I test attuali sono **unit test** che girano in un DOM simulato (jsdom).
Non aprono un browser reale. Per test End-to-End (E2E) che aprono il browser,
servirebbe Playwright o Cypress (non ancora implementato).

### Con npm direttamente

```bash
cd frontend
npm run test:run      # Esecuzione singola
npm run test          # Watch mode
npm run test:coverage # Con coverage report
```

## 🎭 Test E2E (Playwright)

Test End-to-End che aprono un **browser reale** e verificano i flussi completi dell'applicazione.

### Comandi E2E

| Comando                    | Descrizione                                                                        |
|----------------------------|------------------------------------------------------------------------------------|
| `./dev.sh test:e2e`        | Test **headless** (senza vedere il browser), server avviato automaticamente        |
| `./dev.sh test:e2e:headed` | Test con **browser visibile**, server avviato automaticamente                      |
| `./dev.sh test:e2e:ui`     | Apre **Playwright UI** (IDE interattivo per debug), server avviato automaticamente |

```bash
# Test veloci (headless)
./dev.sh test:e2e

# Test con browser visibile (per vedere cosa succede)
./dev.sh test:e2e:headed

# Debug interattivo (clicca sui test nell'UI)
./dev.sh test:e2e:ui

# Filtrare test specifici
./dev.sh test:e2e:headed -- --grep "login"
./dev.sh test:e2e:headed -- --project=chromium
```

### Test E2E Inclusi

| Categoria               | Test                                         |
|-------------------------|----------------------------------------------|
| **Flusso Validatore**   | Login, password, annulla                     |
| **Flusso Partecipante** | Badge ammesso/non ammesso/non trovato        |
| **Conferma Ingresso**   | Success modal, warning non ammesso           |
| **Sicurezza**           | Backend blocca non-ammesso → errore frontend |
| **Debug & Session**     | Pagina debug, logout, persistenza sessione   |

### Test Critico: Sicurezza Backend

Il test E2E `backend blocca non-ammesso → frontend mostra errore`:

1. Intercetta la chiamata API `/entry-request`
2. Forza risposta `success: false` (simula backend che blocca)
3. Verifica che il frontend **NON** mostri il carosello di benvenuto
4. Verifica che mostri un messaggio di errore

Questo garantisce che anche se il frontend ha bug, il backend fa da ultimo baluardo.

## 📚 Documentazione

Per dettagli tecnici, consulta:

### Guide:
- **`PATH_STRUCTURE.md`** - Struttura path del sistema (`/badge` per frontend, `/api/*` per API)
- **`CHANGE_BASE_PATH.md`** - Come cambiare il path base del frontend o delle API
- **`NETWORK_ACCESS.md`** - Come accedere al server da altri dispositivi (tablet)

### Piani di sviluppo (`ai-prompts/`):
- `00-welcome-agent.md` - Panoramica progetto
- `01-backend-plan.md` - Piano sviluppo backend
- `02-frontend-plan.md` - Piano sviluppo frontend

## 🔐 Credenziali Test

- **Password Validatore:** `focolari`
- **Badge Test:** Qualsiasi badge (es. `0008988288`, `0007399575`)

I badge di test con anagrafica sono documentati in `backend-mock/API_SPECIFICATION.md`.

## 🔍 Debug

Accedi a `/debug` per diagnostica RFID in tempo reale.

---

## 🏭 Build e Deploy in Produzione

### Compilazione Frontend

Il frontend React deve essere compilato in file statici prima del deploy.

```bash
# Build automatica (usa dev.sh)
./dev.sh build

# Oppure manualmente
cd frontend
npm install
npm run build
```

I file compilati vengono generati in `frontend/dist/`.

### Struttura Build Output

```
frontend/dist/
├── index.html
├── favicon.jpg
└── assets/
    ├── index-XXXXX.js      # Bundle JS minificato
    ├── index-XXXXX.css     # CSS minificato
    └── FocolareMovLogo-XXXXX.jpg
```

### Deploy

#### Opzione 1: Backend Mock (test/demo)

Il backend mock Python serve automaticamente il frontend dalla cartella `frontend/dist/`:

```bash
./dev.sh server --host 0.0.0.0 --port 8000
```

L'applicazione completa sarà disponibile su `http://<IP>:8000/`.

#### Opzione 2: Backend Reale

Il backend di produzione deve:

1. **Implementare le API** secondo le specifiche in `backend-mock/API_SPECIFICATION.md`
2. **Servire i file statici** dalla cartella `frontend/dist/` sulla root `/`
3. **Configurare CORS** se frontend e backend sono su domini diversi

Esempio con un web server (nginx, Apache, etc.):

```nginx
server {
    listen 80;
    server_name voting.focolari.org;

    # Frontend statico
    location / {
        root /var/www/focolari/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    # API proxy verso backend
    location /info-room { proxy_pass http://localhost:8080; }
    location /login-validate { proxy_pass http://localhost:8080; }
    location /anagrafica/ { proxy_pass http://localhost:8080; }
    location /entry-request { proxy_pass http://localhost:8080; }
}
```

#### Opzione 3: Tutto-in-uno (consigliata)

Il backend reale serve direttamente i file statici:

```python
# Esempio FastAPI
from fastapi.staticfiles import StaticFiles
from fastapi.responses import FileResponse

app.mount("/assets", StaticFiles(directory="frontend/dist/assets"))


@app.get("/")
async def serve_frontend():
    return FileResponse("frontend/dist/index.html")
```

### Variabili d'Ambiente

Il frontend non richiede variabili d'ambiente. Le API sono chiamate con path relativi (`/info-room`, etc.), quindi
funziona automaticamente indipendentemente dal dominio o porta.

### Requisiti Sistema Produzione

- **Python 3.11+** con `pipenv` (per backend mock)
- **Node.js 18+** con `npm` (solo per build frontend)
- **Browser moderno** (Chrome, Safari, Firefox) sul tablet
- **Lettore RFID** configurato come tastiera HID

---

## 📄 Licenza

Progetto privato - Movimento dei Focolari