Guida operativa

1. Panoramica: cos'è e come si pensa

InventoryOS registra i fatti del magazzino — arrivi, prelievi, produzioni, spedizioni — e da quei fatti ricostruisce il valore. Non è un programma contabile: prepara dati che il commercialista può usare, ma la contabilità resta fuori.

La logica è sempre la stessa, in ogni sezione: prima registri, poi confermi. Finché una registrazione è in bozza si può sistemare; dopo la conferma diventa un fatto compiuto che si corregge solo con un movimento di storno, mai cancellandolo. È la stessa garanzia che chiede un controllo fiscale.

L'applicazione gira sul computer dell'azienda (o sul server interno): l'indirizzo te lo comunica chi ha fatto l'installazione, nella forma http://127.0.0.1:8002. Si apre con il browser che usi ogni giorno e funziona anche in rete locale, se l'azienda l'ha configurata.

2. Primo accesso e ruoli

All'apertura trovi la schermata di accesso. Le credenziali le crea l'amministratore dell'azienda (se sei il primo utente, è chi ha installato). Dopo alcune ore di uso la sessione scade e ti viene chiesto di rientrare: è normale, protegge i dati.

Se una pagina ti risponde «Operazione riservata all'amministratore» o «Ruolo non autorizzato», non è un errore: quella funzione spetta a un altro ruolo. Se il sistema ti dice «Licenza non attiva», avvisa l'amministratore (vedi sezione 12).

3. La configurazione iniziale (amministratore)

Si fa una volta sola, in Impostazioni → Configurazione. Senza questi passaggi le sezioni operative non partono:

1. Utenti: un profilo per persona, con il ruolo giusto. Le password sono lunghe per imposizione.
2. Soggetti: fornitori e clienti con partita IVA. Servono ai documenti d'acquisto e alle spedizioni.
3. Magazzini: almeno uno «proprio»; se ordini materiali «in conto lavorazione» aggiungi il magazzino del terzista (tipo deposito terzi o terzista).
4. Unità di misura: quelle che usate davvero (PZ, KG, M, MQ…). Attenzione ai doppioni: «MQ» e «M2» sono due unità diverse per il programma.
5. Causali di movimento: le etichette operative (carico produzione, scarico produzione, rettifica…). Alcune sono create dall'installazione.
6. Tipo di azienda: commerciale o industriale. Cambia ciò che vedi nel menu (la produzione è per le industriali).
7. AI e Cat (facoltativo): se l'azienda vuole l'AI locale, qui si configura; senza AI il programma funziona uguale, solo senza proposte automatiche.

4. Il lavoro di ogni giorno: la merce in entrata

Il flusso d'acquisto unisce due documenti che arrivano separati: la bolla (DDT) e la fattura elettronica XML del fornitore. Il risultato è una giacenza valorizzata al prezzo vero, non a una stima.

1. Vai su In entrata → Ricevimento merci e registra la bolla: fornitore, numero e data DDT, magazzino di destinazione e le righe con articolo e quantità. Il ricevimento nasce in stato «registrato»: la merce fisica è arrivata, il valore ancora no.
2. Su In entrata → Importa fatture XML carica il file della fattura. Il programma legge le righe e prova ad abbinarle agli articoli usando i codici articolo del fornitore (si compilano nella scheda articolo, sezione fornitore). Le righe non riconosciute restano da abbinare a mano.
3. Torna al ricevimento e usa Abbina fattura: il programma confronta quantità della bolla e della fattura (coincidono / non coincidono) e, quando tutto torna, il carico passa a valorizzato. Da questo momento la giacenza ha un costo reale per pezzo.

Se una quantità non coincide, il programma te lo dice invece di inventare: controlla bolla e fattura e correggi dove sbaglia il documento.

5. Il magazzino: giacenze, articoli, lotti, movimenti manuali

• Giacenze (il «Cosa ho»): quante pezzi ci sono, in quale magazzino e quanto valgono. È la pagina da tenere aperta: mostra anche scadenze e lotti da tenere d'occhio.
• Articoli: l'anagrafica. Per ogni articolo si scelgono l'unità di misura, il metodo di valorizzazione (CMP, FIFO, LIFO o costo specifico — decide chi si intende di contabilità, di solito resta CMP), se è acquistabile, producibile o vendibile, e i codici che usa ogni fornitore. Un articolo ben fatto risparmia ore di abbinamenti sulle fatture.
• Lotti: per gli articoli tracciati (attivato in anagrafica). Ogni carico prende un lotto, così uno scarico sa esattamente da quale partenza viene.
• Movimenti manuali: per tutto ciò che non passa da bolla, produzione o spedizione — una rettifica inventario, un carico veloce, uno scarico interno. Scegli la causale, l'articolo, il magazzino e la quantità; conferma solo quando sei sicuro, perché dopo la conferma il movimento non si modifica: si storna.
• Materiale presso terzi: cosa è fuori casa in lavorazione. Il trasferimento verso il terzista e il rientro sono movimenti con causale di classe deposito/lavorazione: la merce resta tua, cambia solo la ubicazione.

