flywms-core/docs/specs/07_entita_configurabili.md

Entita' configurabili dal wizard

Questo documento elenca le entita' che il wizard di installazione deve conoscere.

Lo scopo non e' definire subito lo schema fisico definitivo del database, ma identificare:

• quali oggetti esistono nel sistema;
• quali attributi devono essere raccolti;
• quali valori possono essere generati automaticamente;
• quali domande devono essere poste in fase di prima configurazione.

Classificazione

Le entita' sono divise in cinque gruppi:

• installazione e ambiente;
• integrazione ERP;
• modello logistico;
• struttura fisica del magazzino;
• operativita', barcode, regole e utenti.

Teoria minima WMS da rispettare

Questa sezione raccoglie i concetti essenziali della teoria di gestione magazzini che devono guidare il wizard.

L'obiettivo e' evitare un modello troppo specifico, senza trasformare FlyWMS Core in un prodotto eccessivamente astratto.

Stock Keeping Unit e Logistic Unit

Bisogna distinguere:

• SKU / articolo: cosa e' il prodotto;
• lotto / seriale: quale istanza produttiva o batch;
• LogisticUnit / UDC: quale contenitore fisico movimentiamo;
• contenuto UDC: quali articoli/lotti/quantita' sono dentro la UDC.

Nel legacy questi concetti sono spesso compressi dentro pallet, lotto e codice prodotto.

Nel nuovo modello devono restare separati.

Location logica e location fisica

Una location puo' essere:

• fisica: cella, scaffale, area, magazzino;
• virtuale: non scaffalata, spedita, quarantena, staging;
• transitoria: area di carico, baia, missione in corso.

FlyWMS Core deve gestire la location logica.

FlyWMS Mapper deve aggiungere la posizione fisica, coordinate, accessibilita' e rilevabilita' da drone.

Movimento come transazione

Ogni movimento deve essere una transazione atomica:

prelievo da location sorgente
versamento in location destinazione
audit operatore/data/causale
aggiornamento giacenza corrente

Se una parte fallisce, l'intero movimento deve fallire.

Questo principio e' piu' importante del nome operativo "carico" o "scarico".

Giacenza corrente e storico movimenti

La giacenza corrente serve per velocita' operativa.

Lo storico movimenti serve per verita' contabile e tracciabilita'.

Il sistema deve avere entrambi:

• CurrentInventory per sapere dove si trova ora una UDC;
• InventoryMovement per ricostruire come ci e' arrivata.

Stati logistici

Gli stati logistici non devono sostituire la location.

Esempio:

• una UDC puo' essere in location NON_SHELVED;
• puo' avere stato AVAILABLE;
• oppure stato BLOCKED.

Quindi servono due dimensioni:

• dove si trova;
• in che stato operativo e'.

Strategie di prelievo

Il picking deve poter usare regole configurabili.

Regole teoriche comuni:

• FIFO: prima entrata, prima uscita;
• FEFO: prima scadenza, prima uscita;
• LIFO: ultima entrata, prima uscita, raro ma possibile;
• priorita' documento;
• ottimizzazione percorso;
• zona/area;
• cliente/destinazione;
• lotto obbligatorio.

Per MVP basta supportare policy semplici, ma il modello deve sapere che la regola di prelievo e' configurabile.

Capacita' e vincoli location

Una cella o area puo' avere vincoli:

• peso massimo;
• volume massimo;
• altezza massima;
• tipo UDC ammesso;
• articolo ammesso o vietato;
• lotto ammesso o vietato;
• temperatura;
• pericolosita';
• compatibilita' merceologica;
• stato: libera, occupata, bloccata, manutenzione.

Il wizard deve almeno raccogliere capacita' e dimensioni principali.

I vincoli avanzati possono essere rimandati, ma devono essere previsti nel modello.

Unita' di misura

Peso, dimensioni, volume e quantita' devono avere unita' di misura esplicite.

Non bisogna assumere implicitamente kg, metri o pezzi.

Entita' correlate:

• UnitOfMeasure;
• conversioni;
• precisione numerica;
• arrotondamenti.

Per MVP possiamo usare default semplici, ma salvati in configurazione.

Inventario e riconciliazione

Il WMS deve gestire differenze tra atteso e reale.

Fonti di differenza:

• operatore;
• conteggio manuale;
• drone;
• import ERP;
• errore barcode;
• movimento interrotto.

Servono concetti minimi:

• InventorySnapshot;
• InventoryCount;
• Anomaly;
• ReconciliationAction.

