alfy
b467d4753d
CORREZIONI:
- Badge confrontato ESATTAMENTE come stringa (rimosso .lstrip("0"))
- Success modal si chiude quando arriva nuovo badge (fix dipendenze useCallback)
- Polling ogni 30s per invalidare sessione se server riparte
- Area carosello allargata per testi lunghi (es. russo)
DOCUMENTAZIONE:
- API_SPECIFICATION.md aggiornata: badge come stringa esatta
- Creata TEST_CHECKLIST.md con 22 test manuali
- Aggiornati piani backend e frontend
Badge sono STRINGHE, non numeri:
- "0008988288" != "8988288" (zeri iniziali significativi)
158 lines
5.0 KiB
Markdown
158 lines
5.0 KiB
Markdown
# 🗳️ 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
|