# Interfaccia Web di Amministrazione - Simple Mensa

## Overview

L'interfaccia web di amministrazione è sviluppata con **NiceGUI**, un framework Python moderno che combina la semplicità di sviluppo backend con un'interfaccia utente reattiva e moderna. L'applicazione fornisce un pannello di controllo completo per la gestione del sistema di prenotazione mensa.

## Architettura dell'Applicazione

### Stack Tecnologico

- **Frontend Framework**: NiceGUI 1.4+
- **Backend Integration**: Integrazione diretta con FastAPI via HTTP client
- **Authentication**: JWT token-based con provider esterno
- **Styling**: Tailwind CSS + Quasar Components
- **Real-time Updates**: WebSocket per aggiornamenti live
- **Charts & Analytics**: Plotly.js integrato

### Struttura del Progetto

```
webgui/
├── main.py                 # Punto di ingresso dell'applicazione NiceGUI
├── config.yaml            # Configurazione per la webgui
├── requirements.txt       # Dipendenze specifiche per la webgui
├── pages/                 # Pagine dell'interfaccia amministrativa
│   ├── __init__.py
│   ├── login.py           # Pagina di autenticazione
│   ├── dashboard.py       # Dashboard principale con KPI
│   ├── pietanze.py        # Gestione CRUD pietanze
│   ├── pasti.py           # Composizione e gestione menu giornalieri
│   ├── prenotazioni.py    # Monitoraggio e gestione prenotazioni
│   └── analytics.py       # Reports e statistiche
├── components/            # Componenti riutilizzabili
│   ├── __init__.py
│   ├── layout.py          # Layout principale e navigazione
│   ├── forms.py           # Form components personalizzati
│   ├── tables.py          # Tabelle con paginazione e filtri
│   ├── charts.py          # Grafici e visualizzazioni
│   └── modals.py          # Dialoghi e popup
├── services/              # Servizi per comunicazione con API
│   ├── __init__.py
│   ├── api_client.py      # Client HTTP per FastAPI
│   ├── auth_service.py    # Gestione autenticazione
│   └── data_service.py    # Servizi per manipolazione dati
├── utils/                 # Utilità e helper
│   ├── __init__.py
│   ├── formatters.py      # Formatters per date, numeri, etc.
│   └── validators.py      # Validatori lato client
└── static/                # File statici (CSS, JS, immagini)
    ├── styles.css
    └── logo.png
```

## Funzionalità dell'Interfaccia

### 1. Dashboard Principale (`pages/dashboard.py`)

**KPI e Metriche in Tempo Reale**
- Card con statistiche giornaliere (prenotazioni attive, pasti serviti, disponibilità)
- Grafici trend settimanali/mensili delle prenotazioni
- Indicatori di utilizzo capacità per turno
- Alert per situazioni critiche (esaurimento posti, pietanze terminate)

**Widget Informativi**
- Calendario con vista mensile delle prenotazioni
- Lista prenotazioni recenti con stati in tempo reale
- Notifiche e alert di sistema

### 2. Gestione Pietanze (`pages/pietanze.py`)

**Interfaccia CRUD Completa**
- Tabella responsive con ricerca full-text e filtri per allergeni
- Form di creazione/modifica con validazione client-side
- Upload di immagini per le pietanze (futuro sviluppo)
- Gestione allergeni con chip multiselect
- Azioni bulk per operazioni multiple

**Componenti Specifici**
```python
# Esempio struttura componente pietanze
class PietanzeManager:
    def __init__(self):
        self.search_filter = ""
        self.allergen_filter = []
        
    def render_pietanze_table(self):
        # Tabella con sorting, paginazione, ricerca
        pass
        
    def render_pietanza_form(self, pietanza=None):
        # Form responsive con validazione
        pass
```

### 3. Composizione Menu (`pages/pasti.py`)

**Editor Menu Giornaliero**
- Calendario per selezione data
- Drag & drop per composizione portate
- Configurazione turni con slider per capacità
- Anteprima menu con calcolo automatico disponibilità
- Duplicazione menu da giorni precedenti

**Gestione Turni Dinamica**
- Time picker per orari turni
- Slider per impostazione capacità massima
- Visualizzazione occupazione in tempo reale

### 4. Monitoraggio Prenotazioni (`pages/prenotazioni.py`)

**Vista Operativa per il Servizio**
- Tabella prenotazioni filtrata per data/turno
- Aggiornamento stati prenotazione con click
- Scansione QR code per check-in rapido
- Stampa liste per cucina e cassa

**Funzionalità Avanzate**
- Ricerca prenotazioni per utente
- Export CSV per reporting
- Gestione cancellazioni e modifiche
- Comunicazioni automatiche via email

### 5. Analytics e Reports (`pages/analytics.py`)

**Dashboard Analitica**
- Grafici utilizzo pietanze e preferenze utenti
- Report sprechi e ottimizzazione menù
- Analisi pattern prenotazioni
- Forecast domanda per pianificazione

**Export e Reportistica**
- Report PDF configurabili
- Export dati in formati multipli
- Grafici interattivi con drill-down

## Componenti Tecnici

### Layout e Navigazione (`components/layout.py`)

```python
class AdminLayout:
    def __init__(self):
        self.sidebar_open = True
        
    def render_header(self):
        # Header con user info, logout, notifiche
        pass
        
    def render_sidebar(self):
        # Menu laterale con sezioni collassabili
        pass
        
    def render_main_content(self):
        # Area principale responsiva
        pass
```

### Componenti Form (`components/forms.py`)

