# 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