# TieMeasureFlow - Istruzioni Progetto

## Panoramica
TieMeasureFlow by Tielogic - Sistema di gestione task per misurazioni con calibro manuale.
Monorepo con server FastAPI (backend API) e client Flask (frontend tablet).

## 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

## Struttura
```
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
```

## 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 *)

## 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

## 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`

## Brand
- Colore primario: #2563EB (blu industriale)
- Colore secondario: #64748B (grigio acciaio)
- Font UI: Inter
- Font numeri: JetBrains Mono