**Form Builder Dinamico**
- Generazione automatica form da modelli Pydantic
- Validazione real-time con feedback visuale
- Upload file con progress bar
- Date/time picker localizzati
- Multiselect con ricerca

### Tabelle Avanzate (`components/tables.py`)

**DataTable Component**
- Server-side pagination per performance
- Sorting multi-colonna
- Filtri avanzati per colonna
- Export integrato
- Azioni batch selettive

### Integrazione API (`services/api_client.py`)

**HTTP Client Ottimizzato**
```python
class APIClient:
    def __init__(self, base_url: str, auth_token: str):
        self.base_url = base_url
        self.headers = {"Authorization": f"Bearer {auth_token}"}
        
    async def get_pietanze(self, filters: dict = None):
        # GET /api/v1/pietanze con filtri
        pass
        
    async def create_pasto(self, pasto_data: dict):
        # POST /api/v1/pasti
        pass
```

## Flussi Operativi dell'Interfaccia

### Flusso Creazione Menu Giornaliero

1. **Selezione Data**: Calendario per scelta giorno
2. **Composizione Portate**: Drag & drop pietanze nelle categorie
3. **Impostazione Turni**: Time picker + capacity slider
4. **Anteprima e Validazione**: Controllo disponibilità e conflitti
5. **Attivazione**: Toggle per abilitare prenotazioni

### Flusso Gestione Servizio

1. **Vista Prenotazioni Turno**: Filtro automatico per turno corrente
2. **Check-in Utenti**: Click su riga o scansione QR
3. **Aggiornamento Stati**: Transizioni stato con validazione
4. **Monitoraggio Disponibilità**: Aggiornamenti real-time

### Flusso Amministrazione Pietanze

1. **Vista Lista**: Tabella con ricerca e filtri
2. **Creazione/Modifica**: Form modale con validazione
3. **Gestione Allergeni**: Chip selector con autocomplete
4. **Operazioni Bulk**: Selezione multipla per azioni batch

## Caratteristiche UX/UI

### Design System

**Palette Colori**
- Primary: Verde accogliente per azioni positive
- Secondary: Arancione per elementi di attenzione
- Neutral: Grigi per backgrounds e testi
- Status Colors: Semantici per stati (rosso errore, verde successo)

**Typography**
- Font system: Inter per leggibilità ottimale
- Hierarchy: H1-H6 ben definiti
- Body text: 16px base per accessibilità

**Spacing & Layout**
- Grid system 12 colonne responsive
- Breakpoints standard (mobile, tablet, desktop)
- Spacing scale basato su multipli di 8px

### Responsività

**Mobile-First Design**
- Layout collassabile per mobile
- Touch-friendly button sizing
- Swipe gestures per tabelle
- Bottom navigation su mobile

**Progressive Enhancement**
- Funzionalità base su tutti i device
- Funzionalità avanzate su desktop
- Graceful degradation per browser legacy

### Accessibilità

**WCAG 2.1 AA Compliance**
- Contrasto colori adeguato
- Navigazione da tastiera completa
- Screen reader friendly
- Focus indicators chiari
- Alt text per immagini

## Performance e Ottimizzazioni

### Lazy Loading

- Caricamento componenti on-demand
- Paginazione server-side per tabelle grandi
- Immagini lazy-loaded

### Caching Strategy

- Cache client per dati statici
- Invalidazione intelligente
- Prefetch per navigazione anticipata

### Real-time Updates

- WebSocket per notifiche push
- Server-sent events per updates dashboard
- Optimistic UI per azioni immediate

## Sicurezza

### Authentication Flow

1. **Login**: Redirect a provider esterno (Azure/Keycloak)
2. **Token Management**: Storage sicuro e refresh automatico
3. **Authorization**: Controllo ruoli per ogni sezione
4. **Logout**: Pulizia completa sessione

### Data Protection

- Sanitizzazione input utente
- Validazione server-side sempre presente
- HTTPS only per comunicazioni
- CSP headers per XSS protection

## Deployment e Configurazione

### Development Setup

```bash
cd webgui
pip install -r requirements.txt
cp config.yaml.example config.yaml
# Configura URL API e credenziali
python main.py
```

### Production Deployment

- Container Docker con NiceGUI
- Reverse proxy con SSL termination
- Health checks e monitoring
- Backup automatici configurazione

### Environment Variables

```yaml
# config.yaml example
api:
  base_url: "http://localhost:8000"
  timeout: 30

auth:
  provider_url: "https://login.microsoftonline.com/..."
  client_id: "your-client-id"
  
app:
  title: "Simple Mensa Admin"
  debug: false
  port: 8080
```

## Estensibilità Futura

### Moduli Aggiuntivi

- **Gestione Utenti**: CRUD utenti con ruoli
- **Inventory Management**: Controllo ingredienti e scorte
- **Financial Reports**: Controllo costi e ricavi
- **Mobile App**: Companion app per servizio cucina

### Integrazioni

- **ERP Integration**: Sync con sistemi aziendali
- **Payment Gateway**: Pagamenti online
- **SMS/Push Notifications**: Comunicazioni real-time
- **IoT Integration**: Sensori per monitoraggio automatico

## Testing Strategy

### Unit Testing
- Test componenti NiceGUI
- Mock API calls
- Validation logic testing

### Integration Testing
- End-to-end user workflows
- API integration testing
- Authentication flow testing

### Performance Testing
- Load testing per concorrenza
- Memory usage profiling
- Response time benchmarks

Questa architettura garantisce un'interfaccia amministrativa moderna, scalabile e user-friendly, perfettamente integrata con l'API FastAPI esistente e pronta per evoluzioni future.