Questi sono particolarmente importanti per FlyWMS Mapper.

Qualita', blocchi e quarantena

Non tutte le UDC presenti sono disponibili.

Stati tipici:

• disponibile;
• bloccata;
• quarantena;
• danneggiata;
• in controllo qualita';
• riservata;
• spedita.

Per MVP basta un blocco operativo semplice, ma il wizard deve permettere di definire location virtuali e causali coerenti.

Prenotazione e allocazione

La picking list non deve essere confusa con la giacenza.

Una UDC puo' essere:

• fisicamente in una location;
• disponibile;
• prenotata per una lista;
• prelevata;
• spedita.

La prenotazione deve essere un vincolo separato dal movimento fisico.

Integrazione ERP

L'ERP e' fonte autorevole per:

• articoli;
• lotti;
• documenti;
• UDC prodotte;
• clienti/destinazioni;
• talvolta pesi e dimensioni.

FlyWMS Core e' fonte autorevole per:

• posizione corrente;
• movimenti fisici;
• barcode operativo;
• anomalie;
• riconciliazioni;
• stato di magazzino.

Questa separazione deve essere chiara nel wizard.

Audit e responsabilita'

Ogni azione che cambia stock, stato o configurazione deve registrare:

• operatore;
• timestamp;
• terminale/origine;
• causale;
• valori prima/dopo quando rilevanti;
• eventuale documento collegato.

Questo e' indispensabile per produzione, assistenza e consulenza.

Campi audit standard su tutte le tabelle

Tutte le tabelle persistenti di dominio devono adottare un blocco audit comune.

Forma consigliata:

• created_by;
• created_at;
• updated_by;
• updated_at;
• deleted_by;
• deleted_at.

Questa forma e' piu' leggibile di soluzioni troppo sintetiche come un singolo campo JSON di audit.

Il vantaggio e' che ogni tabella resta interrogabile direttamente con SQL semplice, anche durante assistenza, debug o migrazione.

Le cancellazioni devono essere logiche, non fisiche, salvo casi tecnici molto controllati.

Un record con deleted_at valorizzato e' considerato cancellato.

Un record con deleted_at nullo e' considerato attivo.

Questo blocco audit non sostituisce AuditEvent.

Il blocco audit serve a sapere lo stato amministrativo corrente della riga.

AuditEvent serve invece a ricostruire la sequenza storica completa delle operazioni.

Entita' teoriche di supporto

Oltre alle entita' operative elencate sotto, il modello dovra' prevedere almeno queste entita' di supporto, anche se alcune possono essere minime nell'MVP:

• UnitOfMeasure;
• StockStatus;
• LocationType;
• LocationConstraint;
• MovementPolicy;
• PickingStrategy;
• InventorySnapshot;
• InventoryCount;
• Anomaly;
• ReconciliationAction;
• AuditEvent;
• ExternalSystem;
• SyncJob;

1. Installation

Rappresenta la singola installazione del sistema presso un cliente.

Attributi:

• codice installazione;
• nome azienda;
• nome sito;
• ambiente: demo, test, produzione;
• lingua principale;
• timezone;
• database target;
• versione schema;
• data creazione;
• note.

Wizard:

• obbligatoria;
• configurata manualmente;
• genera il contesto generale del sistema.

2. Company

Rappresenta l'azienda cliente.

Attributi:

• ragione sociale;
• codice interno;
• partita IVA opzionale;
• indirizzo;
• paese;
• contatti;
• note.

Wizard:

• obbligatoria;
• inizialmente semplice;
• puo' essere estesa in seguito.

3. Site

Rappresenta un sito operativo fisico.

Esempi:

• stabilimento produttivo;
• magazzino principale;
• magazzino remoto;
• deposito conto terzi.

Attributi:

• codice sito;
• descrizione;
• indirizzo;
• tipo sito;
• timezone opzionale;
• coordinate opzionali;
• attivo.

Wizard:

• almeno un sito obbligatorio;
• piu' siti possibili;
• utile per aziende con produzione e magazzino fisicamente separati.

4. ERPConnection

Descrive come FlyWMS Core si collega all'ERP.

Attributi:

• tipo ERP;
• tipo database;
• host/server;
• database/schema;
• modalita' autenticazione;
• utente tecnico;
• parametri connessione;
• timeout;
• abilita lettura;
• abilita scrittura;
• note sicurezza.

Wizard:

• obbligatoria se si vuole visibilita' UDC dalla nascita ERP;
• test connessione richiesto;
• le credenziali devono essere salvate in modo sicuro.

