← Torna alla Dashboard
SAGRA 2026
Documentazione di Sistema
Manuale Tecnico & Amministrazione
Guida avanzata riservata agli Amministratori e Sviluppatori: architettura ibrida, sincronizzazione Cloud, sicurezza e procedure di emergenza.
🔒 Riservato ad Amministratori & Super Admin
📋 Indice

# Sommario Tecnico

Sezione | Titolo | Descrizione
--- | --- | ---
1 | Architettura Ibrida | Mac Locale, Cloud Bridge (Aruba/Synology) e Flussi Dati
2 | Procedure di Avvio | Inizializzazione server locale, script remoti e porte
3 | Sincronizzazione & Database | Sync Worker, WAL Checkpoint, Backup Cloud Ponte
4 | Matrice Ruoli & Sicurezza | RBAC, Autorizzazioni Endpoints, Gestione Token e 403
5 | Rete & Stampanti Termiche | IP Statici, ESC/POS TCP 9100, Wi-Fi e Monitor TV

🏗️ Sezione 1

# Architettura Ibrida di Rete

Il sistema adotta un modello distribuito Edge-Cloud ibrido per garantire continuità di servizio anche in caso di caduta della connessione Internet durante l'evento:

📱 Clienti (Smartphone su Rete 4G/5G/Wi-Fi)
│
▼ [HTTPS / HTTP] - Scansione QR Code Menu Smart
☁️ SERVER CLOUD REMOTO (VPS Aruba o Synology NAS)
├── server.py (RUN_MODE = 'remote')
└── MySQL Database (Tabella temporanea ordini clienti)
│
│ SYNC WORKER AUTOMATICO (Ogni 10s - Autenticato con X-Sync-Token)
│ • PULL: Scarica nuovi ordini dal Cloud nel DB locale
│ • PUSH: Invia al Cloud lo stato aggiornato (In Preparazione, Pronto, Consegnato)
▼
🖥️ SERVER LOCALE MASTER (Mac/PC Sagra - IP Fisso)
├── server.py (RUN_MODE = 'local' - Porta 8000)
├── SQLite Database (sagra.db - WAL Mode)
└── Spooler Stampa Termica ESC/POS (Server-Side)
│
┌───┴───────────────────────────────┐
💳 Postazioni Cassa LAN 🍳 Monitor Cucina & Pizzeria 📺 Smart TV Tabellone
/cashier.html /kitchen_matrix.html /display.html

## Flusso e Resilienza

1. Isolamento Operativo Locale: Anche se la connessione Internet globale cade, le casse locali e la cucina continuano a stampare e preparare comande senza alcuna interruzione su SQLite locale.

2. Polling Clienti: I clienti effettuano il polling di stato del proprio ordine (ogni 5 secondi) direttamente sul server Cloud, senza sovraccaricare la rete Wi-Fi locale della sagra.

🚀 Sezione 2

# Procedure di Avvio e Rete

## Requisiti Server Locale Master

⚠️
REQUISITO FONDAMENTALE: IP STATICO (FISSO)
Il computer che fa da server principale (Mac/PC master) DEVE avere un indirizzo IP statico (es. `192.168.1.100`) assegnato nel router. Se l'indirizzo DHCP cambiasse, i tablet e i monitor perderebbero il collegamento.
1
Avvio Server Locale Esegui da terminale: `python3 server.py` oppure fai doppio clic sullo script `Avvia_Sagra.command`. Il server aprirà la porta `8000`.
2
Avvio Server Remoto Cloud (Aruba o NAS Synology) Connettiti via SSH al server remoto ed esegui lo script di boot: `bash avvia_remoto.sh` (ascolto su porta `8082`).
3
Verifica Sync Worker Nel log del terminale master locale apparirà: `[Sync Worker] Avviato... polling ogni 10s`.
☁️ Sezione 3

# Sincronizzazione & Backup Cloud Ponte

## Backup Cloud Istantaneo ("Ponte")

La funzione di backup cloud consente di utilizzare il server remoto come archivio ponte sicuro per replicare database e configurazioni tra postazioni master differenti:

1
Invia Backup al Cloud (Postazione A) Dalla scheda Impostazioni > Database (riservata a `SUPER_ADMIN`), cliccando su "☁️ Invia Backup al Server Remoto" viene eseguito il checkpoint WAL e creato un pacchetto `cloud_backup.zip` crittografato dal token di sincronizzazione.
2
Scarica e Ripristina (Postazione B) Sulla nuova postazione, inserisci Token e URL remoto e clicca su "☁️ Scarica e Ripristina dal Cloud". Il file viene predisposto come `sagra.db.new`.
⚠️
Regola del Riavvio per SQLite: Al termine del download, il server si arresta. Al successivo riavvio, il sistema sostituisce automaticamente `sagra.db.new` in `sagra.db` eliminando i vecchi file `-wal` e `-shm`.
🛡️ Sezione 4

# Matrice Ruoli & Sicurezza (RBAC)

Il sistema applica una rigida matrice di controllo degli accessi. Tentativi di accesso a schermate non consentite mostrano una schermata di Accesso Negato (403):

Ruolo | Permessi & Pagine Autorizzate | Pagine Bloccate (403)
--- | --- | ---
👑 SUPER_ADMIN | Accesso Illimitato: Menu, Cassa, Cucina, Pizzeria, Resoconto, Settings (con Tab Database Danger Zone), Installer, Statistiche, Web Monitor, Strumenti di Test, Gestione Utenti completa. | Nessuna restrizione
🔧 ADMIN | Gestione & Back-Office: Menu & Settori, Resoconto Serata, Impostazioni Generali (Stato Sagra, Stampanti, Gateway, TV), Statistiche, Web Monitor, Creazione account Cassiere/Cucina. | Cassa operativa, Cucina, Pizzeria, Installer, Strumenti di Test, Tab Database Danger Zone.
👤 CASSIERE | Punto Vendita: Monitor Cassa (incasso/convalida) e Resoconto Serata (conteggio quadratura). | Cucina, Menu, Impostazioni, Installer, Statistiche, Utenti.
🍳 CUCINA | Preparazione: Monitor Cucina (Matrice) o Monitor Pizzeria per il proprio reparto. | Cassa, Resoconto, Menu, Impostazioni, Statistiche, Utenti.
📊 F&B_MANAGER | Ottimizzazione: Pagina Pricing Optimizer per analisi margini e prezzi. | Tutte le altre postazioni operative.

🖨️ Sezione 5

# Stampanti Termiche & Hardware

### Stampante Totem Self-Service (ESC/POS via TCP Socket)

Il server locale master invia direttamente i comandi raw di stampa su porta TCP 9100 all'indirizzo IP della stampante termica di rete (es. `192.168.1.200`), garantendo la stampa immediata dei talloncini senza finestre di dialogo del browser.

### Ritardi di Spooling Carta

Nel pannello Impostazioni > Configurazione Operativa è possibile regolare:

- Ritardo Pre-Stampa (ms): Tempo per il rendering HTML (default: 100-300ms).
- Ritardo Post-Stampa / Taglio (ms): Tempo per consentire il taglio fisico della taglierina prima del comando successivo (default: 300-800ms).