TieMeasureFlow/docs/specs/2026-09-14-visione-stato-e-specifica.md

La visione in TieMeasureFlow — stato verificato e specifica del lavoro che manca

Progetto: TieMeasureFlow, ramo V3.0.0 (HEAD 39a6f62, 17/08/2026) Data: 14 settembre 2026 Stato: specifica da approvare Sostituisce, come documento operativo: il piano docs/superpowers/plans/2026-08-16-vision-fondamenta-server.md (eseguito) e la corsia A1-tiemeasureflow.md del piano ferie (eseguita, cancellata dal disco il 01/09 e recuperabile con git show 874a7a4^:docs/plans/corsie-fase2/A1-tiemeasureflow.md nel repo AI-OS). Resta in vigore docs/superpowers/specs/2026-08-16-visionsuite-integration-design.md: le sue otto decisioni architetturali non vengono riscritte qui, vengono richiamate.

1. Perché questo documento

Fra il 16 e il 17 agosto sono entrate in TieMeasureFlow le fondamenta della visione: ventiquattro commit, sette file di test nuovi, tre migrazioni. Da allora il lavoro si è fermato. Nel frattempo VisionSuite è andato avanti di sessantasette commit, la scheda di commessa non registra nulla dopo il 25 agosto, e l'installazione a Tràfilo, prevista per settembre, è alle porte insieme alla fiera del 27-29 ottobre.

Questo documento fa due cose. Prima dichiara, verificandolo sul codice e non sui piani, che cosa esiste davvero sul ramo V3.0.0. Poi specifica che cosa manca per arrivare a ciò che il cliente ha chiesto il 27 luglio: pattern matching, confronto del profilo con il disegno DXF e due o tre quote lineari, dentro l'interfaccia di TieMeasureFlow, con l'esito OK/warning/fail che il prodotto già sa dare.

La distanza fra le due cose è più grande di quanto i documenti di agosto lascino credere, e la ragione è una sola, spiegata al capitolo 3.

2. Quello che esiste, verificato sul ramo V3.0.0

Ogni riga di questa tabella è stata controllata aprendo il file indicato nel clone del ramo V3.0.0 il 14/09/2026. Non è lo stato dichiarato da un piano: è lo stato del disco.

Cosa	Stato	Dove si vede
VisionSuite come sottomodulo git, su commit fisso	✅	.gitmodules, pin f095fcc (15/08)
Runner unico, senza HTTP né database	✅	src/vision/runner.py, 129 righe
Versione del motore timbrata su ogni numero prodotto	✅	runner.engine_version(), errore se non risolve
Vision worker come servizio separato nel compose	✅	src/vision_worker/main.py, Dockerfile.vision, servizio vision
Il server non importa mai VisionSuite	✅ e sorvegliato	src/backend/tests/test_vision_boundary.py
Grafo di visione sul task (vision_json)	✅	migrazione 011, models/orm/task.py
Legame quota del grafo → quota della ricetta (vision_output)	✅	migrazione 011, recipe_subtasks
camera fra i metodi di ingresso misura	✅	migrazione 011, enum input_method
Tabella vision_results, una riga per acquisizione	✅	migrazione 012, models/orm/vision.py
Immagini di riferimento con provenienza	✅	migrazione 013, vision_reference_images
Il verdetto lo dà TieMeasureFlow, non il grafo	✅	vision_service chiama measurement_service
Gate del fuori tolleranza valutato per acquisizione	✅	enforce_tolerance_gate=False più gate a monte
Copy-on-write delle ricette che copia anche il grafo	✅	test_vision_copy_on_write.py
Il refuso xf_compare corretto in dxf_compare	✅	migrazione 011, prima che una riga lo usasse
Limiti di tipo e dimensione sugli endpoint di upload	✅	test_vision_upload_limits.py
Il guasto del worker resta del worker	✅	vision_service._call_worker, 502/504 nominati
L'applicazione parte senza internet	✅	static/vendor/, test_offline.py
API POST /api/vision/execute, /preview, /reference-images	✅	api/routers/vision.py

