feat: setup iniziale sistema controllo accessi Focolari
Struttura progetto: - Backend mock Python (FastAPI) con API per gestione varchi - Frontend React + TypeScript + Vite + Tailwind CSS - Documentazione e piani di sviluppo Backend (backend-mock/): - API REST: /info-room, /login-validate, /anagrafica, /entry-request - Dati mock: 7 utenti, validatore (999999/focolari) - CORS abilitato, docs OpenAPI automatiche - Configurazione pipenv per ambiente virtuale Frontend (frontend/): - State machine completa per flusso accesso varco - Hook useRFIDScanner per lettura badge (pattern singolo) - Componenti UI: Logo, Button, Input, Modal, UserCard, Timer - Schermate: Loading, Login, ActiveGate, Success/Error Modal - Design system con colori Focolari - Ottimizzato per tablet touch Documentazione (ai-prompts/): - Welcome guide per futuri agenti - Piano sviluppo backend e frontend con checklist DA COMPLETARE: - Hook RFID multi-pattern (US/IT/altri layout tastiera) - Pagina /debug per diagnostica in loco - Logging console strutturato
This commit is contained in:
206
ai-prompts/00-welcome-agent.md
Normal file
206
ai-prompts/00-welcome-agent.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# 🎯 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
|
||||
```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
|
||||
```
|
||||
|
||||
### Frontend
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user