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