📋 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).