# Preventivi 1-Click

Manuale utente completo — crea, invia e gestisci preventivi professionali direttamente dal tuo PC, senza abbonamenti e senza cloud.

## 🚀 Installazione e avvio

Il programma non richiede l'installazione di Python né di altri software. Tutto viene scaricato automaticamente dal file di setup.

### Prima installazione (una sola volta)

1. Copia la cartella `preventivi_app` in una posizione a tua scelta sul PC (es. `C:\Lavoro\preventivi_app` oppure sul Desktop).
2. Esegui `SETUP.bat` — fai doppio clic sul file.
   Il setup scarica automaticamente Python portatile (~10 MB) e installa tutte le librerie necessarie.
   Connessione internet richiesta solo durante il setup.
3. Attendi il messaggio "SETUP COMPLETATO CON SUCCESSO" e premi un tasto.

💡
Il setup scarica Python nella cartella `python_embed\` all'interno di `preventivi_app`. Non tocca il resto del sistema, non modifica il registro di Windows, non richiede privilegi di amministratore.

### Avvio quotidiano

1. Fai doppio clic su `AVVIA.bat` nella cartella del programma.
2. Si apre la finestra dell'applicazione. Puoi creare un collegamento a `AVVIA.bat` sul Desktop per averlo sempre a portata di mano (clic destro → Invia a → Desktop come collegamento).

⚠️
Antivirus: i file `.bat` potrebbero essere segnalati alla prima esecuzione. Sono file di testo puri, aprili con Blocco Note per verificarne il contenuto prima di eseguirli. Non contengono codice malevolo.

### Aggiornare le librerie

Se in futuro hai bisogno di aggiornare le dipendenze, esegui nuovamente `SETUP.bat`: rileva Python già installato e aggiorna solo le librerie.

## 🖥️ Interfaccia

La finestra è divisa in due aree principali:

Area | Descrizione
--- | ---
Sidebar sinistra | Navigazione tra le sezioni del programma
Barra superiore (topbar) | Titolo della pagina corrente, barra di ricerca globale, pulsanti azione
Area principale | Contenuto della sezione selezionata

### Voci della sidebar

Voce | Funzione
--- | ---
Dashboard | Panoramica statistiche e lista preventivi
+ Nuovo Preventivo | Crea un preventivo da zero
Clienti | Rubrica clienti
Prodotti | Catalogo prodotti e servizi
Template | Modelli di preventivo riutilizzabili
Impostazioni | Dati azienda, email SMTP, colori PDF, backup

## ⚙️ Impostazioni iniziali

Prima di creare il primo preventivo, vai su Impostazioni (ultima voce nella sidebar) e compila i dati.

### La tua azienda

Campo | Dove appare
--- | ---
Nome azienda / Professionista | Intestazione PDF, firma email
Email | Intestazione PDF
Telefono | Intestazione PDF, messaggio WhatsApp
Indirizzo | Sezione "DA" nel PDF
P.IVA | Piè di pagina PDF

### Email (SMTP)

Necessario per inviare preventivi via email direttamente dall'app.

Campo | Valore per Gmail | Valore per altri provider
--- | --- | ---
Host SMTP | `smtp.gmail.com` | chiedi al tuo provider
Porta | `587` | solitamente 587 o 465
Email mittente | la tua email | la tua email
Password | App Password (vedi sotto) | password email

📱
Come ottenere l'App Password Gmail:
Account Google → Sicurezza → Verifica in due passaggi (deve essere attiva) → Password per le app → crea una password per "Preventivi" → copia il codice di 16 caratteri.

### Numerazione preventivi

Il campo Prefisso determina il formato del numero automatico. Esempi:

Prefisso | Risultato
--- | ---
`PREV` | PREV-2025-0001, PREV-2025-0002 …
`FDM` | FDM-2025-0001, FDM-2025-0002 …
`Q` | Q-2025-0001, Q-2025-0002 …

### Personalizzazione PDF

- Colore principale — colore dell'intestazione e del totale (clicca il quadratino colorato o digita un codice esadecimale es. `#E63946`)
- Lingua PDF — Italiano 🇮🇹 o English 🇬🇧 (cambia le etichette nel documento)

### Logo aziendale

1. Prepara un file PNG con sfondo trasparente (consigliato) o JPG, dimensione massima 2 MB.
2. In Impostazioni → Logo aziendale, clicca Scegli file e seleziona il tuo logo.
3. Clicca 📤 Carica logo. Il logo apparirà nella sidebar e nell'intestazione del PDF.

