Manuale Professionale Completo

Questo manuale spiega il perché e il come interni. Per la guida d'uso passo dopo passo, vedi il Manuale Utente.

1. Architettura generale

Ledyvas è un'applicazione desktop costruita su Electron. Gira al 100% sulla macchina del cliente — non c'è un server applicativo né un database in cloud. L'unica cosa che Ledyvas interroga via internet è un server di licenze (un Cloudflare Worker), e solo ogni tanto.

• Processo principale: avvia l'app, convalida la licenza, apre il database e collega ogni modulo prima di mostrare l'interfaccia.
• Interfaccia: HTML/CSS/JavaScript senza framework. Ogni schermata è una vista caricata su richiesta durante la navigazione.
• Ponte unico: l'interfaccia non tocca mai il database direttamente. Tutto passa da uno strato di servizi con validazione, transazioni e calcoli.
• Modalità portatile: il database vive in una cartella Data accanto all'eseguibile. Puoi copiare l'intera cartella su un altro computer o su un disco esterno.

2. Licenza e cifratura

Ledyvas si attiva con un codice di licenza contro il server di licenze. La convalida usa la firma crittografica asimmetrica (Ed25519): la chiave privata vive solo sul server, quindi l'app non potrebbe falsificare una licenza nemmeno se qualcuno la decompilasse.

• Margine offline: dopo l'attivazione, Ledyvas funziona diversi giorni senza connessione. Si riconvalida in background ogni volta che c'è internet. Solo se il margine scade e non c'è connessione l'app chiede di ricollegarsi.
• Trasferimento: la licenza può essere spostata su un'altra macchina. Il server impone una sola macchina attiva alla volta (impronta hardware); attivando su un nuovo PC si disattiva il precedente.
• Database cifrato: il file opshield.db è cifrato. La chiave si deriva dal codice di licenza con PBKDF2 a 210.000 iterazioni (standard OWASP). Se il portatile viene rubato, nessuno apre il database senza la licenza. Poiché la chiave viaggia con la licenza e non con l'hardware, la stessa licenza riattivata su un altro PC riapre lo stesso file — per questo puoi spostare la cartella tra computer.

3. Database e migrazioni

Ledyvas usa un unico file SQLite. Lo schema evolve attraverso migrazioni numerate e ordinate: ogni aggiornamento dell'app porta nuove migrazioni che si applicano da sole, una volta, al primo avvio, dentro la propria transazione. Una migrazione già applicata non viene mai modificata; se ne aggiunge una nuova.

All'avvio, Ledyvas fa anche un checkpoint del write-ahead log (WAL) e lo ripete in background ogni tanto — questo evita che il file di lavoro cresca senza limiti nelle sessioni lunghe.

4. Catalogo e relazioni

Il catalogo è la base di tutto. Viene caricato una volta e referenziato in ogni operazione successiva dal suo identificatore interno stabile, mai dal nome — per questo puoi rinominare un prodotto, una destinazione o una categoria in qualsiasi momento senza rompere lo storico.

Entità	Ruolo	Si relaziona con
Prodotto	Un articolo comprato, venduto o prodotto. Ha categoria, sottocategoria, unità, costo, codice a barre.	Acquisti, Vendite, Ricette, Formula, Magazzino
Categoria / Sottocategoria	Classificano il prodotto. Definiscono il raggruppamento in Acquisto/Magazzino e a quale "famiglia" appartiene (Alimenti, Bevande, Monouso, Carburante…).	Prodotto, Formula, Consolidati
Fornitore	Da chi compri. Può avere una lista di prodotti forniti con il costo (riferimento).	Acquisto
Cliente	A chi vendi. Se "rivenditore", ha una giacenza propria.	Vendita al Consumatore, Destinazione
Destinazione	Un punto di distribuzione. Può avere un cliente-rivenditore collegato e un prezzo di vendita per PAX.	Formula, Centro Logistico, Margine per Destinazione
Mezzo	Veicolo o imbarcazione. Tipo (barca/terrestre) e gruppo (azienda/noleggiato).	Carburante, Consolidato Flotte

5. Il motore Formula-per-PAX

Solo con la Modalità Escursione attiva. La Formula traduce "quante persone servirai" in "quanto comprare e spedire".

