From a9c73fdfbacf1aa89d75a79d1b18986e994390d5 Mon Sep 17 00:00:00 2001
From: allebonvi <allebonvi@gmail.com>
Date: Tue, 30 Jun 2026 16:58:42 +0200
Subject: [PATCH] Aggiungi teoria WMS e entita configurabili

---
 README.md                             |   1 +
 docs/specs/07_entita_configurabili.md | 848 ++++++++++++++++++++++++++
 2 files changed, 849 insertions(+)
 create mode 100644 docs/specs/07_entita_configurabili.md

diff --git a/README.md b/README.md
index b0ca069..f63f1e9 100644
--- 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)
diff --git a/docs/specs/07_entita_configurabili.md b/docs/specs/07_entita_configurabili.md
new file mode 100644
index 0000000..354d88e
--- /dev/null
+++ 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.