Trentanove test di visione fra src/backend/tests/test_vision_*.py, src/vision/tests/ e src/vision_worker/tests/. ⚠️ Non li ho eseguiti: l'albero della visione richiede Python 3.13 e il sottomodulo inizializzato, cioè un'installazione da alcuni gigabyte che su questa macchina non c'è. Il conteggio è dei file; la loro verdezza è dichiarata dai commit del 16-17 agosto e va riverificata da chi riprende, prima di scriverci sopra.

In sintesi: le fondamenta ci sono e sono fatte bene. Il confine architetturale è difeso da un test invece che da una buona intenzione, la provenienza di ogni numero è tracciata, e il modello dati regge il resto del lavoro senza ristrutturazioni.

3. Il buco strutturale: pattern matching e DXF compare non sono eseguibili dal grafo

È il punto che i documenti di agosto non dicono, ed è quello che decide il calendario.

Il runner esegue un grafo vs-task: Task.from_dict(graph), poi task.run(context). Gli strumenti che un grafo può contenere sono quelli registrati in vs-task, e al 14/09 — sia sul commit fissato f095fcc, sia sull'ultimo commit di VisionSuite — sono dieci, tutti geometrici:

DetectLine, DetectCircle, CircleCenter, PointIntersectionLL, Distance2P, DistancePL, DistanceCL, Angle2L, Radius, Diameter.

Nessuno strumento di pattern matching. Nessuno strumento di confronto DXF. Una ricerca di pm2d, shape_model o dxf dentro packages/vs-task/src non trova nulla.

Coerentemente, in pyproject.toml gli extra vision e vision-worker installano visionsuite (core), vs-task, vs-measure, vs-pm2d e numpy: vs-dxf non è installato affatto, e vs-pm2d è installato ma il grafo non ha modo di chiamarlo.

I due motori esistono, e sono buoni: visionsuite.pm2d ha il matcher e l'auto-tune, visionsuite.dxf ha DXFCompare, l'ICPAligner, il ricampionamento, il controllo di tolleranza e il generatore di rapporto. Ma sono librerie, non strumenti di grafo. Fra loro e TieMeasureFlow manca un ponte, e il ponte va costruito in VisionSuite, non qui: la decisione 4 della spec di agosto — il server non importa mai VisionSuite — e il criterio di accettazione della corsia A1 — «grep non trova algoritmi di visione dentro il repo di TieMeasureFlow» — rendono illegittima qualunque scorciatoia che scriva visione dentro questo repository.

🔑 La conseguenza commerciale, detta chiara: oggi TieMeasureFlow sa eseguire un grafo che misura distanze, angoli, raggi e diametri su un'immagine. Le due cose che Menoncin ha chiesto per nome — il confronto DXF, che il suo cliente finale non ha, e il pattern matching, che il loro «funziona male» — non sono ancora raggiungibili da nessun percorso del prodotto.

4. Le altre lacune, in ordine di peso

1. Nessuna interfaccia. Nel frontend Flask la visione compare in due sole righe di templates/measure/task_list.html, le etichette «Confronto profilo» e «Misura camera». Non esiste la schermata del Maker per comporre un grafo, scegliere un'immagine di riferimento, agganciare un'uscita a una quota o premere «prova»; non esiste la schermata dell'operatore che acquisisce e vede l'esito. Oggi un grafo entra solo via POST /api/tasks scrivendo il JSON a mano.
2. Nessun agente di stazione, nessun registro dei device. La tabella station_devices della spec non esiste in nessuna migrazione; il WebSocket /api/stations/agent non esiste; vs-camera, cioè il pacchetto che contiene il driver Itala, non è montato. L'unico modo di far entrare un'immagine è un upload HTTP.
3. L'immagine di produzione non viene conservata. vision_results.image_path e overlay_path migrano e restano vuote: nessuna riga le scrive. Una misura contestata non ha prova materiale, e l'overlay — l'immagine con sopra le zone dove il sistema ha guardato — non esiste.
4. La prova di non regressione è promessa e non mantenuta. expected_json esiste sulla tabella delle immagini di riferimento; nessun percorso la scrive, preview compreso. È la rete di sicurezza che rende sostenibile aggiornare il sottomodulo con il motore installato su due host: senza, ogni aggiornamento di VisionSuite è un salto al buio.
5. Il sottomodulo è indietro di 67 commit, dal 15/08 al 10/09. Fra questi c'è almeno una correzione di vs-core sulla ricomposizione dei mosaici. Aggiornare il pin non è manutenzione facoltativa: è la decisione 2 della spec, che vuole server e stazione sullo stesso commit, e va fatta con la prova di non regressione già in piedi — cioè dopo il punto 4, non prima.
6. Le tre verifiche a monte non sono mai state fatte, e la spec di agosto le poneva come condizione d'ingresso: lo stato reale di VisionSuite rispetto al suo README, il test di calibrazione dato per rosso (focale recuperata a 373 contro 456 attesi, tolleranza 5%) e il peso effettivo del sottoinsieme di pacchetti che il worker installa. La seconda pesa più delle altre: tutte le quote in millimetri poggiano sulla calibrazione, e finché quel test non è verde o spiegato, i millimetri che il sistema produce non hanno garanzia.

