# Manuale Operativo del Gestionale PowerUp

Versione manuale: stato del progetto al 12 aprile 2026.

Questo documento descrive l'uso pratico del gestionale cosi come risulta dai sorgenti attuali del progetto. Dove una funzione e ancora parziale o placeholder, lo segnalo esplicitamente.

## 1. Obiettivo del gestionale

Il gestionale unifica in un unico workspace:

- accesso al locale e ai moduli
- assistente operativo della Home
- ordini e storico acquisti
- prenotazioni, tavoli, piantina e WhatsApp prenotazioni
- documenti cloud su Google Workspace
- documenti fiscali del locale
- gestione di sotto-account e permessi del team

## 2. Ruoli e permessi

Nel sistema esistono tre profili principali.

### Super admin

Puo:

- accedere alla console piattaforma
- creare nuovi locali
- creare l'admin principale di ogni locale
- aggiornare dati del locale e dell'admin cliente
- entrare dentro un tenant come se fosse il locale stesso
- cambiare la password del super admin

### Admin locale

Puo:

- usare tutte le funzioni del proprio tenant
- creare, modificare ed eliminare i sotto-account del team
- decidere quali strumenti rendere disponibili ai dipendenti

### Sotto-account dipendente

Ha sempre accesso alla Home del locale.

Le altre aree dipendono dai permessi assegnati dall'admin:

- `assistant`
- `ordini`
- `prenotazioni`
- `documents`
- `menu`
- `homemade`
- `fiscal_documents`

Se un dipendente prova ad aprire una funzione non autorizzata, il sistema mostra un messaggio di accesso negato e invita a chiedere l'abilitazione all'amministratore del locale.

## 3. Login e primo accesso

La pagina di login e unica per tutti.

### Primo avvio piattaforma

Se il sistema non ha ancora un super admin attivo:

- compare la schermata `Bootstrap`
- viene mostrato l'identificativo del super admin principale
- devi impostare la password iniziale

Completato questo passaggio, il super admin entra nella console admin.

### Accesso ordinario

Per l'accesso quotidiano:

- inserisci username oppure email
- inserisci la password
- premi `Entra nel portale`

Il sistema usa la stessa pagina sia per il super admin sia per gli admin dei singoli locali.

## 4. Struttura del workspace locale

Per un locale autenticato, il portale ruota attorno a queste aree:

- `Home`
- `Strumenti`
- `Ordini`
- `Prenotazioni`
- `Documenti`
- `Menu`
- `Homemade`
- `Account`

La disponibilita reale dipende dal ruolo e dai permessi.

## 5. Home del locale

La Home e la chat operativa principale del locale.

### Cosa fa

La Home serve per:

- fare domande operative al gestionale
- leggere dati reali del tenant attivo
- chiedere supporto su ordini, prenotazioni, documenti e stato del locale

### Come si usa

- scrivi una richiesta nell'area di testo
- premi invio oppure il pulsante di invio
- attendi la risposta dell'assistente

### Nuova chat

Quando vuoi azzerare il contesto:

- usa il pulsante `Nuova chat`

Questo pulisce la conversazione lato utente e chiede al backend di chiudere il thread corrente.

### Permessi

- admin locale e super admin possono usare la Home
- i dipendenti possono usarla solo se hanno il permesso `assistant`

## 6. Strumenti

La pagina `Strumenti` e il contenitore degli strumenti trasversali del locale.

Stato attuale:

- oggi contiene il tool `Documenti fiscali`

Per i dipendenti, `Strumenti` e visibile solo se hanno il permesso `fiscal_documents`.

## 7. Documenti fiscali

Percorso: `Strumenti > Documenti fiscali`

Questa pagina serve a gestire fatture e bolle del locale.

### A cosa serve

Permette di:

- caricare documenti fiscali a mano
- archiviare fatture e DDT per fornitore
- configurare la mailbox dedicata ai documenti
- collegare Google per leggere la casella email
- sincronizzare gli allegati in arrivo
- filtrare e rivedere i documenti archiviati

### Sezione statistiche

In alto trovi il riepilogo di:

- totale documenti
- numero fatture
- numero bolle
- documenti da verificare

### Caricamento manuale

Usa `Carica documenti fiscali` per importare file locali.

Formati previsti:

- `pdf`
- `png`
- `jpg`
- `jpeg`
- `txt`
- `md`
- `csv`

### Mailbox fornitori

La sezione `Casella di ricezione documenti` serve a salvare l'indirizzo email usato dai fornitori.

Puoi:

- inserire l'email dedicata a bolle e fatture
- premere `Salva mailbox`
- rimuovere l'indirizzo con `Rimuovi mailbox`

