Freeze 2.0 warehouse monolista e documento fisso F1/F2

specifica_prelievo_due_pickinglist.md

@@ -0,0 +1,439 @@
+# Prelievo guidato di due picking list sul terminalino
+
+Data: 02/10/2026. Revisione: 0.3.
+
+**Stato: specifica da rileggere e concordare prima dell'implementazione.**
+La funzione di prelievo abbinato descritta qui non e' ancora implementata.
+I punti indicati come aperti o proposti non sono decisioni gia' approvate.
+
+## 1. Obiettivo operativo
+
+Consentire al responsabile di prenotare una oppure due picking list dal
+programma desktop. Quando sono due, il terminalino deve guidare un unico
+percorso di prelievo che considera le UDC residue di entrambe.
+
+L'operatore deve percorrere il magazzino seguendo l'ordine previsto, senza
+ritornare alle prime colonne perche' una lista non conteneva UDC in quelle
+posizioni. Il sistema sceglie di volta in volta il documento della prossima
+UDC; l'operatore riconosce il cambio dal numero del documento e dal colore.
+
+Il prelievo abbinato riguarda un operatore che lavora due documenti nello
+stesso giro. La gestione di piu' operatori contemporanei richiede ulteriori
+decisioni e non e' definita da questa specifica.
+
+## 2. Termini usati
+
+| Termine | Significato |
+|---|---|
+| Lista 1 / F1 | Prima lista assegnata alla coppia, con identita' stabile |
+| Lista 2 / F2 | Seconda lista assegnata alla coppia, con identita' stabile |
+| Lista proposta | Documento della prossima UDC indicata dal sistema |
+| Colonna o campata | Colonna di uno specifico scaffale e magazzino |
+| Cella | Singola posizione dentro la colonna, a un determinato livello |
+| Percorso comune | Ordine delle posizioni applicato alle UDC di entrambe le liste |
+| UDC residua | UDC ancora da prelevare, non gia' nella locazione spedita |
+
+Area 5 e Area 6 sono i nomi operativi dei magazzini MDE5 e MDE6.
+Non corrispondono necessariamente agli ID 5 e 6 della tabella legacy Aree.
+La colonna 1 dello scaffale A e la colonna 1 dello scaffale B sono distinte.
+
+## 3. Situazione attuale e difetto da non reintrodurre
+
+La prenotazione Python attuale prevede un unico documento. Storicamente F1
+interroga la priorita' prenotata e F2 quella non prenotata. Quest'ultima puo'
+contenere piu' documenti, quindi non identifica di per se' una seconda lista.
+
+E' stata introdotta nel codice locale una correzione che fissa il documento
+del ciclo per ciascun tasto. Il passaggio F2 -> F1 -> F2 conserva il documento
+precedentemente avviato con F2. Il dettaglio e' in
+[fix_barcode_documento_fisso_f1_f2.md](fix_barcode_documento_fisso_f1_f2.md).
+
+La nuova funzione estende il modello: entrambi i documenti devono essere
+esplicitamente assegnati alla coppia. Il cambio automatico sara' ammesso
+soltanto fra questi due documenti e per una ragione di percorso.
+Nessuna terza lista deve subentrare silenziosamente.
+
+## 4. Selezione e prenotazione sul desktop
+
+### R01. Una o due liste
+
+Gestione Picking List deve permettere di prenotare al massimo due liste per
+il prelievo abbinato. Deve restare utilizzabile anche con una sola lista.
+Il semplice clic per consultare il dettaglio non deve modificare implicitamente
+una prenotazione: selezione per consultazione e assegnazione al giro devono
+avere un comportamento chiaramente distinguibile.
+
+### R02. Identita' della coppia
+
+Il desktop deve rendere riconoscibile quale documento e' Lista 1/F1 e quale
+e' Lista 2/F2. L'assegnazione non dipende dall'ordinamento momentaneo della
+griglia o dalla posizione della prossima UDC.
+
+Il gesto per assegnare i ruoli e' ancora da definire: ad esempio due slot
+espliciti, oppure prima e seconda scelta rese chiaramente visibili.
+
+### R02a. Le due liste devono appartenere alla stessa area
+
+Il prelievo abbinato e' consentito esclusivamente fra due liste della stessa
+area operativa: entrambe Area 5/MDE5 oppure entrambe Area 6/MDE6.
+Non e' consentito abbinare una lista dell'Area 5 a una dell'Area 6.
+Il sistema deve rifiutare l'abbinamento con un messaggio comprensibile,
+senza salvare una coppia parziale o alterare le prenotazioni preesistenti.
+Il vincolo deve essere verificato anche lato servizio/database, non soltanto
+mediante la disponibilita' dei pulsanti nell'interfaccia desktop.
+
+Prima dell'implementazione va definita la fonte autorevole dell'area della
+lista, specialmente se contiene UDC non scaffalate o senza giacenza WMS.
+La cella virtuale condivisa 1000 non dimostra da sola l'appartenenza all'area.
+Non dedurre il magazzino dal numero documento o dagli ID legacy delle Aree.
+Il trattamento delle liste internamente miste o con area indeterminata resta
+da concordare; non considerarle implicitamente compatibili con entrambe.
+
+### R03. Un'unica sequenza personalizzata
+
+Con due liste selezionate, il comando Sequenza di prelievo riguarda entrambe.
+L'editor deve presentare l'unione degli scaffali/gruppi presenti nelle due liste,
+includendo quelli presenti soltanto in una di esse e il gruppo Non scaff.
+
+Non si devono eseguire due ordinamenti personalizzati incompatibili nello
+stesso giro. La sequenza della coppia deve costituire l'unico riferimento.
+
+La scelta fra eventuali personalizzazioni gia' salvate sulle singole liste
+resta aperta. Non e' ammessa una fusione silenziosa che produca un ordine
+diverso da quello mostrato al responsabile.
+
+## 5. Percorsi delle aree: conservare il comportamento esistente
+
+### R04. Area 6 / MDE6
+
+Conservare il percorso attuale: scaffali nell'ordine previsto, colonne in
+ordine crescente all'interno dello scaffale e livelli dal pavimento verso
+l'alto. Il documento [ordinamento.md](ordinamento.md) riporta per i dati
+analizzati la sequenza interna a -> b -> c -> d -> e.
+
+La modifica non deve rinumerare Celle.Ordinamento ne' inventare nuovi percorsi
+per celle eventualmente configurate con eccezioni.
+
+### R05. Area 5 / MDE5
+
+Conservare l'ordinamento esistente delle celle. Nel default e' il percorso
+storico rappresentato da Celle.Ordinamento, con serpentina fra scaffali.
+
+Esempio documentato del blocco 1A/2B:
+
+```text
+1A.1 -> 2B.1 -> 2B.2 -> 1A.2 -> 1A.3 -> 2B.3 -> ...
+```
+
+All'interno delle campate analizzate l'ordine e' e -> d -> c -> b -> a,
+quindi dall'alto verso il basso. E' confermato che anche la prima UDC
+proposta deve rispettare questo verso: non partire dal pavimento in area 5.
+Non sostituire questo percorso con un generico ordinamento numerico
+scaffale/colonna/livello dell'area 6.
+
+### R06. Effetto della personalizzazione
+
+La personalizzazione mantiene il significato attuale: cambia la precedenza
+dei gruppi/scaffali, mentre dentro ogni gruppo si conserva l'ordine delle celle.
+Con due liste, la stessa scelta si applica all'intero contenuto della coppia.
+
+Per esempio, porre tutto 1A prima di tutto 2B elimina intenzionalmente
+l'alternanza fra quei due scaffali, come avviene gia' nella personalizzazione
+attuale. Non sarebbe corretto promettere contemporaneamente tale precedenza
+e il mantenimento della serpentina globale.
+
+I gruppi omessi da una personalizzazione parziale devono essere accodati con
+il criterio attuale, senza perdere le relative UDC.
+
+## 6. Scelta della prossima UDC
+
+### R07. Confronto continuo delle due liste
+
+A ogni passo confrontare le UDC ancora lavorabili di entrambe le liste e
+scegliere quella che viene prima nel percorso comune.
+Questa regola vale all'avvio, fra colonne consecutive, dopo un movimento e
+quando uno dei documenti non ha UDC nella colonna corrente.
+
+Non si deve usare F1 come guida unica, cercando F2 soltanto nelle colonne
+incontrate da F1: questo lascerebbe indietro le colonne presenti solo in F2.
+
+### R08. Il percorso prevale sull'identita' della lista
+
+Non esiste una precedenza fissa F1-prima-di-F2 nella stessa colonna.
+Se nell'area 6 i livelli dal basso verso l'alto appartengono a F2, F1 e F2,
+il prelievo deve seguire F2 -> F1 -> F2.
+
+La precedente ipotesi di esaurire tutte le UDC F1 della colonna e solo dopo
+quelle F2 e' superata: la scelta si compie sulla posizione a ogni passo.
+
+### R09. Nessuna UDC persa e nessun documento estraneo
+
+Il contenuto lavorato e' l'unione delle UDC residue delle due liste.
+Le UDC su piu' righe lotto devono essere considerate una sola volta come
+unita' fisica di prelievo. Ogni proposta deve mantenere l'identita' del
+documento a cui appartiene.
+
+Non introdurre la scelta automatica di una terza lista, neanche al termine
+di una delle due. La gestione delle UDC saltate e' trattata al punto 10.
+
+## 7. Avvio neutro e tasti F1/F2
+
+### R10. Avvio scelto dal sistema
+
+Quando il terminalino mostra Pronto per la coppia, il sistema deve avere gia'
+individuato la prima proposta. L'operatore non decide arbitrariamente da quale
+documento partire.
+
+Se la prima UDC appartiene alla Lista 2, F2 e' abilitato e F1 disabilitato;
+se appartiene alla Lista 1, vale il contrario. Il blocco deve valere sia per
+i pulsanti sullo schermo sia per i tasti fisici.
+
+### R11. Guida durante il giro
+
+Nel prelievo abbinato deve essere selezionabile soltanto la lista proposta
+dal percorso. Il cambio automatico verso l'altro documento non richiede una
+nuova scelta dell'operatore.
+
+La precedente modalita' manuale F1/F2 e il nuovo giro guidato non devono
+essere confusi: nel giro guidato i due tasti identificano documenti stabili,
+ma non autorizzano a scavalcare il percorso stabilito.
+
+### Chiarimento confermato: la prima cella dipende dal percorso dell'area
+
+Si parte dalla prima UDC secondo il percorso effettivo comune, rispettando
+anche all'avvio l'ordine dell'area e l'eventuale personalizzazione.
+La precedente espressione "cella piu' bassa" non e' una regola universale:
+
+- Area 5: nella campata prevista dal percorso, prima la cella occupata
+  richiesta piu' in alto, poi quelle inferiori (e -> d -> c -> b -> a).
+- Area 6: nella colonna prevista dal percorso, prima la cella occupata
+  richiesta piu' vicina al pavimento, poi quelle superiori (a -> b -> c -> d -> e).
+
+Il confronto comprende entrambe le liste: in area 5, se F1 ha una UDC al
+livello a e F2 ne ha una al livello d della stessa campata, si propone prima
+F2/d e poi F1/a. Non conta quale documento occupa il ruolo di Lista 1.
+Restano la serpentina del default area 5, l'ordine comune eventualmente
+personalizzato e la precedenza delle Non scaff. descritta in R14.
+
+## 8. Identificazione visiva sul terminalino
+
+### R12. Colori stabili
+
+| Documento assegnato | Colore di contesto |
+|---|---|
+| Lista 1 / F1 | Rosellino |
+| Lista 2 / F2 | Giallino |
+
+Il colore segue il documento e non la sua posizione nel giro: se inizia F2,
+lo sfondo iniziale e' giallino. La stessa lista conserva il proprio colore
+nei successivi passaggi.
+
+Il numero della picking list e il ruolo Lista 1/Lista 2 devono essere leggibili
+insieme all'UDC e alla cella proposta: il colore non deve essere l'unica
+informazione per capire quale documento si sta lavorando.
+
+La barra esito mantiene il significato funzionale dei propri colori
+(successo, errore, attesa), distinguibile dallo sfondo di contesto.
+Il layout deve restare utilizzabile sul terminalino 240 x 320.
+
+## 9. Ciclo di scansione e conferma
+
+### R13. Sequenza ordinaria
+
+1. Il sistema propone UDC, cella sorgente e documento; applica il colore relativo.
+2. L'operatore legge il barcode della UDC proposta.
+3. Rimangono i controlli attuali di corrispondenza e avvio automatico della lettura.
+4. Il movimento di picking porta la UDC in spedita, 7G.1.1, destinazione 9000000.
+5. Il terminalino mostra l'esito positivo per i tre secondi previsti.
+6. Il sistema propone la prossima UDC della coppia secondo il percorso comune.
+7. Se cambia documento, aggiorna insieme colore, riferimento lista e tasti abilitati.
+
+L'esito dei tre secondi appartiene al movimento appena concluso, non al
+documento che verra' proposto dopo. Non deve comparire un contesto misto.
+
+Un cambio programma della UDC visualizzata non deve simulare una scansione
+dell'operatore: va preservata la protezione contro gli auto-submit accidentali.
+Un errore o un esito incerto non deve avanzare il giro come se il movimento
+fosse riuscito; restano necessarie le verifiche e il recupero gia' esistenti.
+
+## 10. Non scaffalate, salti, pausa e fine giro
+
+### R14. Non scaffalate
+
+Conservare il comportamento corrente: Non scaff. precede gli scaffali nel
+default, salvo diversa posizione assegnata nella sequenza personalizzata.
+La regola deve considerare le UDC di entrambe le liste.
+
+La cella virtuale e' condivisibile e non ha un livello fisico da confrontare.
+Il criterio di parita' fra UDC non scaffalate delle due liste resta da
+concordare; proposta: ordine stabile per ruolo lista e codice UDC.
+
+### R15. UDC saltate: approfondimento rinviato
+
+Il comando Salta UDC esiste gia'. L'utente ha chiesto di analizzarne in seguito
+il comportamento nel nuovo giro abbinato, con l'intenzione di conservare
+quanto possibile il funzionamento attuale.
+
+Restano da decidere il termine della singola lista con soli skip, la sua
+sprenotazione, la prosecuzione dell'altra lista e le modalita' di ripresa.
+Saltare una UDC non deve comunque equivalere a spedirla o cancellarla dalla lista.
+
+### Pausa e ripresa: comportamento da completare
+
+Oggi Pausa PL consente movimenti liberi e ESC riporta al picking.
+Nel nuovo giro occorre conservare identita' dei due documenti e percorso.
+Va deciso se al rientro mantenere la UDC gia' proposta o ricalcolare la
+prossima posizione quando nel frattempo cambiano le ubicazioni.
+I movimenti liberi devono mantenere le proprie regole di carico e scarico.
+
+### Fine di una lista: proposta ancora da confermare
+
+Quando una lista non ha piu' UDC residue, proseguire con l'altra mantenendone
+ruolo e colore originali. Non promuovere automaticamente F2 a F1 e non
+aggiungere un terzo documento. Distinguere esaurimento reale e soli skip.
+
+## 11. Esempi di percorso atteso
+
+### Esempio A: colonne presenti soltanto in F2
+
+Area 6, stesso scaffale, default: colonne crescenti e livelli dal basso
+verso l'alto.
+
+| Passo | Posizione | Lista proposta |
+|---|---|---|
+| 1 | Colonna 1, livello a | F2 |
+| 2 | Colonna 2, livello a | F2 |
+| 3 | Colonna 3, livello a | F1 |
+| 4 | Colonna 3, livello b | F2 |
+| 5 | Colonna 4, livello a | F2 |
+| 6 | Colonna 5, livello a | F2 |
+| 7 | Colonna 6, livello a | F1 |
+
+F1 ha UDC solo ogni tre colonne. Le colonne intermedie di F2 vengono visitate
+al momento corretto, senza attendere il termine di F1.
+
+### Esempio B: alternanza verticale nella stessa colonna
+
+| Passo | Posizione | Lista proposta |
+|---|---|---|
+| 1 | Colonna 3, livello a | F2 |
+| 2 | Colonna 3, livello b | F1 |
+| 3 | Colonna 3, livello d | F2 |
+| 4 | Colonna 4, livello a | F1 |
+
+Il passaggio F2 -> F1 -> F2 e' richiesto dal percorso; i documenti associati
+ai tasti restano gli stessi.
+
+### Esempio C: area 5 con default storico
+
+| Ordinamento cella | Ubicazione | Lista proposta |
+|---|---|---|
+| 1001 | 1A.1.e | F2 |
+| 1003 | 1A.1.c | F1 |
+| 1007 | 2B.1.e | F1 |
+| 1010 | 2B.1.b | F2 |
+| 1013 | 2B.2.e | F2 |
+| 1019 | 1A.2.e | F1 |
+
+Si uniscono le due liste rispettando i valori del percorso storico; non si
+raggruppano automaticamente tutte le colonne 1A prima di quelle 2B.
+
+### Esempio D: ordine personalizzato della coppia
+
+Il responsabile imposta Non scaff. -> 4P -> 1M. Il terminalino lavora tutte
+le UDC richieste dalle due liste in Non scaff., poi quelle in 4P, poi quelle
+in 1M, applicando dentro ciascun gruppo l'ordine delle celle previsto.
+Gli eventuali gruppi non configurati vengono accodati, mai esclusi.
+
+## 12. Garanzie e decisioni tecniche da tradurre in progetto
+
+La prenotazione attuale a documento unico deve evolvere per rappresentare
+esplicitamente due documenti con ruoli stabili e una sequenza comune.
+Il formato delle nuove tabelle e le modifiche alle stored non sono ancora
+definiti da questo documento.
+
+La nuova prenotazione dovra' essere salvata in modo atomico, evitando che il
+terminalino legga meta' coppia o una sequenza parzialmente aggiornata.
+Le modifiche SQL dovranno avere script di installazione e di ripristino e
+mantenere la separazione degli oggetti Python dagli oggetti legacy C#.
+
+Sono ancora da specificare persistenza della ripresa dopo riavvio, modifiche
+alla coppia durante un giro, modifiche della sequenza a giro iniziato e
+comportamento con piu' terminalini. Non assumere che la memoria locale del
+singolo client sia una soluzione completa per questi casi.
+
+## 13. Dati locali predisposti per il collaudo
+
+Il 01/10/2026 sono state riattivate nella copia locale quattro testate SAM
+cambiando solo D in P, senza movimentare UDC. Con filtro 30 giorni:
+
+| Lista | UDC residue | In celle fisiche | Non scaffalate nella vista |
+|---|---:|---:|---:|
+| 233 | 28 | 3 | 25 |
+| 234 | 28 | 2 | 26 |
+| 240 | 11 | 0 | 11 |
+| 241 | 28 | 0 | 28 |
+| 244, gia' attiva | 26 | 24 | 2 |
+
+Le celle fisiche candidate sono risultate prive di altre UDC, anche esterne
+alle cinque liste. Le UDC residue non sono condivise fra questi documenti.
+La condivisione della locazione virtuale Non scaff. e' invece prevista.
+
+Esempi utili in area 5: 234 in 1A.7.a e 244 in 1A.7.d; 233 in 1A.18.a e
+244 in 1A.18.c. Sono celle distinte della stessa colonna.
+
+La voce Non scaff. puo' derivare anche dal fallback di una UDC senza giacenza
+WMS: non prova da sola l'esistenza di un versamento registrato nella cella 1000.
+
+Questi dati non bastano a verificare tutte le alternanze verticali e le colonne
+intermedie in area 6: occorrera' predisporre ulteriori casi controllati prima
+del collaudo completo. Non creare documenti ERP fittizi o spostare UDC online
+per ottenere tali scenari.
+
+Preparazione e ripristino sono descritti in [sql_tests/README.md](sql_tests/README.md).
+Il ripristino delle testate non annulla le movimentazioni fatte durante i test.
+
+## 14. Criteri di accettazione
+
+| Test | Risultato atteso |
+|---|---|
+| Una sola lista | Ordinamento attuale conservato |
+| Due liste entrambe Area 5 oppure entrambe Area 6 | Abbinamento consentito, applicando il percorso della relativa area |
+| Una lista Area 5 e una Area 6 | Abbinamento rifiutato senza modificare le prenotazioni esistenti |
+| F2 precede F1 nel percorso | All'avvio solo F2 utilizzabile |
+| F1 presente ogni tre colonne | Nessuna colonna intermedia F2 omessa |
+| Livelli alternati F2/F1/F2 | Tre proposte in ordine fisico, con documenti corretti |
+| Default area 5 | Serpentina attuale e livelli dall'alto verso il basso, anche all'avvio |
+| Area 5: F1 in 1A.7.a, F2 in 1A.7.d | Prima F2/d, poi F1/a, senza precedenza fissa a F1 |
+| Default area 6 | Percorso corrente per scaffale, colonne crescenti e livelli dal basso verso l'alto |
+| Personalizzazione della coppia | Stesso ordine applicato a entrambe |
+| Gruppo presente solo in F2 | Visibile nell'editor e incluso nel percorso |
+| Gruppo omesso dalla personalizzazione | Accodato secondo il comportamento attuale |
+| Tasto fisico della lista disabilitata | Nessun cambio documento e nessun movimento |
+| Cambio automatico | Numero lista, colore e UDC aggiornati coerentemente |
+| UDC con due lotti | Un solo prelievo fisico |
+| Terza lista disponibile | Mai inserita automaticamente nel giro |
+| Aggiornamento programma del campo UDC | Non interpretato come nuova lettura |
+| Movimento fallito o esito incerto | Nessun avanzamento ingiustificato |
+
+I casi relativi a skip, fine parziale, pausa, riavvio e modifiche concorrenti
+andranno completati dopo la decisione delle relative regole.
+
+## 15. Decisioni aperte per la revisione
+
+L'avvio e' chiarito: si rispetta il percorso dell'area, dall'alto in area 5
+e dal basso in area 6. Restano aperti i punti seguenti.
+
+1. Assegnazione esplicita dei ruoli Lista 1 e Lista 2 sul desktop.
+2. Gestione delle sequenze preesistenti quando si compone una nuova coppia.
+3. Ordine fra UDC non scaffalate o con identico valore di percorso.
+4. Salti, esaurimento con residui e riprenotazione della coppia o di una lista.
+5. Ripresa dalla pausa e da un riavvio, con ubicazioni eventualmente cambiate.
+6. Modifiche alla coppia/sequenza mentre il prelievo e' in corso.
+7. Fonte autorevole dell'area di una lista e gestione di liste internamente
+   miste o con area indeterminata; le coppie Area 5/Area 6 sono vietate (R02a).
+8. Condotta su dati anomali: stessa UDC in due liste o cella fisica con piu' UDC.
+   Il dataset di collaudo evita questi casi; la regola generale resta da definire.
+
+Le risposte possono essere annotate direttamente in questa sezione prima di
+passare al progetto tecnico e alle modifiche applicative.