Matteo Benedetto a833ce93f8 feat: Update configuration, enhance authentication, and improve database management with Italian localization		7 months ago
..
README.md	feat: Update configuration, enhance authentication, and improve database management with Italian localization	7 months ago

README.md

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

# 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`)

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

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

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

Flusso Gestione Servizio

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

Flusso Amministrazione Pietanze

Vista Lista: Tabella con ricerca e filtri
Creazione/Modifica: Form modale con validazione
Gestione Allergeni: Chip selector con autocomplete
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

Login: Redirect a provider esterno (Azure/Keycloak)
Token Management: Storage sicuro e refresh automatico
Authorization: Controllo ruoli per ogni sezione
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

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

# 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.