## 📝 Creare un preventivo

Clicca + Nuovo Preventivo nella sidebar o il pulsante verde in dashboard.

### Passo 1 — Cliente e Template

- Cliente — scegli dalla lista oppure clicca + Nuovo cliente per crearne uno al volo senza perdere il lavoro
- Template — scegli il modello (determina IVA%, testo introduttivo, note finali, giorni di validità)

### Passo 2 — Dettagli

Campo | Descrizione | Compare nel PDF?
--- | --- | ---
Titolo / Oggetto | Es. "Realizzazione sito web" | Sì
Note visibili nel PDF | Condizioni, tempistiche, garanzie per il cliente | Sì
Note interne | Appunti interni: margini, contatti, riferimenti | No

### Passo 3 — Voci del preventivo

Ogni riga della tabella è un prodotto o servizio.

Colonna | Descrizione
--- | ---
Descrizione | Testo della voce (con autocomplete dal catalogo)
Qtà | Quantità, anche decimale (es. 2.5 ore)
Prezzo unit. | Prezzo unitario in euro
Sc.% | Sconto sulla singola riga (0 = nessuno sconto)
Totale | Calcolato automaticamente

Pulsanti riga: `⎘` duplica la riga | `✕` rimuove la riga

Aggiungere voci:

- 📦 Da catalogo — apre il catalogo prodotti; clicca un prodotto per aggiungerlo
- + Aggiungi voce — riga vuota da compilare
- Autocomplete — inizia a scrivere nella descrizione; appaiono suggerimenti dal catalogo in tempo reale; clicca per selezionare e compilare prezzo automaticamente

### Passo 4 — Opzioni e Riepilogo

Campo | Descrizione
--- | ---
Sconto globale (%) | Sconto sull'intero subtotale (si somma agli sconti per riga)
IVA (%) | Ereditata dal template (modifica nel template per cambiare)
Giorni di validità | Sovrascrive il valore del template per questo preventivo
Acconto ricevuto (€) | Se hai già incassato un acconto; l'app mostrerà il saldo residuo
Numero manuale | Lascia vuoto per numerazione automatica; riempi per forzare un numero specifico

### Passo 5 — Salva

Clicca Crea Preventivo. Il preventivo viene salvato come Bozza.

## 📋 Gestire un preventivo

Clicca sul numero del preventivo in dashboard per aprire il dettaglio.

### Intestazione del dettaglio

In alto a destra trovi sempre: totale, acconto ricevuto (se presente) e saldo residuo.

### Invio rapido

Pulsante | Cosa fa
--- | ---
💬 Invia su WhatsApp | Apre WhatsApp Web con messaggio precompilato (nome cliente, numero, totale); salva anche il PDF sul Desktop per allegarlo manualmente
📧 Invia Email + PDF | Invia email con PDF allegato all'indirizzo del cliente (SMTP necessario)
📄 Scarica PDF | Salva il PDF direttamente sul Desktop con il nome `Preventivo_NUMERO.pdf`

### Accettazione

Quando il cliente accetta, clicca Segna come Accettato: lo stato diventa Firmato e viene registrata data e ora. Il PDF mostrerà la dicitura di accettazione.

### Cambio stato manuale

Usa il menu a tendina per impostare lo stato:

- Bozza — in preparazione, non ancora inviato
- Inviato — inviato al cliente
- Firmato — accettato dal cliente
- Rifiutato — non andato a buon fine

Aggiungi una nota opzionale al cambio stato per documentarne il motivo (es. "Cliente ha chiesto revisione prezzi").

### Storico stati

Clicca Mostra nel pannello Storico per vedere la cronologia completa: ogni cambio di stato con data, ora e nota. Include anche l'invio via WhatsApp o email.

### Anteprima PDF

Clicca Mostra nel pannello Anteprima PDF per vedere il documento direttamente nell'app senza scaricarlo.

### Altre azioni

Azione | Descrizione
--- | ---
✏️ Modifica | Torna al form di modifica
📋 Duplica | Crea una copia identica con stato Bozza e nuovo numero
🗑️ Elimina | Elimina definitivamente (irreversibile)

## 📊 Dashboard

### Statistiche in tempo reale

