# 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