11 changed files with 522 additions and 133 deletions
@ -0,0 +1,366 @@
|
||||
# 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. |
||||
@ -0,0 +1,19 @@
|
||||
services: |
||||
|
||||
db: |
||||
image: postgres |
||||
restart: always |
||||
# set shared memory limit when using docker compose |
||||
shm_size: 128mb |
||||
# or set shared memory limit when deploy via swarm stack |
||||
#volumes: |
||||
# - type: tmpfs |
||||
# target: /dev/shm |
||||
# tmpfs: |
||||
# size: 134217728 # 128*2^20 bytes = 128Mb |
||||
environment: |
||||
POSTGRES_PASSWORD: example |
||||
ports: |
||||
- "5432:5432" |
||||
volumes: |
||||
- ./db_data:/var/lib/postgresql/data |
||||
Loading…
Reference in new issue