Indicatore | Significato
--- | ---
Preventivi totali | Numero totale di preventivi nel sistema
Bozze | Preventivi ancora in preparazione
Inviati | Preventivi spediti al cliente e in attesa di risposta
Accettati | Preventivi firmati/confermati
Valore pipeline | Somma in euro dei preventivi inviati + firmati

### Grafico andamento mensile

Clicca Mostra nel pannello "Andamento mensile" per vedere il grafico degli ultimi 6 mesi con:

- Barre blu — valore totale dei preventivi emessi per mese
- Linea grigia — numero totale preventivi
- Linea verde — numero preventivi firmati

### Filtri e ricerca preventivi

- Cerca — filtra per numero, nome cliente o titolo
- Tutti / Bozze / Inviati / Firmati — filtra per stato

### Badge scadenza automatici

I preventivi in stato Inviato mostrano automaticamente:

- ⏰ scade in Ng — scade entro 3 giorni
- ⚠️ scaduto — data di validità superata

### Export Excel

Clicca il pulsante Excel in alto a destra per esportare la lista corrente (con filtri applicati) in formato `.xlsx`. Il file viene salvato automaticamente sul Desktop con il nome `preventivi_export_YYYYMMDD_HHMMSS.xlsx` e compare un messaggio di conferma verde.

## 🔍 Ricerca globale

La barra "Cerca tutto…" in cima a ogni pagina cerca simultaneamente in:

- Preventivi (numero, titolo, nome cliente)
- Clienti (nome, email, telefono)
- Prodotti / servizi (nome, descrizione)

I risultati appaiono in una pagina dedicata, raggruppati per categoria, con link diretto a ogni elemento.

## 👥 Clienti

Vai su Clienti nella sidebar per gestire la rubrica.

### Aggiungere un cliente

Clicca + Nuovo Cliente e compila i campi:

- Nome (obbligatorio)
- Email, Telefono, Indirizzo, P.IVA, Note

### Azioni sulla lista clienti

Pulsante | Azione
--- | ---
✏️ Modifica | Modifica i dati del cliente
📋 (icona) | Duplica il cliente — utile per aziende con più referenti
🗑️ (icona) | Elimina il cliente (non elimina i preventivi già creati)

💡
Puoi aggiungere un cliente anche durante la compilazione di un preventivo: clicca + Nuovo cliente nel form e, dopo il salvataggio, ritorni automaticamente al preventivo.

## 📦 Catalogo Prodotti

Il catalogo ti permette di salvare i prodotti e servizi che usi più spesso, per inserirli nei preventivi con un clic senza dover riscrivere ogni volta.

### Aggiungere un prodotto

Clicca + Nuovo Prodotto e compila:

Campo | Descrizione
--- | ---
Nome | Nome breve usato per la ricerca (es. "Consulenza oraria")
Descrizione | Testo esteso che comparirà nella voce del preventivo
Prezzo default | Prezzo unitario suggerito (modificabile nel preventivo)
Unità di misura | pz, ora, mq, kg, ecc.
Categoria | Per raggruppare i prodotti nel catalogo
Attivo | Se disattivato, non appare nei suggerimenti del preventivo

### Usare il catalogo durante un preventivo

Due metodi:

- Pulsante "📦 Da catalogo" — apre una finestra con ricerca e lista; clic sul prodotto per aggiungerlo come voce
- Autocomplete — inizia a scrivere nella colonna Descrizione; compaiono suggerimenti in tempo reale; clic per selezionare (compila anche il prezzo automaticamente)

## 📄 Template

I template definiscono le impostazioni di default per i preventivi. Puoi averne quanti vuoi (es. uno per lavori standard, uno per urgenze, uno per forfait annuali).

### Campi del template

Campo | Descrizione
--- | ---
Nome | Es. "Standard", "Urgente +20%", "Privati senza IVA"
Testo introduttivo | Paragrafo di apertura nel PDF ("Gentile Cliente, …")
Note finali | Testo in fondo al PDF (condizioni generali, modalità di pagamento, ecc.)
Valuta | EUR o altra valuta
Giorni di validità | Scadenza default (modificabile sul singolo preventivo)
IVA % | Aliquota IVA (22%, 10%, 4%, 0%, ecc.)

## 🖨️ Il PDF del preventivo

Il PDF viene generato automaticamente quando clicchi "Scarica PDF" o "Invia Email".

### Struttura del documento

#### Intestazione