1. Si configura una matrice di Valore: per ogni combinazione prodotto × destinazione, quanto consuma una persona (es. 0,25 kg di riso per PAX alla destinazione X).
2. Ogni giorno si inserisce il PAX per destinazione.
3. Il calcolo produce, per riga (destinazione × prodotto): Richiesta = Valore × PAX.
4. Dalla Richiesta si sottraggono tre rettifiche inserite per destinazione: Giacenza (ciò che la destinazione ha già), Reso (ciò che ha restituito) e Inventario in Spiaggia (conteggio fisico sul punto). Il risultato è la Spedizione di quella riga (mai negativa).
5. Per sapere quanto comprare in totale, si somma la Spedizione di tutte le destinazioni di ogni prodotto (arrotondando ogni riga per eccesso, perché non si consegna una frazione a un ristorante) e si sottrae una sola volta la Giacenza di Magazzino (giacenza condivisa già presente nel Centro Logistico).

Acquisto Assistito A (Alimenti) e B (Bevande) eseguono solo questo calcolo — sono una proposta. Non generano alcun acquisto reale e non toccano il magazzino. La schermata Acquisto è l'unica che conferma.

6. Acquisto: come entra la giacenza

La schermata Acquisto è l'unico punto del sistema che genera un acquisto reale. Alla conferma, dentro un'unica transazione atomica:

1. Viene inserito il documento di acquisto (fornitore, data, righe).
2. La quantità viene aggiunta al current_stock di ogni prodotto, in modo sincrono.
3. Viene registrato un movimento nello storico (stock_movements) con prodotto, quantità, costo, data e utente — tracciabilità completa.
4. Il modulo Controllo Giornaliero viene sincronizzato per quel giorno/categoria.
5. Se il prodotto è Bevande, Monouso o Carburante, si trasferisce da sé al tracciamento interno di quelle categorie dentro il Centro Logistico.

Annullare o modificare un acquisto inverte tutto quanto sopra sulla data originale del documento, non sulla data di oggi. Ledyvas non blocca l'annullamento anche se la giacenza va in negativo (vedi sezione 16).

7. Centro Logistico e le Vendite

Il Centro Logistico è l'unico magazzino del sistema. Da lì vendi/spedisci alle destinazioni. Ogni sezione di vendita (Vendita ai Ristoranti = Alimenti + Monouso; Vendita alle Imbarcazioni = Bevande) ha il proprio PAX, indipendente dal PAX dell'Acquisto — il PAX dell'Acquisto e quello della Vendita non si sovrascrivono a vicenda (comprare e vendere sono processi separati).

Alla conferma di una vendita, per ogni destinazione con qualcosa calcolato viene generato un trasferimento reale: detrae il current_stock, accredita la giacenza del cliente-rivenditore di quella destinazione, e registra il movimento — tutto dentro un'unica transazione (se una destinazione fallisce, tutto viene invertito). La spedizione per destinazione usa la stessa Formula, rettificata da Giacenza / Reso / Inventario in Spiaggia, dell'Acquisto.

La vendita convalida la giacenza e avvisa di cosa manca, ma non impedisce la conferma — l'operazione non viene interrotta.

8. Vendita al Consumatore e giacenza del rivenditore

Ogni cliente segnato come "rivenditore" ha un proprio saldo di giacenza (reseller_stock). Viene accreditato quando il Centro Logistico gli spedisce, e detratto quando quel rivenditore vende al cliente finale nella schermata Vendita al Consumatore.

• Confermare una vendita dal Centro Logistico crea automaticamente una bozza di Vendita al Consumatore per destinazione. La bozza esiste e si può modificare, ma non detrae giacenza finché non viene confermata esplicitamente.
• Le righe di Bevande delle imbarcazioni non hanno un prezzo di vendita proprio (l'incasso del pacchetto per PAX viene registrato una sola volta sul lato Alimenti, per non contare l'introito due volte). Si mostrano come registro di costo, non come perdita.
• Rivendita è solo un report di ciò che è già stato spedito — non genera movimenti.

9. Bevande, Monouso e Carburante

Queste tre famiglie non hanno un magazzino né una schermata separata. Vivono dentro il Centro Logistico con il proprio tracciamento della giacenza:

• Si trasferiscono da sole a quel tracciamento alla conferma di un Acquisto (invece di aggiungersi alla giacenza generale dei prodotti).
• Dal Centro Logistico registri le loro vendite, rettifiche, uscite/consumi e resi, ciascuno con il proprio tipo di movimento e storico.
• Le Bevande si suddividono in Alcoliche / Analcoliche.
• La vista "Resi del Giorno" consolida tutti i resi (Bevande per sottogruppo, Consumabili, Carburante) in un unico posto, e quella giacenza restituita riduce automaticamente il suggerimento di acquisto del giorno dopo.

