316 lines
9.2 KiB
Markdown
316 lines
9.2 KiB
Markdown
# 🗳️ 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
|