5. ERPMapping

Descrive come i dati ERP diventano entita' FlyWMS.

Attributi:

• nome mapping;
• origine dati: vista, tabella, query, API;
• campo codice UDC;
• campo articolo;
• campo lotto;
• campo quantita';
• campo peso;
• campo dimensioni;
• campo documento;
• campo stato ERP;
• filtri di validita';
• frequenza refresh;
• modalita' sincronizzazione.

Wizard:

• obbligatoria per UDC prodotte;
• puo' iniziare con mapping guidato su viste SQL;
• in futuro puo' supportare API o file.

6. LogisticUnitType

Definisce la tipologia di unita' di carico.

Esempi:

• pallet;
• cartone;
• cassa;
• bobina;
• contenitore;
• roll;
• collo.

Attributi:

• codice;
• descrizione;
• barcode obbligatorio;
• peso obbligatorio;
• dimensioni obbligatorie;
• contenuto mono-articolo;
• contenuto multi-articolo;
• contenuto mono-lotto;
• contenuto multi-lotto;
• impilabile;
• fragile;
• deperibile;
• temperatura controllata;
• unita' di misura peso;
• unita' di misura dimensioni;
• attivo.

Wizard:

• almeno un tipo obbligatorio;
• valori default proponibili;
• il wizard deve chiedere solo gli attributi rilevanti per il settore.

7. LogisticUnitAttributeDefinition

Definisce attributi aggiuntivi per le UDC, senza creare codice custom per cliente.

Attributi:

• nome attributo;
• label utente;
• tipo dato: testo, numero, booleano, data, enum;
• obbligatorio;
• valore default;
• origine: ERP, manuale, calcolato;
• visibile in griglia;
• visibile su barcode;
• validazione.

Wizard:

• opzionale nella prima versione;
• utile per settori diversi;
• da mantenere controllato, evitando attributi liberi illimitati troppo presto.

8. Item

Rappresenta articolo/prodotto.

Attributi:

• codice articolo;
• descrizione;
• unita' di misura;
• peso unitario;
• dimensioni;
• categoria;
• barcode articolo opzionale;
• origine ERP;
• attivo.

Wizard:

• normalmente importato da ERP;
• non creato manualmente salvo demo o installazione senza ERP.

9. Lot

Rappresenta lotto, batch o seriale produttivo.

Attributi:

• codice lotto;
• articolo;
• data produzione;
• data scadenza;
• stato lotto;
• origine ERP.

Wizard:

• importato da ERP;
• il wizard deve solo configurare mapping e obbligatorieta'.

10. LogisticUnitContentSchema

Descrive la struttura contenuto di una UDC.

Attributi:

• tipo UDC;
• consente piu' articoli;
• consente piu' lotti;
• richiede quantita';
• richiede peso per riga;
• richiede lotto;
• richiede scadenza;
• origine contenuto: ERP, barcode, manuale.

Wizard:

• obbligatorio per ogni LogisticUnitType;
• guida la creazione di LogisticUnitContent.

11. VirtualLocation

Rappresenta location non fisiche ma operative.

Obbligatorie:

• NON_SHELVED;
• SHIPPED.

Attributi:

• codice interno;
• label utente;
• barcode convenzionale;
• descrizione;
• tipo virtuale;
• visibile in dashboard;
• movimentabile da barcode;
• destinazione finale;
• attiva.

Wizard:

• le due obbligatorie devono sempre esistere;
• label e barcode devono essere configurabili;
• valori default proposti: Non scaff., Spedita.

12. Warehouse

Rappresenta un magazzino logico/fisico.

Attributi:

• codice;
• descrizione;
• sito;
• tipo magazzino;
• attivo;
• note;
• dimensioni fisiche opzionali;
• coordinate opzionali per mapper.

Wizard:

• almeno un magazzino obbligatorio;
• puo' generare aree/scaffali/celle.

13. WarehouseArea

Rappresenta una zona del magazzino.

Esempi:

• area scaffalata;
• area transito;
• area accettazione;
• area spedizione;
• area quarantena.

Attributi:

• codice;
• descrizione;
• magazzino;
• tipo area;
• ordinamento;
• coordinate opzionali;
• attiva.

Wizard:

• generabile;
• puo' essere semplice nella prima installazione;
• importante per mapper e layout.

14. Aisle

Rappresenta una corsia.

Attributi:

• codice;
• descrizione;
• area;
• ordinamento;
• lato opzionale;
• coordinate inizio/fine opzionali;
• attiva.