### Collegamento Google e sync inbox

La sezione `Stato lettura mailbox` serve a predisporre l'ingestione automatica.

Qui puoi:

- collegare o ricollegare Google
- verificare se il permesso Gmail e attivo
- controllare se mailbox e account Google coincidono
- lanciare `Sincronizza inbox`

Se la configurazione non e pronta, la pagina mostra il prossimo passo da fare.

### Archivio documenti

Nella parte archivio puoi:

- filtrare per `Tutti`
- filtrare per `Fatture`
- filtrare per `Bolle`
- filtrare per `Da verificare`
- selezionare un documento
- consultare dettaglio e dati estratti
- scaricare il file selezionato

### Nota importante

La pagina e gia pronta come base operativa, ma il confronto automatico ordine-bolla-fattura e ancora un'area in evoluzione. Il modulo oggi archivia, classifica e prepara il dato.

## 8. Documenti

Percorso: `Documenti`

Questa pagina serve a generare file su Google Workspace partendo da una richiesta in linguaggio naturale.

Per i dipendenti, l'accesso dipende dal permesso `documents`.

### Cosa puo creare

- `Google Doc`
- `Google Sheet`

### Flusso corretto

1. collega Google
2. scegli il tipo documento
3. descrivi cosa vuoi creare
4. genera l'anteprima
5. controlla contenuto, titolo e cartella
6. conferma il salvataggio su Google

### Collegamento Google

Nella barra alta della pagina vedi:

- email account collegato
- stato della connessione
- pulsante per collegare o ricollegare Google
- pulsante per scollegare l'account

### Generazione anteprima

Nel blocco `Cosa vuoi creare?`:

- scegli `Google Doc` o `Google Sheet`
- scrivi il brief nel campo `Descrizione`
- premi `Genera anteprima`

### Modifica titolo e cartella

Una volta generata la preview puoi:

- cambiare il nome file
- indicare il nome cartella Drive

Se la cartella non esiste, il sistema la prepara automaticamente.

### Salvataggio finale

Premi `Conferma e salva su Google`.

Alla fine la pagina mostra:

- titolo creato
- account Google usato
- link `Apri su Google`

## 9. Ordini

Percorso: `Ordini`

Il modulo `Ordini` gestisce:

- catalogo prodotti
- ordine in corso
- ordine sospeso
- storico batch
- archivio e confronti
- note condivise
- monitoraggio obiettivi

### Accesso al modulo

Se apri `Ordini` dal portale:

- il modulo eredita la sessione del tenant
- non richiede un secondo login

Se apri il modulo fuori dal portale:

- puo chiedere login diretto con credenziali del locale

### Sezione Prodotti

Nel menu `Prodotti` trovi:

- `Importa CSV in SQL`
- `Importa catalogo fornitore`
- `Modifica prodotti`
- `Aggiungi prodotto`

#### Importa CSV in SQL

Serve a caricare un catalogo prodotti da file CSV.

#### Importa catalogo fornitore

Serve a importare un listino esterno e riconciliarlo con il catalogo del tenant.

#### Modifica prodotti

Apre l'editor catalogo.

Da qui puoi:

- cercare un prodotto
- aprirne la scheda
- modificare nome, lotto, fornitore, codice, prezzo, IVA, categoria, note, peso, litri e unita per pack

#### Aggiungi prodotto

Serve a creare manualmente un nuovo articolo di catalogo.

Campi tipici:

- prodotto
- lotto
- fornitore
- codice prodotto
- prezzo finale ivato
- IVA
- peso o unita di misura
- prezzo al kg
- categoria
- note
- unita per pack
- litri per unita

### Ordine in lavorazione

Nella sezione operativa centrale trovi:

- `Conferma ordine`
- `Ordine in corso`
- `Azzera quantita`
- `Riepilogo fornitori`
- totale stimato ordine

### Compilazione ordine

Nella tabella prodotti puoi:

- cercare per nome, codice, lotto o fornitore
- scegliere il lotto
- inserire la quantita

Il sistema aggiorna:

- numero selezioni
- totale stimato
- riepilogo fornitore

Quando il lotto cambia, il modulo usa il lotto selezionato anche per il prezzo stimato della riga e del totale.

### Ordine in corso

Il menu `Ordine in corso` contiene:

- `Sospendi ordine`
- `Carica ordine sospeso`
- `Cancella ordine sospeso`

Serve a mettere in pausa un lavoro non ancora confermato.

### Conferma ordine

Premendo `Conferma ordine`:

- il sistema valida i prodotti selezionati
- apre un riepilogo raggruppato per fornitore
- salva il batch nello storico

