Aggiungi teoria WMS e entita configurabili

2026-06-30 16:58:42 +02:00
parent a2520ff84c
commit a9c73fdfba
2 changed files with 849 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -28,3 +28,4 @@ Questo repository nasce come riprogettazione del prototipo `ware_house`, con l'o
 - [Configurabilita' iniziale](docs/specs/04_configurabilita_iniziale.md)
 - [Roadmap pragmatica](docs/specs/05_roadmap.md)
 - [Wizard di installazione](docs/specs/06_wizard_installazione.md)
 - [Entita' configurabili](docs/specs/07_entita_configurabili.md)
--- a/docs/specs/07_entita_configurabili.md
+++ b/docs/specs/07_entita_configurabili.md
@@ -0,0 +1,848 @@
 # 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:
 ```text
 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.
 ## 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.