Checkpoint before ghost pallet cleanup workflow

docs/flows/gestione_layout_flow.md

@@ -0,0 +1,64 @@
+# `gestione_layout.py`
+
+## Scopo
+
+Questo modulo visualizza il layout delle corsie come matrice di celle, mostra
+lo stato di occupazione, consente di cercare una UDC e permette l'export della
+matrice. La griglia ad alte prestazioni e' resa con `tksheet`, mantenendo la
+stessa semantica visiva delle celle operative.
+
+## Flusso operativo
+
+```{mermaid}
+flowchart TD
+    A["open_layout_window()"] --> B["Crea o riporta in primo piano LayoutWindow"]
+    B --> C["LayoutWindow.__init__()"]
+    C --> D["Costruisce toolbar, host matrice, statistiche"]
+    D --> E["_load_corsie()"]
+    E --> F["AsyncRunner.run(query_json SQL corsie)"]
+    F --> G["_on_select() sulla corsia iniziale"]
+    G --> H["_load_matrix(corsia)"]
+    H --> I["AsyncRunner.run(query_json SQL matrice)"]
+    I --> J["_rebuild_matrix()"]
+    J --> K["_refresh_stats()"]
+```
+
+## Ricerca UDC
+
+```{mermaid}
+flowchart TD
+    A["Utente inserisce barcode"] --> B["_search_udc()"]
+    B --> C["query_json ricerca pallet -> corsia/colonna/fila"]
+    C --> D{"UDC trovata?"}
+    D -- No --> E["Messaggio informativo"]
+    D -- Si --> F["Seleziona corsia in listbox"]
+    F --> G["_load_matrix(corsia)"]
+    G --> H["_rebuild_matrix()"]
+    H --> I["_highlight_cell_by_labels()"]
+```
+
+## Schema di chiamata essenziale
+
+```{mermaid}
+flowchart LR
+    Init["__init__"] --> Top["_build_top"]
+    Init --> Host["_build_matrix_host"]
+    Init --> Stats["_build_stats"]
+    Init --> LoadCorsie["_load_corsie"]
+    LoadCorsie --> Select["_on_select"]
+    Select --> LoadMatrix["_load_matrix"]
+    LoadMatrix --> Rebuild["_rebuild_matrix"]
+    Rebuild --> RefreshStats["_refresh_stats"]
+    Search["_search_udc"] --> LoadMatrix
+    Export["_export_xlsx"] --> MatrixState["matrix_state / fila_txt / col_txt / udc1"]
+```
+
+## Note
+
+- Il modulo usa un token `_req_counter` per evitare che risposte async vecchie
+  aggiornino la UI fuori ordine.
+- La statistica globale viene ricalcolata da query SQL, mentre quella della
+  corsia corrente usa la matrice gia' caricata in memoria.
+- Il click destro su una cella riusa lo stesso menu contestuale della versione
+  precedente basata su pulsanti CTk.
+- `destroy()` marca la finestra come non piu' attiva per evitare callback tardive.