5. Che cosa si vuole ottenere

Un operatore apre un task di visione su una postazione, appoggia il profilato sul piano, e il sistema:

• riconosce il pezzo e la sua posa (pattern matching);
• ne confronta il profilo con il DXF di riferimento, dichiarando lo scarto massimo e dove sta;
• ne ricava due o tre quote lineari (le quote massima e minima che il cliente chiede);
• applica le tolleranze della ricetta e dà OK / warning / fail, con il gate del fuori tolleranza e l'autorizzazione del capoturno come per qualunque altra misura;
• registra tutto in measurements e vision_results, con immagine, overlay, versione del motore e taratura in vigore.

Nulla di quanto il prodotto già fa — ricette, SPC, Cp/Cpk, carta di controllo, export, tracciabilità — deve cambiare. Una quota da camera resta una misura come le altre: è la decisione 7, e va tenuta.

6. Il lavoro, in sei fasi

Le fasi sono ordinate per dipendenza. Le prime due sono il cammino critico verso la fiera; la terza è il cammino critico verso l'installazione a Tràfilo. Non sono stimate in ore: una stima si scrive dopo aver guardato il codice dei due motori, e quella lettura fa parte della fase V0.

V0 — Le verifiche a monte, prima di scrivere righe

Le tre della spec di agosto (capitolo 4, punto 6), più una quarta che nasce da questo documento: leggere visionsuite.pm2d.matcher e visionsuite.dxf.compare per sapere che forma hanno gli ingressi e le uscite dei due motori, perché è quella forma che decide la firma degli strumenti della fase V1.

Fatto quando: il test di calibrazione è verde o il suo scarto è spiegato per iscritto; il peso dell'ambiente del worker è un numero misurato; esiste una nota di due pagine con le firme reali dei due motori.

V1 — Il ponte: pattern matching e DXF compare diventano strumenti del grafo

Si lavora in VisionSuite, non in TieMeasureFlow. In vs-task nascono gli strumenti nuovi, con la stessa forma dei dieci esistenti:

• MatchPattern — ingresso: immagine più modello; uscite: presenza, punteggio, posizione e rotazione dell'istanza trovata. È anche ciò che fornisce la posa alle quote successive, invece di pretendere che il pezzo sia appoggiato sempre uguale.
• CompareDXF — ingressi: immagine, disegno di riferimento, fattore di scala; uscite: scarto massimo, scarto medio, numero di zone fuori tolleranza, e l'esito zona per zona.

Due vincoli che decidono se il ponte è fatto bene:

1. Gli strumenti espongono numeri, non verdetti. vs-dxf ha di suo un ToleranceChecker e un CompareResult con il proprio giudizio: quel giudizio va ignorato, esattamente come la decisione 7 impone già per le quote di vs-measure. Due giudici sullo stesso valore è il modo più rapido per ottenere un CSV che si contraddice.
2. vs-dxf si porta dietro PyTorch (~2,5 GB) per una riga (config.py:53, annotato nella scheda VisionSuite). Prima di aggiungerlo agli extra del worker, quella riga va tolta: altrimenti il container della visione triplica, e con lui i tempi di ogni deploy a Tràfilo.

