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

🎯 Focolari Voting System - Guida Agente

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.

---

🏗️ Architettura

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
    └── src/
        ├── App.tsx           # State machine principale
        ├── hooks/            # Custom hooks (RFID scanner)
        ├── components/       # UI components
        ├── screens/          # Schermate complete
        ├── services/         # API layer
        ├── types/            # TypeScript definitions
        └── tests/            # Test automatici use case

---

🔧 Stack Tecnologico

Backend Mock

• Python 3.10+
• FastAPI - Framework web asincrono
• Uvicorn - ASGI server
• Pydantic - Validazione dati
• pipenv - Gestione ambiente virtuale
• argparse - Parametri CLI (porta, dataset)

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

---

🎨 Design System

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

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

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

Frontend

cd frontend
npm install
npm run dev           # Sviluppo
npm run test          # Test suite
npm run test:ui       # Test con UI

---

🧪 Test Automatici

Suite di test per validazione use case:

Test	Descrizione
UC01	Login validatore
UC02	Accesso partecipante ammesso
UC03	Accesso negato
UC04	Timeout sessione
UC05	Cambio rapido badge
UC06	Pattern RFID multipli

---

🔍 Debug

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

---

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

---

📚 Documentazione Correlata

• 01-backend-plan.md - Piano sviluppo backend
• 02-frontend-plan.md - Piano sviluppo frontend