Nei Consolidati, queste famiglie non si ripartiscono per destinazione: si portano come costo generale (tranne il Monouso, che si spedisce per destinazione — vedi sezione 5).

10. Taniche di carburante

Per attività che, oltre alla giacenza in galloni, gestiscono carburante/olio in taniche fisiche (5, 7, 9, 10 e 18 GL). È un inventario parallelo che si sincronizza da sé con la giacenza in galloni — non bisogna mai inserire nulla due volte.

Operazione	Effetto
Acquisto	Aggiunge taniche (per capacità e quantità esatta, o con un suggerimento di ripartizione ottimale dati i galloni che ti servono) e aggiunge i galloni equivalenti alla giacenza generale.
Vendita / spedizione	Rimuove taniche assegnandole a un mezzo, e rimuove i galloni dalla giacenza.
Reso	Piena (aggiunge tutto), parziale (aggiunge i galloni reali contenuti) o vuota (non aggiunge carburante, restituisce solo il contenitore).
Rettifica	Corregge il conteggio dopo un inventario fisico. Chiede il valore corretto per capacità/stato e un motivo, ed è tracciata.

Ha una propria Chiusura di Giornata (Iniziale + Acquisti − Venduto + Restituito = Finale) e uno storico completo. Il display si può alternare tra Galloni e Litri; ciò che è salvato nel database non cambia mai unità.

11. Controllo Giornaliero

È uno strato di riconciliazione, separato dalla giacenza reale. Registra, per giorno/categoria/prodotto: iniziale, acquisti, spedizioni (per mezzo/destinazione), resi e il conteggio fisico.

Finale calcolato = Iniziale + Acquisti − (Spedito − Restituito). Se è inserito un conteggio fisico, quello è il numero verificato e si usa come iniziale del giorno dopo — così una differenza tra teorico e reale si corregge e non viene trascinata.

Acquisti e spedizioni reali sincronizzano il Controllo Giornaliero automaticamente; si può anche modificare a mano.

12. Come si calcola ogni Consolidato

Riepilogo Giornaliero / Consolidato Operativo

Il costo operativo totale dell'attività nel periodo: l'Acquisto reale confermato (per categoria, con i gruppi Benzina/Olio separati) più i costi manuali configurabili per categoria (affitto, stipendi, commissioni, ecc. — gestiti in Configurazione, non un elenco fisso). Mostra anche: PAX del periodo, spesa totale, costo per PAX, e una tabella statistica PAX Medio per Destinazione (media dei PAX venduti al giorno a ciascuna destinazione, contando solo i giorni con una vendita reale). Quella tabella è puramente informativa — non entra in nessun calcolo di costo.

Margine per Destinazione

Solo Modalità Escursione. Costo, vendite e margine per destinazione, solo per ciò che è passato dal Centro Logistico (trasferimenti reali). Il costo è congelato in ogni trasferimento; le vendite usano il prezzo salvato nel trasferimento. Bevande e Carburante non compaiono per destinazione (si mostrano a parte come "altri costi del periodo").

Consolidato Flotte

Consumo di carburante per mezzo. In modalità settimanale usa una media ponderata per quantità (un giorno di consumo elevato pesa più di uno leggero). Importi in valuta locale o in dollari USA, secondo il tasso configurato.

13. Ricette e Produzione

Una ricetta definisce, per un prodotto finito, quanto di ogni ingrediente serve. L'ingrediente può essere in un'unità diversa da quella del prodotto nel catalogo (grammi nella ricetta, chili in Prodotti) — Ledyvas converte automaticamente per famiglia di unità (peso, volume) prima di calcolare costo e consumo.

Alla produzione, dentro una transazione:

1. Ogni ingrediente viene detratto dalla giacenza per la quantità convertita × lotti.
2. Il prodotto finito viene aggiunto (porzioni × lotti).
3. Il costo del prodotto finito viene ricalcolato come media ponderata tra la giacenza già presente (al suo costo precedente) e ciò appena prodotto (al costo per porzione della ricetta). Se la ricetta non ha ingredienti valorizzati, il costo reale precedente non viene sovrascritto.

Così il prodotto finito ha sempre un costo reale: vale l'importo giusto in Magazzino e si può vendere senza che la validazione lo blocchi per costo zero.

14. Mezzi e Consolidato Flotte

Mezzi è il registro di veicoli/imbarcazioni. Ciascuno con un codice automatico, tipo (barca/terrestre) e gruppo (azienda / noleggiati). Si usano per attribuire spedizioni di carburante e vendite per unità, che poi alimentano il Consolidato Flotte (vedi sezione 12).

