Aggiungi teoria WMS e entita configurabili

This commit is contained in:
2026-06-30 16:58:42 +02:00
parent a2520ff84c
commit a9c73fdfba
2 changed files with 849 additions and 0 deletions

View File

@@ -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.