- Barra colorata (colore brand) con logo, nome azienda e contatti
- Numero e tipo documento (PREVENTIVO in IT, QUOTE in EN)
- Data emissione e data di scadenza
- Sezione DA (tuoi dati) e A (dati cliente con P.IVA se presente)
- Testo introduttivo del template

#### Corpo

- Tabella voci: descrizione, qtà, prezzo, colonna sconto (appare solo se almeno una riga ha sconto), totale riga
- Riepilogo: subtotale, sconto globale (se presente), IVA, TOTALE in evidenza colorata
- Note visibili al cliente (le note interne NON appaiono)
- Note finali del template

#### Piè di pagina

- P.IVA aziendale (o indirizzo) a sinistra
- Numero pagina a destra
- Spazio firma manuale del cliente (se non ancora accettato)
- Data e ora di accettazione (se già firmato)

## 💾 Backup e Ripristino

### Eseguire un backup

1. Vai su Impostazioni → sezione Backup database.
2. Inserisci il percorso cartella di destinazione oppure lascia vuoto per salvare automaticamente in `Desktop\Preventivi_Backup\`.
3. Clicca 📦 Esegui backup ora. Viene creato il file `preventivi_backup_YYYYMMDD_HHMMSS.db`.

✅
Consiglio: esegui un backup prima di ogni aggiornamento del programma o almeno una volta a settimana se usi il programma intensivamente.

### Ripristinare un backup

1. Vai su Impostazioni → sezione Ripristina backup.
2. Clicca Scegli file e seleziona un file `.db` di backup precedente.
3. Clicca ♻️ Ripristina e conferma il dialogo.

⚠️
Attenzione: il ripristino sovrascrive tutti i dati correnti (preventivi, clienti, prodotti, impostazioni). Esegui sempre un backup dei dati attuali prima di ripristinare.

## ❓ Domande frequenti

### Il PDF mostra caratteri strani o manca il simbolo €

L'app usa il font Arial di sistema. Verifica che `C:\Windows\Fonts\arial.ttf` esista. In caso contrario, installa Arial o Calibri su Windows.

### Non riesco a inviare email

Per Gmail, usa l'App Password (non la password dell'account). La verifica in due passaggi deve essere attiva. Verifica Host (`smtp.gmail.com`), Porta (`587`) e che nessun firewall blocchi la porta.

### Come cambio il colore del PDF?

Impostazioni → PDF Personalizzazione → usa il selettore colore o digita un codice esadecimale (es. `#16A34A` per verde).

### Il numero automatico salta dei numeri, è normale?

Sì, se hai eliminato preventivi. La numerazione è progressiva sui preventivi esistenti nell'anno. Per numeri specifici usa il campo "Numero manuale" alla creazione.

### Posso usare il programma su più computer?

Sì: copia l'intera cartella `preventivi_app` sull'altro PC (incluso `preventivi.db` e `python_embed`). Sul nuovo PC non serve rieseguire il setup. Per sincronizzare i dati usa backup manuale + ripristino.

### Posso modificare un preventivo già inviato?

Sì. Lo stato resta "inviato" ma i dati vengono aggiornati. Se rigeneri o reinvii il PDF, sarà la versione aggiornata.

### Come rimuovo il logo?

Impostazioni → Logo aziendale → clicca 🗑️ Rimuovi logo.

## 📁 Struttura dei file

    preventivi_app/
    ├── AVVIA.bat              ← avvia il programma (uso quotidiano)
    ├── SETUP.bat              ← installazione una-tantum
    ├── main.py                ← punto di ingresso dell'app
    ├── app.py                 ← logica web (Flask)
    ├── db.py                  ← gestione database (SQLite)
    ├── pdf_gen.py             ← generazione PDF (fpdf2)
    ├── email_utils.py         ← invio email (SMTP)
    ├── preventivi.db          ← il tuo database (generato automaticamente)
    ├── requirements.txt       ← lista librerie Python necessarie
    ├── MANUALE_UTENTE.html    ← questo documento
    ├── python_embed/          ← Python portatile (creato dal SETUP)
    ├── static/
    │   └── uploads/           ← logo aziendale caricato
    └── templates/             ← pagine HTML dell'interfaccia

💾
Il file preventivi.db contiene tutti i tuoi dati. Includilo sempre nei backup. Non eliminarlo mai.

Preventivi 1-Click — Manuale Utente v2.0 · Uso locale e privato