simple-mensa/api

Implementazione API - Organizzazione dei File

Struttura delle Directory

api/
├── config.yaml              # File di configurazione per le impostazioni API
├── main.py                  # Punto di ingresso dell'applicazione FastAPI
├── dependencies.py          # Dipendenze condivise e middleware
├── core/                    # Moduli delle funzionalità principali
│   ├── __init__.py
│   ├── database.py          # Connessione al database e gestione del pool
│   ├── auth.py              # Autenticazione e autorizzazione JWT
│   ├── security.py          # Utilità di sicurezza e validatori
│   └── exceptions.py        # Classi di eccezioni personalizzate
├── models/                  # Modelli Pydantic per validazione dati
│   ├── __init__.py
│   ├── pietanze.py          # Modelli per le pietanze
│   ├── pasti.py             # Modelli per i pasti (da implementare)
│   ├── prenotazioni.py      # Modelli per le prenotazioni (da implementare)
│   └── common.py            # Modelli comuni e utilità
├── routes/                  # Gestori delle route API
│   ├── __init__.py
│   ├── pietanze.py          # Operazioni CRUD per pietanze
│   ├── pasti.py             # Endpoint di gestione pasti
│   ├── prenotazioni.py      # Operazioni di prenotazione
│   └── admin.py             # Endpoint amministrativi
└── utils/                   # Funzioni di utilità
    ├── __init__.py
    ├── validators.py        # Helper per la validazione dei dati
    └── formatters.py        # Utilità per la formattazione delle risposte

Funzionalità dei Moduli

Configurazione

config.yaml

File di configurazione centrale contenente:

• Parametri di connessione al database
• Impostazioni e segreti JWT
• Configurazione del server API
• Impostazioni CORS
• Parametri di rate limiting
• Configurazione del logging

Moduli Core

core/database.py

• Gestione del pool di connessioni asyncpg
• Ciclo di vita delle connessioni al database
• Gestori di contesto per le transazioni
• Controlli di salute delle connessioni
• Helper per l'esecuzione di query con gestione degli errori

core/auth.py

• Validazione ed estrazione dei token JWT
• Middleware di autenticazione utente
• Decoratori di autorizzazione per accesso basato sui ruoli
• Logica di refresh dei token
• Integrazione con IAM esterno (Azure/Keycloak)

core/security.py

• Utilità e helper di sicurezza
• Funzioni di sanitizzazione dell'input
• Prevenzione delle SQL injection
• Implementazioni di rate limiting
• Configurazione CORS

core/exceptions.py

• Classi di eccezioni personalizzate per la logica di business
• Mapper di eccezioni HTTP
• Standardizzazione dei codici di errore
• Integrazione del logging per le eccezioni

Modelli Pydantic

models/pietanze.py

• PietanzaBase: Modello base condiviso
• PietanzaCreate: Schema per la creazione di nuove pietanze
• PietanzaUpdate: Schema per l'aggiornamento di pietanze esistenti
• PietanzaResponse: Schema per le risposte API
• Validatori personalizzati per allergeni e campi specifici

models/common.py

• ErrorResponse: Struttura standardizzata per le risposte di errore
• PaginatedResponse: Schema per risposte paginate
• Modelli di utilità condivisi tra diverse entità

models/pasti.py (da implementare)

• Modelli Pydantic per la gestione dei pasti
• Validatori per strutture JSONB (portate, turni)
• Schemi per creazione, aggiornamento e risposta

models/prenotazioni.py (da implementare)

• Modelli per le operazioni di prenotazione
• Validatori per stati e selezioni pietanze
• Schemi per la gestione del ciclo di vita delle prenotazioni

Vantaggi della Nuova Organizzazione

Separazione delle Responsabilità

• Modelli isolati: Ogni entità ha i propri modelli in file dedicati
• Riusabilità: Modelli comuni facilmente condivisibili
• Manutenibilità: Modifiche ai modelli localizzate in file specifici

Scalabilità

• Organizzazione modulare: Facilita l'aggiunta di nuove entità
• Import selettivi: Possibilità di importare solo i modelli necessari
• Testing: Test unitari più focalizzati per ogni gruppo di modelli

Convenzioni

• Naming consistente: Suffissi standard (Create, Update, Response)
• Validatori centralizzati: Logica di validazione specifica per dominio
• Documentazione: Ogni file può contenere documentazione specifica