Focolari-Voting-System/ai-prompts/00-welcome-agent.md

🗳️ 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

# 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