emanuele.alfano/Focolari-Voting-System
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Controllo accessi RFID completo con gestione sessioni

Browse Source 
- Aggiunto supporto multi-pattern RFID (US/IT layout)
- Implementata invalidazione sessioni al restart del server
- Schermata "badge non trovato" con countdown 30s
- Notifica quando badge validatore passato senza utente
- Database aggiornato con badge reali di test
- Layout ottimizzato per tablet orizzontale
- Banner NumLock per desktop
- Toggle visibilità password
- Carosello benvenuto multilingua (10 lingue)
- Pagina debug RFID (/debug)
This commit is contained in:
alfy
2026-01-17 20:06:50 +01:00
parent 21b509c6ba
commit e68f299feb
48 changed files with 3625 additions and 2445 deletions
Download Patch File Download Diff File Expand all files Collapse all files

272
ai-prompts/00-welcome-agent.md
View File

@@ -1,206 +1,150 @@
# 🎯 Focolari Voting System - Guida Agente
# 🗳️ Focolari Voting System - Welcome Agent
## 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.
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).
---
## 🏗️ Architettura
## 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/
├── 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
├── 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/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/ # Custom hooks (RFID scanner)
├── hooks/ # useRFIDScanner
├── components/ # UI components
├── screens/ # Schermate complete
├── services/ # API layer
├── types/ # TypeScript definitions
└── tests/ # Test automatici use case
├── screens/ # Schermate
├── services/ # API client
└── types/ # TypeScript types
```
---
## 🔧 Stack Tecnologico
## Funzionalità Principali
### Backend Mock
- **Python 3.10+**
- **FastAPI** - Framework web asincrono
- **Uvicorn** - ASGI server
- **Pydantic** - Validazione dati
- **pipenv** - Gestione ambiente virtuale
- **argparse** - Parametri CLI (porta, dataset)
### Flusso Utente
### 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
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
### Gestione RFID
- **Multi-pattern**: Supporta layout tastiera US (`;?`) e IT (`ò_`)
- **Timeout 2.5s**: Per scansioni accidentali
- **ESC annulla**: Scansione in corso
- **Enter handling**: Gestito automaticamente
### Sicurezza Sessioni
- Sessione salvata in localStorage
- **Invalidazione automatica** se il server riparte
- Timeout 30 minuti
---
## 🎨 Design System
## Comandi Rapidi
| 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
```
# Setup iniziale
./dev.sh install
### Frontend
```bash
cd frontend
npm install
npm run dev # Sviluppo
npm run test # Test suite
npm run test:ui # Test con UI
# 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
```
---
## 🧪 Test Automatici
## Badge di Test
Suite di test per validazione use case:
| Badge | Nome | Ruolo | Ammesso |
|--------------|----------------|---------|---------------|
| `0008988288` | Marco Bianchi | Votante | ✅ |
| `0007399575` | Laura Rossi | Votante | ✅ |
| `0000514162` | Giuseppe Verdi | Tecnico | ❌ |
| `0006478281` | - | - | ⚠️ Non nel DB |
| Test | Descrizione |
|------|-------------|
| UC01 | Login validatore |
| UC02 | Accesso partecipante ammesso |
| UC03 | Accesso negato |
| UC04 | Timeout sessione |
| UC05 | Cambio rapido badge |
| UC06 | Pattern RFID multipli |
**Password validatore:** `focolari`
---
## 🔍 Debug
## Dove Trovare Cosa
### 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
| 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` |
| Configurazione Vite | `frontend/vite.config.ts` |
---
## ⚠️ Note Importanti
## 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
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.
---
## 📚 Documentazione Correlata
## TODO (da concordare con committenti)
- `01-backend-plan.md` - Piano sviluppo backend
- `02-frontend-plan.md` - Piano sviluppo frontend
- [ ] Verificare se il badge validatore debba essere validato anche lato server
- [ ] Test automatici E2E per regression detection