Browse Source
- 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.master
4 changed files with 200 additions and 168 deletions
@ -0,0 +1,114 @@
|
||||
# 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 |
||||
@ -0,0 +1,7 @@
|
||||
fastapi>=0.104.0 |
||||
uvicorn[standard]>=0.24.0 |
||||
sqlalchemy>=2.0.0 |
||||
psycopg2-binary>=2.9.0 |
||||
pydantic>=2.0.0 |
||||
python-jose[cryptography]>=3.3.0 |
||||
python-multipart>=0.0.6 |
||||
Loading…
Reference in new issue