### Riepilogo fornitori

Mostra l'ordine raggruppato per fornitore con:

- righe selezionate
- quantita
- prezzi disponibili
- totale stimato per fornitore

### Storico

Nel menu `Storico` trovi:

- `Confronto annuale`
- `Ultimo ordine`
- `Archivio`
- `Esporta CSV`
- `Obiettivi`

#### Confronto annuale

Confronta l'anno selezionato con quello precedente e mostra:

- totale articoli
- delta assoluto
- delta percentuale
- dettaglio per prodotto

#### Ultimo ordine

Mostra l'ultimo batch salvato.

#### Archivio

L'archivio ha due viste:

- `Giornaliero`
- `Totali`

Puoi anche:

- cambiare anno
- filtrare per data, prodotto, fornitore o lotto

Nel tab `Giornaliero` vedi i singoli batch.

Nel tab `Totali` vedi i totali aggregati per prodotto.

Il filtro nei `Totali` oggi lavora sulle righe prodotto, non solo sugli ordini che le contengono.

#### Modifica / Storna ordine storico

Da `Archivio`, ogni batch ha il pulsante `Modifica / Storna`.

Comportamento attuale corretto:

- l'ordine storico viene caricato in modalita modifica
- non viene trasformato in un nuovo ordine con data del giorno
- quando confermi, viene aggiornato lo stesso batch esistente
- la data originale dell'ordine viene mantenuta

Durante questa modalita compare un banner dedicato.

Se vuoi uscire senza salvare:

- usa `Annulla modifica storico`

#### Esporta CSV

Scarica lo storico dell'anno selezionato in formato CSV.

#### Obiettivi

La schermata `Obiettivi` mostra gli obiettivi stagionali gia configurati per l'anno selezionato.

La UI ordini oggi e pensata soprattutto per monitoraggio, non per la creazione manuale degli obiettivi.

### Note condivise

Il pulsante `Note condivise` apre il blocco note del team.

Funzioni disponibili:

- visualizzare tutte le note
- aggiungere una nuova nota
- eliminare una nota

Se ci sono note presenti, il pulsante mostra un badge con il numero totale.

## 10. Prenotazioni

Percorso: `Prenotazioni`

Il modulo prenotazioni e separato dal portale ma integrato al tenant attivo.

Aree principali:

- `Cruscotto`
- `Prenotazioni`
- `Editor`
- `Piantina`
- `WhatsApp`

Se il modulo e stato aperto dal portale, compare anche il link `Home`.

### Cruscotto

Il cruscotto mostra la panoramica giornaliera.

Informazioni tipiche:

- totale prenotazioni del giorno
- confermate
- in attesa
- senza tavolo
- timeline del servizio
- stanze e stato operativo

Azioni rapide:

- nuova prenotazione
- apri gestione prenotazioni
- apri piantina
- apri WhatsApp
- apri editor tavoli se sei da PC

### Agenda prenotazioni

La pagina `Prenotazioni` serve alla gestione del servizio.

Permette di:

- filtrare per data
- filtrare per stato
- vedere assegnazioni e tavoli
- ricalcolare le assegnazioni
- riassegnare una singola prenotazione
- modificare una prenotazione
- cancellare una prenotazione

Il sistema conserva la prenotazione anche se non trova subito un tavolo adatto.

### Nuova prenotazione

Dal cruscotto o dalla lista puoi aprire il form di nuova prenotazione.

I dati chiave sono:

- nome cliente
- telefono
- email
- data
- ora
- durata
- coperti
- stato
- origine
- preferenza area
- note

### Piantina operativa

La pagina `Piantina` e la vista sala del giorno.

Serve a:

- vedere la distribuzione dei tavoli
- cambiare data
- cambiare sala
- controllare occupazione
- leggere le prenotazioni che richiedono unione tavoli

### Editor piantina

La pagina `Editor` e disponibile solo da PC.

Serve a costruire e modificare la sala:

- aree
- tavoli
- foto di sfondo
- banco
- entrata
- dimensioni in metri
- posizione degli elementi

Funzioni tipiche:

- `Nuova area`
- `Nuovo tavolo`
- `Salva area attiva`
- modifica diretta in mappa
- dettagli tavolo selezionato
- `Salva dettagli tavolo`
- `Elimina tavolo`

### WhatsApp prenotazioni

La pagina `WhatsApp` e dedicata solo al canale prenotazioni del locale.

Permette di:

- verificare lo stato della linea WhatsApp
- validare la configurazione
- inserire Phone Number ID
- salvare o sostituire il token
- impostare il prompt aggiuntivo del canale prenotazioni
- inviare un messaggio di test
- consultare lo storico log del canale

