# 🗳️ Focolari Voting System

Sistema di controllo accessi per le assemblee di voto del **Movimento dei Focolari**.

## 📖 Descrizione

Applicazione web ottimizzata per tablet che gestisce i varchi d'ingresso alle sale votazione. Il sistema utilizza
lettori RFID USB (che emulano tastiera) per identificare validatori e partecipanti.

## 🏗️ Struttura Progetto

```
VotoFocolari/
├── dev.sh            # Script sviluppo (install, dev, server, build, ...)
├── ai-prompts/       # Documentazione sviluppo e prompt
├── backend-mock/     # API mock in Python FastAPI
│   └── static/       # Frontend buildato (generato)
└── frontend/         # App React + TypeScript + Tailwind
```

## 🚀 Quick Start

### Setup Iniziale

```bash
./dev.sh install
```

### Sviluppo (hot reload)

```bash
./dev.sh dev
# Backend API: http://localhost:8000
# Frontend Dev: http://localhost:5173
```

### Produzione Locale

```bash
./dev.sh server
# App completa: http://localhost:8000
```

### Altri Comandi

```bash
./dev.sh build      # Solo build frontend
./dev.sh backend    # Solo backend (API)
./dev.sh frontend   # Solo frontend dev
./dev.sh shell      # Shell pipenv backend
./dev.sh clean      # Pulisce build e cache
./dev.sh help       # Mostra tutti i comandi
```

## 📚 Documentazione

Per dettagli tecnici, consulta la cartella `ai-prompts/`:

- `00-welcome-agent.md` - Panoramica progetto
- `01-backend-plan.md` - Piano sviluppo backend
- `02-frontend-plan.md` - Piano sviluppo frontend

## 🔐 Credenziali Test

- **Password Validatore:** `focolari`
- **Badge Test:** Qualsiasi badge (es. `0008988288`, `0007399575`)

I badge di test con anagrafica sono documentati in `backend-mock/API_SPECIFICATION.md`.

## 🔍 Debug

Accedi a `/debug` per diagnostica RFID in tempo reale.

---

## 🏭 Build e Deploy in Produzione

### Compilazione Frontend

Il frontend React deve essere compilato in file statici prima del deploy.

```bash
# Build automatica (usa dev.sh)
./dev.sh build

# Oppure manualmente
cd frontend
npm install
npm run build
```

I file compilati vengono generati in `frontend/dist/`.

### Struttura Build Output

```
frontend/dist/
├── index.html
├── favicon.jpg
└── assets/
    ├── index-XXXXX.js      # Bundle JS minificato
    ├── index-XXXXX.css     # CSS minificato
    └── FocolareMovLogo-XXXXX.jpg
```

### Deploy

#### Opzione 1: Backend Mock (test/demo)

Il backend mock Python serve automaticamente il frontend dalla cartella `frontend/dist/`:

```bash
./dev.sh server --host 0.0.0.0 --port 8000
```

L'applicazione completa sarà disponibile su `http://<IP>:8000/`.

#### Opzione 2: Backend Reale

Il backend di produzione deve:

1. **Implementare le API** secondo le specifiche in `backend-mock/API_SPECIFICATION.md`
2. **Servire i file statici** dalla cartella `frontend/dist/` sulla root `/`
3. **Configurare CORS** se frontend e backend sono su domini diversi

Esempio con un web server (nginx, Apache, etc.):

```nginx
server {
    listen 80;
    server_name voting.focolari.org;

    # Frontend statico
    location / {
        root /var/www/focolari/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    # API proxy verso backend
    location /info-room { proxy_pass http://localhost:8080; }
    location /login-validate { proxy_pass http://localhost:8080; }
    location /anagrafica/ { proxy_pass http://localhost:8080; }
    location /entry-request { proxy_pass http://localhost:8080; }
}
```

#### Opzione 3: Tutto-in-uno (consigliata)

Il backend reale serve direttamente i file statici:

```python
# Esempio FastAPI
from fastapi.staticfiles import StaticFiles
from fastapi.responses import FileResponse

app.mount("/assets", StaticFiles(directory="frontend/dist/assets"))

@app.get("/")
async def serve_frontend():
    return FileResponse("frontend/dist/index.html")
```

### Variabili d'Ambiente

Il frontend non richiede variabili d'ambiente. Le API sono chiamate con path relativi (`/info-room`, etc.), quindi funziona automaticamente indipendentemente dal dominio o porta.

### Requisiti Sistema Produzione

- **Python 3.11+** con `pipenv` (per backend mock)
- **Node.js 18+** con `npm` (solo per build frontend)
- **Browser moderno** (Chrome, Safari, Firefox) sul tablet
- **Lettore RFID** configurato come tastiera HID

---

## 📄 Licenza

Progetto privato - Movimento dei Focolari