15. Multiutente, ruoli e accesso

Ledyvas ha un sistema di utenti con 5 ruoli: Direzione, Acquisti, Vendite, Magazzino, Contabilità. Le password sono salvate solo come hash (scrypt), mai in chiaro.

16. Giacenza negativa: una scelta di progettazione

Ledyvas non blocca mai la conferma di una vendita, una spedizione, una produzione o l'annullamento di un acquisto per mancanza di giacenza. È una scelta esplicita: non interrompere l'operazione dell'attività. La giacenza negativa non è un errore del programma — si corregge con il pulsante Regola Giacenza su quella riga (in Prodotti o Magazzino), che chiede il valore corretto e un motivo e lo traccia.

L'unica eccezione: il Reso di merce di un rivenditore convalida che non restituisca più di quanto ha ricevuto (fisicamente non ha senso).

17. Backup e Cancellazione Master

Backup (in Home): salva una copia completa del file di database con un clic.

Cancellazione Master (in Home, "Modalità Prova"): cancella Acquisti, Vendite e Trasferimenti da una data scelta in poi — mai prima di quella data, e mai il catalogo (Prodotti, Clienti, Fornitori, Destinazioni). Chiede di scrivere "CANCELLA TUTTO". Ogni documento viene cancellato con lo stesso meccanismo di un annullamento individuale, quindi le inversioni di giacenza restano coerenti. Serve per pulire i dati di prova prima di operare sul serio.

18. Lingue e valuta

Ledyvas è tradotto in spagnolo, italiano, inglese, francese e portoghese. La lingua cambia al volo con le bandiere, senza riavvio. La valuta dell'attività si imposta in Configurazione e governa ogni importo; il tasso di cambio ai dollari USA (configurabile) si usa nei report della flotta.

19. Assistente IA

L'assistente nell'app risponde a domande d'uso. Architettura:

• L'app invia la domanda (e lo storico recente) insieme alla sua licenza e all'impronta hardware al server di licenze.
• Il server convalida la licenza, applica un limite di 40 domande al giorno per licenza (una rete di sicurezza sui costi), e solo allora chiama il modello linguistico.
• La chiave del fornitore IA non è mai nell'app né nell'installer — vive solo come segreto del server.
• L'assistente risponde sempre nella lingua in cui gli si scrive, tra le 5 lingue supportate.

20. Regole di business chiave

• Comprare ≠ vendere. L'Acquisto aggiunge solo giacenza. La distribuzione alle destinazioni è indipendente.
• Un unico magazzino. Il Centro Logistico. Non c'è un deposito separato né un "magazzino satellite".
• L'Acquisto Assistito calcola soltanto. Non genera mai un acquisto reale.
• Identificatori stabili. Tutto è referenziato da id interno; i nomi si possono cambiare senza rompere nulla.
• Ogni movimento di giacenza è tracciato nello storico, con la data reale del documento (non quella di oggi).
• La giacenza non ferma mai l'operazione (tranne il Reso di un rivenditore).
• Il conteggio fisico comanda. Nel Controllo Giornaliero, il conteggio reale corregge quello teorico e viene trascinato come iniziale del giorno dopo.

21. Domande tecniche frequenti

Posso spostare l'installazione su un altro computer?

Sì. Copia l'intera cartella (programma + cartella Data) e attiva la licenza sulla nuova macchina. La licenza si trasferisce da sé (la precedente viene disattivata). Poiché la chiave di cifratura deriva dalla licenza, il database si apre sul nuovo PC.

I dati sono nel cloud?

No. Tutto è sulla tua macchina, in un file cifrato. Fai backup spesso.

Perché un prodotto prodotto valeva zero e ora no?

Produrre ora calcola il costo reale del prodotto finito (media ponderata). Prima andava inserito a mano.

Perché la Vendita ai Ristoranti ora offre il Monouso?

Il Monouso si spedisce per destinazione proprio come gli Alimenti. Serve che abbia il suo Valore caricato nella Formula (Acquisto Assistito A) e il suo costo in Prodotti.

Cosa succede se cancello un prodotto che è in una ricetta?

Ledyvas ti avvisa prima di confermare in quante ricette e righe di Formula è usato. Se lo cancelli, viene rimosso da lì e quelle ricette ricalcolano il costo. Se il prodotto ha acquisti/vendite reali, non viene cancellato: viene disattivato.

Se qualcosa non è coperto qui

Scrivi a info@ledyvas.com.