Sistema di Prenotazione Mensa - Documentazione Tecnica

Abstract

Il sistema di prenotazione mensa è una piattaforma web-based sviluppata, con FastAPI e PostgreSQL a livello backend e NiceGUI per le interfacce fullstack, che consente agli utenti di prenotare pasti giornalieri. L'architettura è basata su un'API RESTful con autenticazione JWT, garantendo sicurezza e scalabilità. Il sistema gestisce tr entità principali interconnesse: prenotazioni, pasti e pietanze, utilizzando campi JSON per semplificare le relazioni e migliorare le erformance. I dati utente sono forniti dal JWT auth bearer evittando la memorizzazione sul database di dati sensibili non necessari, sfruttando per questa funzionalità lo IAM Azure e l'account aziendale (o anche IAM self hosted Keycloak)

Architettura del Sistema

Stack Tecnologico

• Backend: FastAPI (Python 3.8+)
• Database: PostgreSQL 13+ con supporto JSON/JSONB
• Autenticazione: JWT (JSON Web Tokens) / OpenID-Connect (provider Azure o self-hosted)
• HMI: webgui fullstack NiceGUI (Python 3.9+)

Database Design

Filosofia di Semplificazione

Il database è stato progettato seguendo una filosofia di massima semplificazione, riducendo la complessità relazionale tradizionale attraverso l'uso strategico di campi JSONB di PostgreSQL al posto di tabelle intermedie per le relazioni N a N. Contestalmente alla semplicità dello scheme e alle potenti capacità di manipolazione di dati strutturati JSON di postgresql, questa scelta progettuale offre diversi vantaggi:

• Riduzione delle JOIN: Eliminazione di tabelle di associazione complesse
• Flessibilità: Strutture dati dinamiche per allergeni, turni e selezioni delle pietanze
• Performance: Meno query multiple per operazioni comuni
• Manutenibilità: Schema più leggibile e modificabile

Struttura delle Tabelle

Tabella pietanze

Gestisce le singole pietanze disponibili con:

• Informazioni base (nome, descrizione)
• Gestione allergeni tramite array JSON
• Controllo disponibilità e limiti di prenotazione

Tabella pasti

Rappresenta i menu giornalieri con:

• Portate JSONB: Organizzazione flessibile delle pietanze per tipologia indicando la disponibilità massima di ciascuna
• Turni JSONB: Gestione dinamica degli orari e capacità ({"12:45": 100, "13:30": 100})
• Vincolo di unicità per data e tipo pasto

Tabella prenotazioni

Collega utenti e pasti con:

• Riferimento user_id estratto da JWT
• Pietanze selezionate JSONB: Array delle scelte dell'utente
• Gestione stati del ciclo di vita della prenotazione

Flussi Operativi

Flusso di Creazione Menu Giornaliero

1. Inserimento Pietanze: Caricamento delle pietanze disponibili per il giorno
2. Composizione Pasto: Associazione pietanze alle portate tramite JSON
3. Configurazione Turni: Definizione orari e capacità massima per turno
4. Attivazione: Abilitazione delle prenotazioni per gli utenti

Flusso di Prenotazione Utente

1. Autenticazione: Verifica JWT e estrazione user_id
2. Visualizzazione Menu: Recupero pasti disponibili per data
3. Selezione Pietanze: Scelta pietanze per ogni portata disponibile
4. Validazione: Controllo disponibilità e limiti di prenotazione
5. Conferma: Creazione record prenotazione con stato 'attiva'

Flusso di Servizio Mensa

1. Consultazione Prenotazioni: Visualizzazione prenotazioni per turno
2. Erogazione Pasto: Aggiornamento stato da 'attiva', 'servita', 'pagata', 'completata'
3. Monitoraggio: Tracking utilizzo e disponibilità residua

Flusso di Gestione Disponibilità

1. Controllo Automatico: Verifica limiti pietanze e turni
2. Aggiornamento Dinamico: Modifica disponibilità in tempo reale
3. Notifiche: Gestione comunicazioni per esaurimento posti
4. Chiusura Prenotazioni: Disabilitazione automatica al raggiungimento limiti

Scelte Architetturali: Logica di Business

Principio di Separazione delle Responsabilità

In linea con la filosofia di semplificazione adottata per il design del database, la logica di business complessa rimane interamente gestita a livello API (FastAPI) piuttosto che essere delegata al database tramite stored procedures o funzioni PostgreSQL.

Motivazioni della Scelta

Coerenza Architetturale: Il sistema è progettato attorno a FastAPI come orchestratore centrale. Mantenere la logica di business nell'API garantisce un'architettura coerente e predicibile.

Manutenibilità e Testabilità: Le funzioni Python sono intrinsecamente più facili da testare, debuggare e modificare rispetto alle stored procedures. Questo si allinea con l'approccio DevOps moderno e l'integrazione continua.

Flessibilità di Sviluppo: La gestione della disponibilità, dei limiti di prenotazione e delle validazioni può evolvere rapidamente senza modifiche al schema database.

Implementazione delle Verifiche di Disponibilità

Le operazioni critiche come la verifica di disponibilità posti in un turno o di una pietanza vengono gestite tramite:

• Query atomiche per il recupero dati
• Validazioni Python per la logica di business
• Transazioni asyncpg per garantire consistenza
• Pattern async/await per performance ottimali

Scelta di asyncpg vs ORM

Il sistema utilizza asyncpg come driver database principale invece di un ORM tradizionale come SQLAlchemy per diverse ragioni strategiche:

Motivazioni Tecniche

Ottimizzazione Nativa PostgreSQL: La progettazione è strettamente legata alle funzionalità specifiche di PostgreSQL (JSONB, operatori JSON, funzioni aggregate native). Asyncpg consente di sfruttare al massimo queste capacità senza astrazioni intermedie.

Performance Async Native: Asyncpg è progettato specificamente per l'ecosistema async/await di Python, offrendo performance superiori rispetto agli adapter asincroni degli ORM tradizionali.

Controllo Granulare: Le query SQL dirette permettono un controllo preciso delle operazioni JSONB, essenziali per la gestione delle portate, turni e selezioni pietanze.

Semplicità Architetturale: Con solo tre tabelle e logica di business in Python, l'overhead di un ORM completo risulterebbe sproporzionato rispetto ai benefici.

Implementazione Pratica

• Query ottimizzate per operazioni JSONB specifiche
• Pool di connessioni gestito nativamente da asyncpg
• Transazioni esplicite per operazioni critiche di prenotazione
• Prepared statements per query ripetitive ad alta frequenza