commit 3c97dbe313f5be55a6943dd8f236bd695bee142c
Author: allebonvi <allebonvi@gmail.com>
Date:   Tue Jun 30 16:40:15 2026 +0200

    Avvio specifiche FlyWMS Core

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..8cf8565
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.log
+*.tmp
+*.zip
+.env
+.env.*
+db_connection.json
+.codegraph/
+.venv/
+venv/
+build/
+dist/
+
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f567b02
--- /dev/null
+++ b/README.md
@@ -0,0 +1,27 @@
+# FlyWMS Core
+
+FlyWMS Core e' il modulo operativo WMS della piattaforma FlyWMS.
+
+La piattaforma sara' composta inizialmente da due moduli principali:
+
+- FlyWMS Core: gestione magazzino, unita' di carico, celle, movimenti, picking, barcode, storico e integrazione ERP.
+- FlyWMS Mapper: mappatura fisica, drone mapping, scansione celle, inventario assistito e riconciliazione tra mappa fisica e giacenza attesa.
+
+Questo repository nasce come riprogettazione del prototipo `ware_house`, con l'obiettivo di trasformarlo in un prodotto piu' generale, configurabile e adatto a piccole e medie imprese.
+
+## Obiettivi
+
+- Mantenere concretezza operativa: barcode, picking, movimenti e storico devono funzionare in modo semplice e robusto.
+- Separare chiaramente interfaccia, modello dati, servizi applicativi e accesso al database.
+- Rendere configurabili gli aspetti che cambiano da cliente a cliente, senza costruire un sistema eccessivamente teorico.
+- Preparare un modello location compatibile con FlyWMS Mapper e con la futura mappatura tramite drone.
+- Integrare ERP esterni, inizialmente con forte attenzione a SQL Server e a scenari legacy.
+
+## Documentazione iniziale
+
+- [Visione prodotto](docs/specs/01_visione_prodotto.md)
+- [Confini tra Core e Mapper](docs/specs/02_core_mapper_boundary.md)
+- [Modello concettuale iniziale](docs/specs/03_modello_concettuale.md)
+- [Configurabilita' iniziale](docs/specs/04_configurabilita_iniziale.md)
+- [Roadmap pragmatica](docs/specs/05_roadmap.md)
+
diff --git a/docs/specs/01_visione_prodotto.md b/docs/specs/01_visione_prodotto.md
new file mode 100644
index 0000000..bbea726
--- /dev/null
+++ b/docs/specs/01_visione_prodotto.md
@@ -0,0 +1,34 @@
+# Visione prodotto
+
+FlyWMS Core deve diventare un modulo WMS leggero, configurabile e integrabile con sistemi ERP esistenti.
+
+Non deve nascere come un gestionale monolitico general purpose, ma come un prodotto pragmatico per PMI che hanno bisogno di governare il magazzino senza sostituire subito l'ERP.
+
+## Posizionamento
+
+FlyWMS Core e' pensato per aziende che:
+
+- hanno gia' un ERP o gestionale;
+- producono, movimentano o spediscono unita' di carico;
+- usano barcode o terminali remoti;
+- hanno processi reali spesso non perfettamente standardizzati;
+- vogliono tracciabilita', storico e controllo operativo;
+- possono beneficiare in futuro di mappatura fisica e inventario con drone.
+
+## Principio guida
+
+Il WMS non deve vedere solo cio' che e' gia' stato movimentato nel magazzino, ma anche cio' che e' stato prodotto e deve ancora essere preso in carico.
+
+Questo consente di distinguere:
+
+- UDC prodotte dall'ERP ma non ancora prese in carico dal WMS;
+- UDC non scaffalate o in transito;
+- UDC scaffalate;
+- UDC prenotate in picking;
+- UDC spedite;
+- anomalie rilevate da operatori o da FlyWMS Mapper.
+
+## Obiettivo commerciale
+
+FlyWMS Core deve essere anche un prodotto-vetrina: abbastanza concreto da dimostrare valore operativo, abbastanza configurabile da adattarsi a piu' clienti, abbastanza semplice da poter essere realmente completato e mantenuto.
+
diff --git a/docs/specs/02_core_mapper_boundary.md b/docs/specs/02_core_mapper_boundary.md
new file mode 100644
index 0000000..2e83773
--- /dev/null
+++ b/docs/specs/02_core_mapper_boundary.md
@@ -0,0 +1,51 @@
+# Confini tra FlyWMS Core e FlyWMS Mapper
+
+FlyWMS e' composto da due moduli principali.
+
+## FlyWMS Core
+
+FlyWMS Core e' responsabile della logica WMS operativa:
+
+- anagrafica unita' di carico;
+- anagrafica location e celle;
+- movimenti di magazzino;
+- giacenza corrente;
+- picking list;
+- barcode client;
+- storico movimenti;
+- integrazione ERP;
+- dashboard operative;
+- regole base di validazione.
+
+## FlyWMS Mapper
+
+FlyWMS Mapper e' responsabile della dimensione fisica e spaziale:
+
+- mappa del magazzino;
+- coordinate fisiche di aree, scaffali, celle e corsie;
+- punti di scansione drone;
+- letture automatiche o assistite;
+- confronto tra rilevato e atteso;
+- anomalie fisiche;
+- aggiornamento o proposta di correzione verso Core.
+
+## Punto di contatto
+
+Il punto di contatto principale e' la location.
+
+FlyWMS Core deve sapere che una UDC si trova in una location logica.
+
+FlyWMS Mapper deve sapere dove quella location si trova fisicamente nello spazio.
+
+Esempio:
+
+```text
+Core:
+UDC 655589 -> Location 1A.15.a
+
+Mapper:
+Location 1A.15.a -> coordinate, scaffale, livello, punto drone
+```
+
+Mapper non deve sostituire Core. Mapper osserva, misura e propone riconciliazioni.
+
diff --git a/docs/specs/03_modello_concettuale.md b/docs/specs/03_modello_concettuale.md
new file mode 100644
index 0000000..87faf95
--- /dev/null
+++ b/docs/specs/03_modello_concettuale.md
@@ -0,0 +1,104 @@
+# Modello concettuale iniziale
+
+Il modello deve essere abbastanza generale da non ripetere i limiti del legacy, ma non cosi' astratto da bloccare lo sviluppo.
+
+## Entita' principali
+
+### LogisticUnit
+
+Rappresenta una qualsiasi unita' fisica movimentabile.
+
+Esempi:
+
+- pallet;
+- cassa;
+- cartone;
+- bobina;
+- contenitore;
+- roll;
+- collo;
+- unita' specifica del cliente.
+
+Attributi iniziali:
+
+- codice barcode;
+- tipo unita';
+- stato logico;
+- peso lordo;
+- peso netto;
+- tara;
+- dimensioni;
+- volume;
+- data creazione;
+- origine dati;
+- riferimento ERP.
+
+### LogisticUnitContent
+
+Descrive il contenuto di una unita' logistica.
+
+Serve per gestire:
+
+- una UDC con un solo lotto;
+- una UDC con piu' lotti;
+- una UDC con piu' articoli;
+- quantita' parziali.
+
+### Location
+
+Rappresenta una posizione logica o fisica.
+
+Tipi iniziali:
+
+- magazzino;
+- area;
+- corsia;
+- scaffale;
+- livello;
+- cella;
+- location virtuale.
+
+Le location virtuali sostituiscono i codici convenzionali legacy.
+
+Esempi:
+
+- NON_SHELVED;
+- SHIPPED;
+- RECEIVING;
+- QUALITY_HOLD;
+- DAMAGED;
+- STAGING.
+
+### InventoryMovement
+
+Registra ogni movimento.
+
+Campi concettuali:
+
+- unita' logistica;
+- location sorgente;
+- location destinazione;
+- operatore;
+- timestamp;
+- causale;
+- documento sorgente;
+- origine del movimento;
+- transazione.
+
+### CurrentInventory
+
+Rappresenta la giacenza corrente materializzata.
+
+Puo' essere calcolata dai movimenti oppure mantenuta come tabella aggiornata per performance.
+
+## Stati logici iniziali
+
+- PRODUCED_BY_ERP;
+- RECEIVED;
+- NON_SHELVED;
+- SHELVED;
+- RESERVED_FOR_PICKING;
+- SHIPPED;
+- BLOCKED;
+- UNKNOWN.
+
diff --git a/docs/specs/04_configurabilita_iniziale.md b/docs/specs/04_configurabilita_iniziale.md
new file mode 100644
index 0000000..367bf6f
--- /dev/null
+++ b/docs/specs/04_configurabilita_iniziale.md
@@ -0,0 +1,36 @@
+# Configurabilita' iniziale
+
+La configurabilita' deve essere pragmatica.
+
+L'obiettivo non e' creare subito un motore universale, ma rendere configurabili le differenze piu' frequenti tra clienti.
+
+## Da configurare subito
+
+- connessione ERP;
+- mappatura campi ERP verso FlyWMS;
+- tipi di unita' logistica;
+- location virtuali;
+- codici barcode convenzionali;
+- regole base di movimento;
+- parametri terminale barcode;
+- testi e label UI;
+- soglie operative;
+- ruoli e permessi;
+- formati di esportazione.
+
+## Da rimandare
+
+- workflow designer visuale;
+- regole illimitate utente;
+- multi-tenant completo;
+- contenitori annidati complessi;
+- ottimizzazione matematica percorsi;
+- motore eventi altamente generico;
+- attributi custom totalmente liberi.
+
+## Regola di progettazione
+
+Ogni configurazione deve risolvere un caso reale.
+
+Se una configurazione non ha ancora un caso reale, va documentata come possibilita' futura ma non implementata subito.
+
diff --git a/docs/specs/05_roadmap.md b/docs/specs/05_roadmap.md
new file mode 100644
index 0000000..8073c78
--- /dev/null
+++ b/docs/specs/05_roadmap.md
@@ -0,0 +1,54 @@
+# Roadmap pragmatica
+
+## Fase 0 - Analisi e consolidamento
+
+- rileggere il prototipo `ware_house`;
+- documentare flussi barcode, picking, storico e movimenti;
+- isolare cio' che e' specifico Medisea/SAM;
+- isolare cio' che puo' diventare modello generale.
+
+## Fase 1 - Fondazione Core
+
+- creare modello dominio iniziale;
+- definire layer database;
+- definire layer servizi;
+- definire API interne;
+- creare configurazione connessione ERP/WMS;
+- creare logging e audit robusti;
+- creare struttura test.
+
+## Fase 2 - Funzioni operative minime
+
+- anagrafica location;
+- anagrafica UDC;
+- movimenti UDC;
+- giacenza corrente;
+- storico movimenti;
+- client barcode minimale;
+- picking list base.
+
+## Fase 3 - Integrazione ERP
+
+- vista/import UDC prodotte;
+- mappatura documenti;
+- mappatura articoli/lotti;
+- stato UDC prodotta ma non presa in carico;
+- dashboard UDC da stoccare.
+
+## Fase 4 - Collegamento Mapper
+
+- modello coordinate location;
+- stato atteso vs rilevato;
+- anomalie da scansione;
+- riconciliazione manuale;
+- report inventario fisico.
+
+## Fase 5 - Prodotto-vetrina
+
+- interfaccia pulita;
+- demo dataset;
+- scenario barcode;
+- scenario picking;
+- scenario mappa/drone simulata;
+- documentazione commerciale e tecnica.
+