Matteo Benedetto
a394ed9ad2
- Enhanced README and idea documentation with detailed system architecture and operational flows. - Revised database schema to simplify table structures and improve data handling with JSONB. - Added state management for reservations in the schema. - Updated requirements file to include necessary dependencies.
114 lines
6.4 KiB
Markdown
114 lines
6.4 KiB
Markdown
# 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 |