docs(readme,claude): Quick Start ricostruibile — sottomodulo e VISION_ENGINE_VERSION (#18)

README Quick Start: clone con --recurse-submodules (nota sulla chiave SSH per
git.tielogic.xyz:222), VISION_ENGINE_VERSION valorizzata prima di up --build,
comando già descritto più sotto nel documento e ora portato qui.

CLAUDE.md: titolo del layout V2.0.0 -> V3.0.0, aggiunti src/vision,
src/vision_worker, vendor/visionsuite all'albero; nuova sezione «Visione
(V3.0.0)» con sottomodulo, variabile, worker Python 3.13, comando dei test.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

CLAUDE.md

@@ -7,9 +7,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 TieMeasureFlow by Tielogic - Sistema di gestione task per misurazioni con calibro manuale.
 Monorepo con **backend FastAPI** (porta 8000) e **frontend Flask** (porta 5000), orchestrati con Docker Compose + Nginx reverse proxy + MySQL 8.0.
 
-## Layout del repository (V2.0.0)
+## Layout del repository (V3.0.0)
 
-A partire dalla migrazione V2.0.0 (struttura conforme alla spec `python-project-spec-design.md`):
+A partire dalla migrazione V2.0.0 (struttura conforme alla spec `python-project-spec-design.md`), con l'aggiunta del modulo di visione in V3.0.0 (`src/vision`, `src/vision_worker`, `vendor/visionsuite`):
 
 ```
 TieMeasureFlow/
@@ -18,10 +18,13 @@ TieMeasureFlow/
 ├── .python-version             # 3.11
 ├── Dockerfile                  # Backend (uv + uvicorn)
 ├── Dockerfile.frontend         # Frontend (uv + gunicorn + Tailwind + Babel)
+├── Dockerfile.vision           # Worker di visione (uv, Python 3.13)
 ├── docker-compose.dev.yml      # Dev (Nginx)
 ├── docker-compose.yml          # Prod (Traefik + SSL)
 ├── nginx/
 ├── uploads/                    # Volume montato in /app/uploads
+├── vendor/
+│   └── visionsuite/            # Submodule: libreria di visione (vs-core, vs-task, vs-measure, vs-pm2d)
 ├── docs/
 └── src/
     ├── backend/
@@ -38,16 +41,18 @@ TieMeasureFlow/
     │   ├── migrations/         # Alembic
     │   ├── templates/          # Setup page
     │   └── tests/              # pytest
-    └── frontend/
-        └── flask_app/          # Flask + Jinja2 + Alpine.js (deroga vs spec React,
-            ├── app.py          # giustificata: tablet UX server-side, USB calipers,
-            ├── config.py       # workflow operatore con Fabric.js)
-            ├── blueprints/
-            ├── services/
-            ├── templates/
-            ├── static/
-            ├── translations/
-            └── tests/
+    ├── frontend/
+    │   └── flask_app/          # Flask + Jinja2 + Alpine.js (deroga vs spec React,
+    │       ├── app.py          # giustificata: tablet UX server-side, USB calipers,
+    │       ├── config.py       # workflow operatore con Fabric.js)
+    │       ├── blueprints/
+    │       ├── services/
+    │       ├── templates/
+    │       ├── static/
+    │       ├── translations/
+    │       └── tests/
+    ├── vision/                 # Runner che esegue i grafi di VisionSuite (Python 3.13)
+    └── vision_worker/          # Shell FastAPI attorno al runner, container separato
 ```
 
 Dipendenze gestite con **uv** (no `requirements.txt`):
@@ -280,6 +285,23 @@ Il server esegue Alembic migrations automaticamente all'avvio (`CMD` include `al
 
 Nginx (dev): gzip abilitato, `client_max_body_size 50M`, `proxy_read_timeout 120s`, cache statica 7d, security headers duplicati a livello proxy.
 
+## Visione (V3.0.0)
+
+Il runner di visione (`src/vision/`) e il suo worker FastAPI (`src/vision_worker/`) dipendono da `vendor/visionsuite`, un **submodule** su `ssh://git.tielogic.xyz:222`: un `git clone` senza `--recurse-submodules` lascia la cartella vuota (chi ha già clonato: `git submodule update --init`). Le librerie di VisionSuite richiedono **Python 3.13**, mentre backend e frontend restano su Python 3.11 — è un albero a parte nel monorepo, isolato con il proprio extra `uv`.
+
+Il worker gira in un container separato (`Dockerfile.vision`), non pubblica porte verso l'esterno ed è raggiungibile solo dal server all'indirizzo interno `http://vision:8100`. Il container non ha accesso al repository Git del progetto principale, quindi il commit di VisionSuite in uso (`engine_version`) non può essere scoperto dentro l'immagine: va stampato al momento del build leggendo il commit dalla macchina che esegue `docker compose build`, con la variabile `VISION_ENGINE_VERSION`. Una build senza questa variabile fallisce subito, invece di produrre un worker che risponde con una versione indovinata:
+
+```bash
+VISION_ENGINE_VERSION=$(git -C vendor/visionsuite rev-parse HEAD) \
+  docker compose -f docker-compose.dev.yml build vision
+```
+
+Test del runner e del worker, in un ambiente Python 3.13 dedicato (con `uv run pytest` di default, su Python 3.11, questi test risultano *skipped*, non falliti):
+
+```bash
+uv run --python 3.13 --extra vision --extra vision-worker --extra dev pytest src/vision/tests src/vision_worker/tests
+```
+
 ## Convenzioni Codice
 - Python 3.11+, type hints ovunque
 - async/await per tutte le operazioni DB (server)

README.md

@@ -127,16 +127,25 @@ reparto.
 Docker Compose è il metodo raccomandato. Gestisce database, migrazioni, build delle immagini con `uv` e configurazione Nginx in un solo comando.
 
 ```bash
-# 1. Clona il repository
-git clone ssh://git@git.tielogic.xyz:222/Adriano/TieMeasureFlow.git
+# 1. Clona il repository CON il sottomodulo di VisionSuite (vendor/visionsuite):
+# senza --recurse-submodules la cartella resta vuota e la build del worker di
+# visione fallisce. Il sottomodulo è su ssh://git.tielogic.xyz:222: serve una
+# chiave SSH autorizzata su quel repo, sia sulla macchina di sviluppo sia sulla
+# VPS che farà la build.
+git clone --recurse-submodules ssh://git@git.tielogic.xyz:222/Adriano/TieMeasureFlow.git
 cd TieMeasureFlow
+# Chi ha già clonato senza il sottomodulo:
+#   git submodule update --init
 
 # 2. Configura le variabili d'ambiente
 cp .env.example .env
 # Modifica .env: credenziali DB, chiavi segrete, SETUP_PASSWORD, STATION_CODE per ogni tablet
 
-# 3. Avvia i servizi (ambiente di sviluppo)
-docker compose -f docker-compose.dev.yml up -d --build
+# 3. Valorizza VISION_ENGINE_VERSION PRIMA della build: il worker di visione
+# (Dockerfile.vision) rifiuta di costruirsi senza — vedi "Il worker di
+# visione" più sotto per il motivo. Poi avvia i servizi (ambiente di sviluppo).
+VISION_ENGINE_VERSION=$(git -C vendor/visionsuite rev-parse HEAD) \
+  docker compose -f docker-compose.dev.yml up -d --build
 
 # 4. Verifica lo stato dei container
 docker compose -f docker-compose.dev.yml ps