In TieMeasureFlow cambia soltanto pyproject.toml: vs-dxf entra negli extra vision e vision-worker, il pin del sottomodulo avanza al commit che contiene i due strumenti nuovi. Nessuna riga di algoritmo entra in questo repository.

Fatto quando: un grafo JSON che contiene MatchPattern e CompareDXF viene eseguito da POST /api/vision/preview su un'immagine caricata, e restituisce le uscite attese. Senza camera, senza interfaccia. E test_vision_boundary.py continua a passare.

V2 — L'authoring nel Maker

La schermata che oggi non esiste. Il Maker, alla scrivania:

• carica o sceglie un'immagine di riferimento per il task (l'API esiste già);
• compone il grafo — e qui va deciso come, vedi il capitolo 7, decisione A;
• preme prova e vede le uscite (/preview esiste già);
• aggancia ciascuna uscita a una quota della ricetta, scrivendo vision_output sulla subtask (il campo esiste già), e su quella quota mette nominale e tolleranze come su qualunque altra;
• promuove le uscite della prova a expected_json, che è ciò che accende la prova di non regressione (lacuna 4) e chiude una promessa che la spec di agosto ha fatto e non ha mantenuto.

Fatto quando: una ricetta con un task di visione si compone interamente dall'interfaccia, senza scrivere JSON a mano, e rieseguendo l'intero parco ricette su immagini di riferimento si vede quali quote si sono mosse.

V3 — L'agente di stazione, i device, la camera

È il cammino critico per Tràfilo, perché è ciò che rende il sistema utilizzabile in reparto.

• Tabella station_devices e migrazione, così com'è descritta nella spec di agosto (specchio in sola lettura, popolato dall'agente; un device che non si dichiara più è offline, non cancellato).
• WebSocket /api/stations/agent: è l'agente che apre la connessione, il server non bussa mai a un PC di reparto. È la scelta che evita di aprire porte in fabbrica.
• L'agente: sottile, monta vs-core e vs-camera e basta; acquisisce e carica il fotogramma. Camera Itala di Opto Engineering, il cui producer GenTL è già stato provato in VisionSuite e ha richiesto mezz'ora invece delle sei-dieci ore stimate.
• vision_results.image_path e overlay_path finalmente scritte (lacuna 3), con l'overlay prodotto dal worker.

Fatto quando: un operatore misura un pezzo da una postazione vera, e la riga in vision_results porta immagine, overlay, device, taratura e versione del motore.

V4 — L'esecuzione sulla stazione

La policy per stazione, il ripiego in locale quando il server non risponde, e il rifiuto di misurare quando la versione del motore non concorda con quella del server. Quest'ultimo non è un dettaglio di build: è la garanzia metrologica su cui poggia tutto il resto.

Fatto quando: una stazione con un pin discorde si rifiuta di misurare e lo dichiara, invece di produrre numeri plausibili.

V5 — Il task dxf_compare come tipo a sé

Il valore dxf_compare esiste già nell'enum. Qui prende il suo comportamento: quote sintetiche derivate dal confronto (scarto massimo, numero di zone fuori tolleranza) trattate come misure normali, e il rapporto allegato che visionsuite.dxf.report sa già generare, archiviato accanto all'immagine.

7. Le decisioni che restano da prendere

Nessuna di queste si può dedurre dal codice: vanno chiuse da Adriano, alcune con il cliente.

A. Come si compone un grafo. L'editor visuale a nodi (TieWorkflow) è stato revocato il 09/08 con una motivazione che vale ancora: un editor ha senso solo se a comporre le pipeline è qualcuno che non programma, e il cliente aveva chiesto misure, non un editor. Ma qualcosa deve pur esserci, perché scrivere JSON a mano non è un prodotto. Le tre strade: un modulo per tipo di task con i soli parametri in chiaro (il minimo che funziona); una libreria di grafi preconfezionati che il Maker sceglie e tara; l'editor, che è la strada cara. Questa decisione decide la fase V2 per intero.

B. La scala: pixel o millimetri. Il 09/08 si era deciso che le quote potessero restare in pixel, e che per il DXF compare servisse un fattore di scala ricavato da una quota nota misurata col calibro. Va confermato: sono due prodotti diversi da spiegare al cliente, e il secondo dipende dal test di calibrazione della fase V0.