6. Le distinte base (BOM)

La distinta è la ricetta: per un pezzo finito, quali componenti, in che quantità e con quale scarto. Sta in Produzione → Distinte base e ha versioni: puoi preparare una revisione nuova senza toccare quella in uso, e una sola versione per articolo è quella «predefinita» che la produzione prende di default.

Ogni riga ha la quantità per pezzo (es. 8 viti per tavolo), lo scarto percentuale (5% di vernice in più) e, quando serve, una regola di fabbisogno: un fattore di conversione (il materiale comprato in kg che si consuma in metri quadrati), un lotto minimo d'acquisto o un arrotondamento (es. multipli di una barra). Se apri l'«esplosione» della distinta vedi il calcolo completo, livello per livello: quelle sono esattamente le quantità che la produzione preleverà.

Il programma impedisce i circoli (una distinta che contiene se stessa) e, per articoli composti, si scende in automatico nei semilavorati.

7. La distinta assistita con l'AI

Se l'azienda ha attivato l'AI (Cheshire Cat), in Produzione → Crea distinta assistita puoi partire da un documento invece che da una pagina bianca: un CSV o TXT con l'elenco pezzi, un disegno STEP, un DXF.

1. Carica il documento: il programma estrae le righe o la struttura del disegno.
2. Premi Proponi righe con l'AI: il Cat legge il documento e propone l'elenco dei componenti, già normalizzati (descrizione, quantità, unità di misura).
3. Per ogni riga proposta il programma suggerisce l'articolo di magazzino più simile: confermi, cambi suggerimento o lasci da parte. Le righe non riconosciute restano lì: nessun obbligo di risolverle tutte.
4. Con «Genera BOM» nasce la distinta solo dalle righe che hai abbinato e confermato tu. L'AI non scrive niente da sola: propone, decidi tu. Ogni proposta e ogni conferma resta tracciata.

7.1 Come si configura l'AI (una volta sola)

La configurazione sta in Impostazioni → Configurazione → scheda «AI e Cat» ed è riservata all'amministratore. Si scelgono tre modalità:

• AI locale (consigliata): il modello gira su un computer dell'azienda. Nessun documento esce dalla rete aziendale.
• AI esterna: si usa un provider compatibile OpenAI già disponibile (con chiave API). Comoda se l'azienda ha già un contratto, ma i documenti elaborati lasciano la sede: è una scelta da prendere col titolare.
• Disattivata: tutto il resto del programma funziona uguale, senza assistente e senza proposte automatiche.

7.2 Il percorso locale, passo per passo

Prerequisito, una volta sola: installare Ollama (si scarica da ollama.com) sul PC o sul server dove gira InventoryOS, poi scaricare un modello aprendo un prompt dei comandi e digitando:

ollama pull qwen2.5:7b-instruct

Sono circa 5 GB, si scarica una volta sola; la sigla «7b» indica la dimensione del modello e va bene per un computer normale.

Serve poi la preparazione una tantum del Cat: dalla cartella dove InventoryOS è installato, chi ha accesso ai file esegue una volta i due script mostrati più sotto nel riquadro «Preparazione locale» (setup_ollama.ps1 e setup_cat.ps1, con il tasto destro → «Esegui con PowerShell»). Senza questo passaggio, al primo avvio l'app segnala che il Cat non è stato preparato e prosegue senza AI. Da qui in poi, nell'app:

