Freeze 2.0 warehouse monolista e documento fisso F1/F2

fix_barcode_documento_fisso_f1_f2.md

@@ -0,0 +1,65 @@
+# Documento fisso durante il ciclo barcode F1/F2
+
+## Difetto e requisito
+
+Prima della correzione ogni avanzamento interrogava tutte le UDC con IDStato
+uguale alla priorita' richiesta. Per F2, che include tutte le liste non
+prenotate, il documento poteva quindi cambiare senza intervento dell'operatore.
+
+Una volta proposta una lista, ogni successiva UDC del ciclo deve appartenere
+a quel documento. F1 e F2 ricordano ciascuno la propria lista: F2 -> F1 -> F2
+deve riportare al documento inizialmente assegnato a F2, anche se cambia
+l'ordine globale delle UDC disponibili.
+
+## Implementazione locale
+
+- BarcodeService conserva un documento per priorita', separato dallo stato
+  visuale temporaneo di conferma o pausa.
+- La prima richiesta senza documento usa il criterio di ordinamento vigente.
+  Non viene introdotta una selezione per data del documento.
+- Le successive richieste applicano il filtro Documento nelle query di
+  avanzamento, ricerca skip e ricerca della UDC per conferma del movimento.
+- Un documento differente ricevuto dal repository causa un errore esplicito.
+- La pausa per movimenti liberi e il passaggio tra F1/F2 conservano i documenti.
+- Quando termina il documento, il ciclo si ferma e mostra il relativo messaggio.
+  Una successiva pressione esplicita di un tasto priorita' puo' avviare un nuovo
+  ciclo; la fine del precedente non attiva automaticamente un altro documento.
+- Quando rimangono soltanto UDC saltate, viene gestita la sospensione della
+  lista corrente senza passare a un'altra lista disponibile nella coda.
+- Se cambiano prenotazione o visibilita' e ci sono ancora residui nello storico,
+  compare un messaggio di verifica e il documento viene mantenuto in memoria.
+- Un errore della query non cancella il documento memorizzato.
+
+Gli skip sono conteggiati soltanto se la relativa UDC e' ancora residua.
+Le movimentazioni libere mantengono la loro logica; il filtro Documento e'
+applicato soltanto alle ricerche nel contesto del picking.
+
+## Limiti e installazione
+
+Questa correzione riguarda la sessione del terminalino. La memoria dei documenti
+viene azzerata con reset del servizio o riavvio del programma. Non introduce
+ancora due prenotazioni persistenti o un percorso automatico comune per colonna:
+questi appartengono alla successiva modifica funzionale da specificare.
+
+Non serve una patch SQL: cambiano le SELECT eseguite dal codice Python, non gli
+oggetti del database. Versioni: barcode_client 1.0.27 (titolo visibile),
+barcode_repository 1.0.14, barcode_service 1.0.25.
+
+## Verifiche
+
+Esecuzione senza GUI e senza movimentazioni reali:
+
+```bat
+python -m unittest discover -s tests -p test_barcode_document_binding.py -v
+```
+
+Gli 11 test coprono avanzamento con documenti intercalati, passaggi ripetuti
+F2/F1/F2, pausa con movimento libero, salto UDC, sospensione con soli skip,
+fine lista, cambio prenotazione, errore query, rifiuto di documento inatteso,
+isolamento della conferma e passaggio del parametro al repository.
+
+Ulteriori 5 verifiche SELECT su SQL Server, con righe sintetiche in CTE,
+hanno controllato selezione iniziale, filtro documento, assenza di fallback,
+skip effettivamente residui e isolamento della conferma. Nessun dato reale
+e' stato aggiornato per questi test. Il collaudo fisico sul terminalino resta
+da effettuare.