Questa area non e un assistente generico del locale: il suo perimetro e prenotazioni.

## 11. Menu

Percorso: `Menu`

Il modulo `Menu` e il concierge digitale del locale per carta, cocktail list e focus vendita.

### Uso base

La schermata principale e una chat.

Puoi:

- scrivere una richiesta
- inviare il messaggio
- aprire `Nuova chat` per azzerare il contesto
- usare i pulsanti `Visualizza menu completo` e `Visualizza cocktail list`

### Configura menu

Il pulsante `Configura menu` apre il pannello impostazioni.

### Configurazione locale

Nel pannello locale puoi:

- impostare `Cosa vuoi spingere nella vendita?`
- caricare file, foto o PDF
- scattare foto
- vedere lo stato dei materiali caricati
- rinominare o eliminare i file caricati
- leggere la `Sintesi automatica usata dal prompt`
- usare il pulsante `Modifica` per espandere e modificare la sintesi testuale generata
- salvare la configurazione del locale

### Configurazione tecnica

La parte tecnica del pannello e pensata per test e amministrazione del servizio, non per l'uso quotidiano del gestore.

Include:

- modello
- host API
- porta
- endpoint
- temperatura
- system prompt

### Permessi

Se l'utente non ha accesso a `Menu`, il modulo mostra un messaggio esplicito e non consente l'uso della chat.

## 12. Account

Percorso: `Account`

Questa pagina serve all'admin locale per gestire i profili del team.

Per i dipendenti standard, questa area non e disponibile.

### Cosa mostra

- admin principale del locale
- numero sotto-account creati
- nome del locale corrente

### Creazione sotto-account

Per creare un dipendente devi inserire:

- nome
- username
- email
- telefono
- password iniziale
- permessi da assegnare

Permessi selezionabili:

- Assistente
- Prenotazioni
- Menu
- Homemade
- Ordini
- Documenti
- Documenti fiscali

### Modifica sotto-account

Su un sotto-account esistente puoi:

- cambiare dati anagrafici
- cambiare username
- cambiare email
- cambiare telefono
- impostare una nuova password
- aggiungere o togliere permessi
- eliminare il profilo

### Regola importante

La Home del locale resta sempre disponibile ai dipendenti.

Il resto viene governato dai permessi selezionati in questa pagina.

## 13. Console super admin

Percorso: `Admin`

Questa pagina e riservata al super admin non impersonato.

### Funzioni principali

- creare un nuovo locale e il suo admin principale
- vedere quanti tenant esistono
- vedere quanti moduli sono attivi
- aggiornare i dati di un locale
- cambiare la password del super admin
- entrare dentro un tenant specifico

### Creazione nuovo locale

La console richiede:

- nome locale
- nome admin cliente
- username admin
- email admin
- telefono locale
- numero WhatsApp locale
- indirizzo
- password iniziale admin cliente

### Ingresso nel tenant

Il super admin puo entrare in un locale e lavorare nel suo workspace.

Quando non e impersonato, resta nella console admin.

## 14. Homemade

Percorso: `Homemade`

Stato attuale del modulo:

- presente nel catalogo
- previsto nel sistema permessi
- non ancora implementato come vero modulo operativo

Non va trattato come area completa: oggi e un placeholder architetturale.

## 15. Regole pratiche consigliate

- usa `Nuova chat` quando vuoi azzerare il contesto dell'assistente
- per i dipendenti assegna solo i permessi realmente necessari
- in `Ordini`, usa `Modifica / Storna` per correggere uno storico senza perdere la data originale
- in `Documenti`, controlla sempre la preview prima del salvataggio su Google
- in `Documenti fiscali`, salva prima la mailbox corretta del locale e poi collega Google
- in `Prenotazioni`, usa l'editor piantina da PC
- in `Menu`, tratta la sezione tecnica come area di test, non come configurazione operativa normale

## 16. Limiti attuali da conoscere

- `Homemade` non e ancora un modulo di lavoro completo
- `Strumenti` oggi contiene solo `Documenti fiscali`
- la parte `Obiettivi` del modulo `Ordini` e focalizzata soprattutto sulla lettura e il monitoraggio
- il canale WhatsApp del modulo `Prenotazioni` resta confinato al dominio prenotazioni
- la parte di confronto automatico completo tra ordini, bolle e fatture e ancora in costruzione

## 17. Suggerimento per la prossima versione del manuale

Questo file e una base operativa completa. La versione successiva sensata e:

- aggiungere screenshot reali schermata per schermata
- aggiungere esempi d'uso per ciascun ruolo
- affiancare una mini guida rapida da una pagina per il personale di sala