1. Apri Impostazioni → Configurazione → AI e Cat e scegli la modalità AI locale.
2. Controlla i parametri (i valori già proposti vanno bene nella maggior parte dei casi): Base URL motore AI http://127.0.0.1:11434/v1, Modello qwen2.5:7b-instruct, URL Cheshire Cat http://127.0.0.1:1865. Alza il Timeout AI a 120 secondi: il modello locale ragiona sul tuo computer, non nel datacenter di qualcun altro, e i primi secondi servono a caricarlo in memoria.
3. Premi Salva configurazione: le impostazioni si scrivono nel file di configurazione dell'installazione e l'app chiede un riavvio. Alla prima configurazione basta chiudere e riaprire InventoryOS: il Cat parte insieme all'app. Se invece l'AI era già stata usata da quando il computer è acceso, il motore resta in memoria con le impostazioni vecchie: riavvia il computer (o chiedi a chi ha fatto l'installazione di fermare e riavviare il servizio) per essere certo che la nuova configurazione venga applicata.
4. Torna nella stessa scheda e premi Verifica stato: quando la casella in alto dice «Pronto» e le voci della lista «Verifiche» sono OK, l'AI è operativa. Ogni voce in errore o avviso ti dice cosa controllare.

Nella stessa scheda, il riquadro «Preparazione locale» mostra gli script di preparazione per chi ha accesso alla cartella di installazione (server aziendale o postazione): servono solo la prima volta o dopo un aggiornamento importante.

7.3 Il percorso esterno (se l'azienda lo preferisce)

1. Scegli la modalità AI esterna.
2. Compila Base URL motore AI (l'indirizzo del provider, completo di /v1 se lo richiede), il nome del modello e la chiave API del provider. La chiave si salva nel file di configurazione dell'installazione e non viene più mostrata a schermo.
3. Salva, riavvia e verifica come sopra: le stesse «Verifiche» ti dicono se il provider risponde.

In modalità esterna i documenti che carichi in «Crea distinta assistita» vengono elaborati dal provider scelto: verifica con il titolare che sia compatibile con le politiche dell'azienda e con gli accordi di riservatezza coi clienti.

La stessa configurazione alimenta anche l'assistente in chat (sezione 11): si imposta una volta sola e vale per tutto. Se in «Crea distinta assistita» il pulsante risponde «AI non disponibile», torna sempre qui e premi «Verifica stato»: la lista ti dice cosa manca.

8. Produrre: dal fabbisogno al prodotto finito

Il percorso guidato è Produzione → Produci articolo: scegli cosa produrre e quante pezze, e il programma ti accompagna. Dietro c'è sempre la stessa catena, visibile anche da Commesse:

1. Pianifica: calcola i fabbisogni con le regole della distinta (scarti, fattori di conversione, lotti minimi) e confronta con la disponibilità. Se manca un semilavorato e ha una sua distinta, propone di produrre prima quello (produzione multilivello).
2. Preleva: scarica i componenti dal magazzino indicato. Se la giacenza non basta, il prelievo si ferma e ti dice cosa manca: il programma non lascia giacenze sotto zero. Il costo del prelievo usa il metodo di valorizzazione dell'articolo.
3. Chiudi e carica il finito: aggiungi se vuoi i costi di lavorazione esterna o costi indiretti, conferma la quantità prodotta e chiudi la commessa. Il prodotto finito entra in magazzino col suo costo reale (materiali + lavorazioni).

Gli stati della commessa raccontano dove sei: aperto → pianificato → prelevato → chiuso. Puoi fermarti tra un passo e l'altro e riprendere dopo.

9. Spedire e vendere

1. In uscita → Spedizioni e DDT: registra la bolla al cliente (righe, quantità, magazzino di partenza) e conferma: scarica il magazzino.
2. Quando arriva la fattura di vendita la colleghi al DDT: la spedizione passa a «fatturata». Così a fine mese sai cosa è stato spedito e non ancora fatturato.
3. Listini prezzi: definisci i prodotti di vendita componendoli dai tuoi articoli (con scarti) e calcola il prezzo con margine o ricarico. Ogni pubblicazione fotografa la formula e i costi del momento: se un costo cambia, ricalcoli e pubblichi una versione nuova.

10. Costi, chiusura d'esercizio e commercialista

• Costo materiali: a che prezzo hai comprato ogni articolo, nel tempo. Utile per capire se un fornitore sta salendo prima che se ne accorga l'amministrazione.
• Chiusura esercizio (ruolo commercialista): calcola le rimanenze di fine anno con il metodo di ogni articolo, evidenzia le anomalie, permette le rettifiche (svalutazioni) e poi — solo quando tutto torna — la conferma. Attenzione: confermato l'esercizio, i movimenti di quell'anno non si toccano più.
• Integrazioni contabili: prepara il pacchetto per il commercialista (rimanenze, scritture proposte, checksum) da consegnare via file, cartella condivisa o SFTP secondo come l'ha configurato l'amministratore. La registrazione resta al professionista.

11. L'assistente AI

L'assistente contestuale (l'icona della chat) risponde alle domande sul flusso: «perché questo prelievo è bloccato?», «cosa significa stato fatturata?», «come si fa uno storno?». Non scrive dati e non esegue operazioni: spiega e guida. Se l'azienda ha attivato l'AI locale, le risposte girano in sede; in caso contrario l'assistente resta spento e tutto il resto funziona.

12. Licenza e amministrazione

La licenza è per installazione (mensile o annuale) e si gestisce in Impostazioni → Licenza, solo da amministratore:

• Abbonati: apre il pagamento sicuro Stripe (carta, rinnovo automatico).
• Gestisci abbonamento e carta: apre il portale Stripe per cambio carta, rinnovi e fatture.
• Sincronizza: aggiorna lo stato dopo un pagamento.
• Chiave offline: se l'azienda ha ricevuto una chiave (per uffici senza collegamenti esterni), si incolla qui e vale fino alla sua scadenza.

Con la licenza scaduta le pagine operative rispondono «Licenza non attiva»: i dati non si perdono, restano nel database dell'azienda. Basta rinnovare o attivare una chiave per riprendere.

L'amministratore trova anche la gestione utenti (disattivare chi lascia, cambiare ruoli) e la voce audit: la lista di chi ha fatto cosa, sempre consultabile.

13. Regole d'oro e problemi comuni

Ultima regola, la più importante: quando un numero ti sembra strano, non forzarlo. Il programma è costruito per fermarsi e dirti cosa non torna: quel freno è la garanzia che a dicembre il valore del magazzino sarà spiegabile, riga per riga.