Cost Engine e margini¶

Il Inventory Cost Engine trasforma il magazzino in un sistema che conosce non solo le quantità, ma anche quanto costa realmente ogni articolo e quale margine genera in vendita.

Il modulo è generico: funziona per negozi, industrie, installatori, laboratori, ristoranti e qualsiasi attività che gestisce materiali e prodotti composti.

Voce	Percorso	Descrizione
Dashboard	`/inventory/dashboard`	Prodotti sotto costo, margini bassi, top redditività, rotazione
Costi	`/inventory/costs`	Storico costi e snapshot per prodotto
Distinte base	`/inventory/bom`	BOM, kit, ricette, semilavorati
Produzione	`/inventory/production`	Ordini di produzione
Mapping fornitori	`/inventory/mapping`	Associazione codici fornitore ↔ prodotti interni
Ricevimenti merce	`/inventory/receipts`	DDT in ingresso / ricevimento da fornitore

Costi e valorizzazione¶

Ogni prodotto mantiene:

Ultimo costo — dall'ultimo acquisto
Costo medio — media ponderata (default)
Costo minimo / massimo — range storico
Margine — differenza tra prezzo vendita e costo reale

Metodi configurabili per azienda o per singolo prodotto:

Metodo	Quando usarlo
Media ponderata	Default, adatto alla maggior parte dei casi
FIFO	Uscita al costo del lotto più vecchio
Ultimo costo	Valorizzazione al prezzo dell'ultimo acquisto
LIFO	Opzionale, disabilitato di default

Impostazioni in Sistema → Impostazioni (chiavi inventory.*).

Acquisti e carico magazzino¶

Alla registrazione di una fattura passiva con righe prodotto:

Il sistema converte la quantità dall'unità di acquisto all'unità di magazzino (es. sacco 25 kg → kg)
Aggiorna il costo del prodotto e lo storico prezzi
Genera il movimento di carico nel magazzino default
Se il codice fornitore è nuovo, propone un mapping da confermare manualmente

Mapping fornitore

Alla prima occorrenza di un codice fornitore il sistema propone l'associazione al prodotto interno, ma non la applica automaticamente. L'utente deve confermare in Mapping fornitori. Le fatture successive useranno il mapping confermato.

Ricevimenti merce¶

Per registrare l'ingresso merce prima della fattura (o in parallelo):

Vada in Ricevimenti merce
Crei un documento con fornitore, magazzino e righe prodotto
Alla conferma il sistema carica il magazzino e aggiorna i costi come per un acquisto

Il ricevimento può essere collegato successivamente alla fattura passiva.

Distinte base (BOM)¶

Un prodotto può essere configurato come:

Tipo	Esempio
Semplice	Vite, bullone
Kit	Kit videosorveglianza (4 telecamere + NVR + HDD)
Ricetta	Pizza (farina, acqua, mozzarella, …)
Composto / semilavorato	Prodotto assemblato in più fasi

La distinta elenca componenti e quantità (con eventuale scarto %). Può includere righe di manodopera (minuti × costo orario).

Produzione¶

Per prodotti con BOM attiva:

Crei un ordine di produzione indicando quantità e magazzino
Alla completamento il sistema:
scarica i componenti (consumo materiali)
carica il prodotto finito al costo calcolato dalla distinta

Vendita e margini¶

All'emissione di un DDT (se lo scarico magazzino è abilitato):

Il sistema registra lo scarico e calcola il costo reale della vendita
Aggiorna il margine lordo e la percentuale sul prodotto

L'esplosione della distinta base in vendita (scarico dei singoli componenti invece del prodotto finito) è disattivata di default e si abilita con l'impostazione inventory.explode_bom_on_sale.

Permessi¶

Permesso	Funzione
`inventory.margin.read`	Dashboard e lettura margini
`inventory.cost.read`	Lettura costi e storico
`inventory.cost.manage`	Gestione costi e ricevimenti
`inventory.bom`	Distinte base
`inventory.production`	Ordini produzione
`inventory.purchase_mapping`	Conferma mapping fornitori

Il ruolo magazzino include in genere tutti i permessi operativi; commercialista e vendite hanno accesso in lettura ai margini.

Integrazioni API¶

Per integrazioni esterne veda Appendice per il consulente e la documentazione Swagger (/swagger/) — sezione Inventory (P13).

Documentazione tecnica in docs/p13_inventory_cost_engine.md.