Wizard:

• generabile per numero corsie;
• deve produrre codici coerenti e leggibili.

15. Rack

Rappresenta uno scaffale o struttura di stoccaggio.

Attributi:

• codice;
• descrizione;
• area o corsia;
• numero campate;
• numero livelli;
• profondita';
• altezza;
• larghezza;
• capacita' peso;
• coordinate opzionali;
• attivo.

Wizard:

• configurabile per pattern;
• puo' generare automaticamente campate, livelli e celle.

16. Bay

Rappresenta una campata dello scaffale.

Attributi:

• codice;
• rack;
• indice;
• larghezza;
• profondita';
• capacita' peso;
• coordinate opzionali.

Wizard:

• normalmente generata automaticamente.

17. Level

Rappresenta un livello verticale.

Attributi:

• codice;
• rack o bay;
• indice;
• altezza;
• capacita' peso;
• coordinate opzionali.

Wizard:

• normalmente generato automaticamente.

18. Cell

Rappresenta una posizione fisica puntuale.

Attributi:

• codice cella;
• barcode cella;
• warehouse;
• area;
• aisle;
• rack;
• bay;
• level;
• posizione;
• dimensioni;
• capacita' peso;
• capacita' volume;
• tipo cella;
• accessibile da barcode;
• mappabile da drone;
• attiva.

Wizard:

• generata dal pattern di magazzino;
• modificabile manualmente;
• fondamentale per Core e Mapper.

19. MovementReason

Definisce causali di movimento.

Esempi:

• presa in carico;
• versamento;
• prelievo;
• picking;
• spedizione;
• rettifica;
• inventario;
• riconciliazione drone.

Attributi:

• codice;
• descrizione;
• richiede documento;
• richiede approvazione;
• visibile su barcode;
• attiva.

Wizard:

• default generati;
• personalizzabile in seguito.

20. BarcodeProfile

Descrive terminali e comportamento barcode.

Attributi:

• nome profilo;
• risoluzione;
• tasti funzione;
• enter automatico;
• timeout messaggi;
• operazioni abilitate;
• font e layout;
• modalita' RDP;
• avvio automatico.

Wizard:

• obbligatorio se si usa barcode;
• deve proporre profili standard.

21. OperatorRole

Definisce ruoli utente.

Attributi:

• codice;
• descrizione;
• permessi;
• puo' usare barcode;
• puo' configurare;
• puo' rettificare;
• puo' vedere storico;
• puo' validare anomalie.

Wizard:

• default generati;
• configurazione dettagliata rimandabile.

22. Operator

Rappresenta utente operativo.

Attributi:

• login;
• nome;
• ruolo;
• sito;
• magazzino predefinito;
• attivo;
• autenticazione locale o esterna.

Wizard:

• almeno un amministratore;
• opzionale creare operatori iniziali.

23. PickingPolicy

Definisce regole di proposta picking.

Attributi:

• nome policy;
• ordinamento celle;
• priorita';
• gestione UDC non scaffalate;
• gestione location virtuali;
• limite liste visibili;
• regole F1/F2 o equivalenti.

Wizard:

• default semplice;
• personalizzabile per cliente.

24. ThresholdRule

Definisce soglie operative.

Esempi:

• UDC prodotte non prese in carico >= 50;
• UDC non scaffalate >= 20;
• celle bloccate > 0;
• anomalie mapper > 0.

Attributi:

• codice;
• descrizione;
• metrica;
• soglia;
• severita';
• notifica;
• dashboard.

Wizard:

• opzionale;
• utile per aziende con magazzino remoto.

25. MapperLocationMetadata

Contiene metadati necessari a FlyWMS Mapper.

Attributi:

• location;
• coordinate;
• orientamento;
• altezza;
• punto scansione;
• accessibilita' drone;
• barcode visibile;
• priorita' scansione.

Wizard:

• opzionale nella prima installazione Core;
• puo' essere completato da Mapper.

Entita' da approfondire

Le seguenti entita' sono candidate ma non ancora definitive:

• Document;
• DocumentLine;
• Reservation;
• PickingTask;
• Shipment;
• InventorySnapshot;
• DroneScan;
• Anomaly;
• ReconciliationAction.

Prossimo passo

Per ogni entita' bisogna decidere:

• obbligatoria o opzionale;
• configurata dal wizard o derivata da ERP;
• generata automaticamente o inserita manualmente;
• tabella fisica, vista, configurazione JSON o entrambe;
• attributi minimi per MVP;
• attributi rimandabili.