From cf2bf427fc1387b4ed8dfe30f0b5aa17a241300d Mon Sep 17 00:00:00 2001 From: Adriano Date: Sat, 7 Feb 2026 18:45:32 +0100 Subject: [PATCH] docs: rewrite CLAUDE.md with comprehensive project guidance for Claude Code Add dev commands (test, migrations, i18n, Docker), architecture overview, critical patterns (copy-on-write versioning, pass/fail, SPC, auth flow), and dependency/configuration reference. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 184 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 131 insertions(+), 53 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3e1f61a..226c873 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,71 +1,149 @@ -# TieMeasureFlow - Istruzioni Progetto +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Panoramica + TieMeasureFlow by Tielogic - Sistema di gestione task per misurazioni con calibro manuale. -Monorepo con server FastAPI (backend API) e client Flask (frontend tablet). +Monorepo con **server FastAPI** (backend API, porta 8000) e **client Flask** (frontend tablet, porta 5000), orchestrati con Docker Compose + Nginx reverse proxy + MySQL 8.0. -## Stack -- **Server**: FastAPI + SQLAlchemy 2.0 async + asyncmy + MySQL 8.0 -- **Client**: Flask 3.0 + Jinja2 + htmx 2.0 + Alpine.js 3.x + TailwindCSS 3.x -- **Grafici**: Plotly.js (browser) + Kaleido (server export SVG) -- **PDF**: WeasyPrint (HTML → PDF), PDF.js (rendering browser) -- **Annotazioni**: Fabric.js 6.x (editor Maker), Canvas overlay (display MeasurementTec) -- **i18n**: Flask-Babel (server) + alpinejs-i18n (client), lingue IT/EN -- **Auth**: API Key nell'header X-API-Key +## Comandi di Sviluppo -## Struttura +### Avvio servizi (Docker) +```bash +docker compose up -d # Avvia tutto +docker compose logs -f server # Log server +docker compose logs -f client # Log client +docker compose ps # Stato servizi ``` -TieMeasureFlow/ -├── server/ # FastAPI Backend (porta 8000) -│ ├── main.py # Entry point -│ ├── config.py # Settings da .env -│ ├── database.py # SQLAlchemy async engine -│ ├── models/ # SQLAlchemy ORM models -│ ├── schemas/ # Pydantic validation schemas -│ ├── routers/ # API endpoint routers -│ ├── services/ # Business logic -│ ├── middleware/ # API key auth, logging -│ └── migrations/ # Alembic migrations -├── client/ # Flask Frontend (porta 5000) -│ ├── app.py # Entry point -│ ├── blueprints/ # Flask route blueprints -│ ├── services/ # API client wrapper -│ ├── templates/ # Jinja2 HTML templates -│ ├── static/ # CSS, JS, immagini -│ └── translations/ # Flask-Babel i18n -└── docs/ # Documentazione + +### Avvio manuale (senza Docker) +```bash +# Server (terminale 1) +cd server && uvicorn main:app --reload --host 0.0.0.0 --port 8000 + +# Client (terminale 2) +cd client && flask run --host 0.0.0.0 --port 5000 + +# TailwindCSS watch (terminale 3) +cd client && npx tailwindcss -i static/css/input.css -o static/css/tailwind.css --watch ``` +### Database & Migrations +```bash +cd server && alembic upgrade head # Applica migrazioni +cd server && alembic revision --autogenerate -m "descrizione" # Genera migrazione +cd server && alembic downgrade -1 # Rollback ultima +docker compose exec server alembic upgrade head # Via Docker +``` + +### Test +```bash +# Server (usa SQLite in-memory via aiosqlite, no MySQL richiesto) +cd server && pytest # Tutti i test +cd server && pytest tests/test_auth.py # Singolo modulo +cd server && pytest tests/test_auth.py::test_login_success # Singolo test +cd server && pytest --cov # Con copertura + +# Client +cd client && pytest +cd client && pytest tests/test_auth.py +``` + +### i18n (Traduzioni) +```bash +# Estrai stringhe +cd client && pybabel extract -F babel.cfg -k _ -o translations/messages.pot . + +# Aggiorna catalogo +cd client && pybabel update -i translations/messages.pot -d translations + +# Compila .po → .mo +cd client && pybabel compile -d translations +# oppure +cd client && python compile_translations.py +``` + +### Setup iniziale +Dopo primo avvio, aprire `http://localhost/api/setup` (o `:8000/api/setup` senza Nginx) con la SETUP_PASSWORD dal `.env` per: inizializzare DB, creare admin, caricare dati demo. + +## Architettura + +### Flusso richieste +``` +Browser/Tablet → Nginx (:80/443) → Flask Client (:5000) → APIClient → FastAPI Server (:8000) → MySQL +``` +Il client Flask è un frontend server-side che comunica col backend via REST API. Ogni richiesta dal client al server include l'header `X-API-Key` per autenticazione. + +### Server (FastAPI) — `server/` +- **main.py**: entry point, registra middleware (RateLimit → SecurityHeaders → CORS → AccessLog) e 10 router +- **config.py**: `Settings` Pydantic che legge da `.env` +- **database.py**: SQLAlchemy 2.0 async engine con `AsyncSession`, pool 10+20 overflow +- **routers/**: auth, recipes, tasks, measurements, statistics, reports, files, users, settings, setup +- **services/**: recipe_service (versioning copy-on-write), measurement_service (calcolo pass/fail), spc_service (Cp/Cpk/control chart, puro stdlib senza numpy), report_service (WeasyPrint PDF + Kaleido SVG), auth_service (bcrypt + API key) +- **middleware/**: api_key.py (auth dependency), rate_limit.py (sliding window per-IP), security_headers.py (CSP, HSTS), logging.py (audit trail async su DB) +- **models/**: User, Recipe, RecipeVersion, RecipeTask, RecipeSubtask, Measurement, AccessLog, SystemSetting +- **schemas/**: Pydantic v2 per validazione I/O API +- **migrations/**: Alembic con alembic.ini nella directory migrations +- **tests/**: pytest + pytest-asyncio, database SQLite in-memory (aiosqlite), fixture pre-popolate (admin_user, maker_user, etc.), WeasyPrint mockato + +### Client (Flask) — `client/` +- **app.py**: factory pattern `create_app()`, CSRF protection, Babel i18n +- **blueprints/**: auth (login/logout/session), maker (editor ricette con Fabric.js), measure (esecuzione misurazioni), statistics (dashboard SPC con Plotly.js) +- **services/api_client.py**: singleton `APIClient` — wrapper HTTP (get/post/put/delete) con gestione errori normalizzata, timeout 30s, header X-API-Key da session +- **templates/**: Jinja2 con `{{ _('string') }}` per i18n +- **static/js/**: Alpine.js components, Fabric.js editor, locales JSON (it.json, en.json) +- **translations/**: Flask-Babel, cataloghi .po/.mo per IT/EN + +## Pattern Critici + +### Recipe Versioning (Copy-on-Write) +Le ricette usano un versioning immutabile: ogni modifica crea una nuova `RecipeVersion` con deep-copy di tasks e subtasks. Le misurazioni restano sempre legate alla versione originale. La versione corrente ha `is_current=True`, le precedenti `False`. Audit trail in `recipe_version_audit` (CREATE, UPDATE, RETIRE). Logica in `server/services/recipe_service.py`. + +### Calcolo Pass/Fail +Ogni subtask ha 4 limiti di tolleranza: UTL (upper tolerance), UWL (upper warning), LWL (lower warning), LTL (lower tolerance) più un valore nominale. Il calcolo in `server/services/measurement_service.py`: +- Fuori UTL/LTL → **fail** +- Fuori UWL/LWL ma dentro UTL/LTL → **warning** +- Dentro UWL/LWL → **pass** + +### SPC (Statistical Process Control) +Calcoli in `server/services/spc_service.py` usando solo `math` e `statistics` stdlib (no numpy/scipy): summary (conteggi pass/warning/fail), capability (Cp, Cpk, Pp, Ppk), control chart (UCL/LCL = mean ± 3σ), histogram (20 bin + curva normale). + +### Autenticazione +1. Login con username/password → server ritorna `api_key` (64 char random) +2. Client salva api_key in Flask session +3. Ogni richiesta API include header `X-API-Key` +4. Middleware `get_current_user()` autentica, `require_role()` autorizza +5. Dependency pre-built: `require_maker`, `require_measurement_tec`, `require_metrologist`, `require_admin_user` + +### Ruoli Utente +Combinabili (JSON array): **Maker** (crea ricette), **MeasurementTec** (esegue misurazioni), **Metrologist** (dashboard SPC). Flag `is_admin` separato. + +### File Storage +Upload in `uploads/{recipe_id}/{version_id}/`. Tipi ammessi: JPEG, PNG, GIF, WebP, PDF. Limite 50MB. Thumbnail auto-generate per immagini (Pillow). Sanitizzazione filename. + ## Convenzioni Codice - Python 3.11+, type hints ovunque - async/await per tutte le operazioni DB (server) - Pydantic v2 per validazione I/O API - Nomi variabili e commenti in inglese, UI strings in IT/EN via i18n -- File imports ordinati: stdlib, third-party, local -- Nessun import wildcard (from x import *) +- Import ordinati: stdlib → third-party → local, nessun wildcard +- DB queries: `selectinload()` per eager loading, `scalar_one_or_none()` per single-row -## Database -- MySQL 8.0 con charset utf8mb4 -- SQLAlchemy 2.0 async con asyncmy driver -- Alembic per migrations -- Tabelle: users, recipes, recipe_versions, recipe_tasks, recipe_subtasks, measurements, access_logs, system_settings, recipe_version_audit +## Dipendenze Chiave +- **Server**: fastapi, uvicorn, sqlalchemy[asyncio], asyncmy, alembic, pydantic, bcrypt, pillow, plotly, kaleido, weasyprint, jinja2 +- **Client**: flask, flask-babel, flask-wtf, requests +- **Test server**: pytest, pytest-asyncio, httpx, aiosqlite (SQLite in-memory per test) +- **Test client**: pytest, coverage -## Ruoli Utente -- **Maker**: crea/modifica ricette -- **MeasurementTec**: esegue misurazioni -- **Metrologist**: visualizza statistiche SPC -- Ruoli combinabili (JSON array), flag `is_admin` separato - -## Pattern Importanti -- **Recipe Versioning**: copy-on-write immutabile. Modifiche creano nuova versione, misure restano legate a versione originale -- **Pass/Fail**: calcolato da tolleranze UTL/UWL/LWL/LTL su ogni subtask -- **File Storage**: uploads/{images,pdfs,logos,reports}/{recipe_id}/{version_id}/ - -## Comandi -- Server: `cd server && uvicorn main:app --reload --host 0.0.0.0 --port 8000` -- Client: `cd client && flask run --host 0.0.0.0 --port 5000` -- Migrations: `cd server && alembic upgrade head` -- TailwindCSS: `cd client && npx tailwindcss -i static/css/input.css -o static/css/tailwind.css --watch` +## Configurazione +Variabili d'ambiente in `.env` (copiare da `.env.example`): +- DB: `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` +- Server: `SERVER_HOST`, `SERVER_PORT`, `SERVER_SECRET_KEY`, `SERVER_CORS_ORIGINS` +- Client: `CLIENT_HOST`, `CLIENT_PORT`, `CLIENT_SECRET_KEY`, `API_SERVER_URL` +- Upload: `UPLOAD_DIR`, `MAX_UPLOAD_SIZE_MB` +- Setup: `SETUP_PASSWORD` (vuota = endpoint disabilitato) +- SSL: `SSL_CERTFILE`, `SSL_KEYFILE` ## Brand - Colore primario: #2563EB (blu industriale)