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