diff --git a/CLAUDE.md b/CLAUDE.md index fade97d..0677f32 100644 --- a/CLAUDE.md +++ b/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) diff --git a/README.md b/README.md index 624793a..3a1f4bc 100644 --- a/README.md +++ b/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