C. Il dimensionamento del server di Tràfilo. Con l'esecuzione lato server come default, il pattern matching contende la CPU fra tutte le stazioni. La domanda alla D-4 non è più solo quale macchina e quanto disco: è anche quanti core e quanta RAM. Venti postazioni non sono tre.

D. La conservazione delle immagini. Quelle di riferimento sono poche e vivono quanto la ricetta; quelle di produzione sono una per pezzo e crescono senza limite. Serve una scadenza, o una regola del tipo «si conservano solo quelle dei pezzi fuori tolleranza». Senza, il disco del cliente si riempie e nessuno lo ha avvertito.

E. Che cosa fa la stazione se la rete cade e non è configurata per elaborare in locale: si blocca, o consente il calibro segnando il task come non eseguibile? È una domanda per Tràfilo.

F. Chi paga — chiusa il 14/09/2026. Nessuno, ed è una scelta. Il modulo di visione è un investimento commerciale di Tielogic: non si quota a Ricerca e Misure, non entra nel setup né nel canone dell'OFF-2026-022, e non aspetta un'offerta per cominciare. Serve a prendere lavori futuri, e il posto dove quell'investimento si trasforma in lavori è la fiera.

Ne discendono tre conseguenze che questo documento adotta:

1. Il modulo non ha una data di consegna contrattuale, quindi l'unica scadenza che lo governa è la fiera del 27-29 ottobre. La fase V1 è l'unica del percorso visione che ha una data vera.
2. Tràfilo va servito con il perimetro venduto — le dodici modifiche del 28/07, l'installazione on-premise, l'agente di stazione — e quel lavoro non si rallenta per la visione: è quello che è già stato fatturato. Dove la visione e Tràfilo si contendono le stesse ore, vince ciò che è stato venduto, con l'unica eccezione della V1 prima della fiera.
3. Il confine va tenuto per iscritto: le ore spese per la fiera sono a carico Tielogic, quelle spese per Tràfilo stanno nella commessa. Senza quella riga, a consuntivo il modulo di visione sembrerà un costo della commessa Ricerca e Misure e ne falserà il margine.

⚠️ Resta aperto un pezzo che non è «chi paga» ma «che cosa»: cosa si mostra in fiera non coincide con cosa si consegna. Una demo può girare su un grafo preparato, un pezzo noto e una posa controllata; un prodotto no. Deciderlo prima cambia l'ampiezza della V1.

8. Quello che non va fatto

• Non scrivere algoritmi di visione in questo repository. Il confine è sorvegliato da un test; se domani il server importasse VisionSuite per una scorciatoia, il vantaggio si perderebbe in silenzio.
• Non rifare l'interfaccia oltre le schermate nuove che le fasi V2 e V3 richiedono.
• Non toccare SPC, ricette e integrazione GAIA. GAIA è il gestionale del cliente finale e non è in questo perimetro.
• Non aggiungere il modulo AI di cui si è parlato in call: è perimetro nuovo, senza offerta.
• Non far giudicare il grafo. I verdetti di vs-dxf e di vs-measure restano inutilizzati: decide measurement_service.
• Non avanzare il pin del sottomodulo senza la prova di non regressione in piedi. Con il motore installato su due host, un aggiornamento non verificato sposta i numeri senza che nessuno se ne accorga fino alla contestazione.

9. Il calendario, per capire le priorità

La catena è Tielogic produce → Ricerca e Misure (Menoncin) rivende → Tràfilo usa, venti postazioni. Due scadenze esterne, entrambe vicine:

• Installazione a Tràfilo, attesa per settembre. La serve la fase V3, ed è la ragione per cui l'agente di stazione non può aspettare la fiera.
• Fiera del 27-29 ottobre, banchetto Tielogic nella zona Opto Engineering. La serve la fase V1, perché è lì che si mostrano il confronto DXF e il pattern matching, cioè le due cose che a Menoncin interessano commercialmente.

Se le due si contendono le stesse ore, la V1 è quella che non ha alternative: un'installazione può slittare di due settimane, una fiera no.