From 1578398f0ffd4d64ff637e29fa58207dc2ad35d0 Mon Sep 17 00:00:00 2001 From: Adriano Date: Wed, 25 Feb 2026 12:00:47 +0100 Subject: [PATCH] docs: rewrite README with cleaner structure and less duplication Restructure README to be more concise: add feature overview section, architecture diagram with security note, tabular stack listing, streamlined quick start, and env vars reference table. Move VPS deployment details to docs/DEPLOYMENT.md to avoid duplication. Co-Authored-By: Claude Opus 4.6 --- README.md | 494 +++++++++++++++++++++++++----------------------------- 1 file changed, 225 insertions(+), 269 deletions(-) diff --git a/README.md b/README.md index 6ad8560..84968fb 100644 --- a/README.md +++ b/README.md @@ -2,362 +2,285 @@ Sistema di gestione task per misurazioni con calibro manuale. Soluzione tablet-first, multi-ruolo, con statistiche SPC (Statistical Process Control) integrate. +--- + +## Panoramica + +TieMeasureFlow guida l'operatore attraverso sequenze di misurazione definite dal Maker, registra i valori (da calibro USB HID o numpad touch), e valuta automaticamente la conformità rispetto alle tolleranze configurate. I dati raccolti alimentano una dashboard SPC con indici di capability e control chart, esportabili in PDF. + +Caratteristiche principali: + +- Recipe versioning condizionale (copy-on-write se esistono misurazioni, update in-place altrimenti) +- Calcolo pass/fail/warning su quattro limiti di tolleranza (UTL, UWL, LWL, LTL) +- SPC: Cp, Cpk, Pp, Ppk, control chart UCL/LCL, istogramma con curva normale — puro stdlib (no numpy) +- Annotazioni grafiche su disegni tecnici (Fabric.js) con viewer sincronizzato all'esecuzione +- Interfaccia completamente localizzata IT/EN, dark mode, ottimizzata per tablet touch +- Autenticazione API Key, rate limiting sliding window, audit log persistente + +--- + ## Architettura ``` -Browser/Tablet → Reverse Proxy → Flask Client (:5000) → FastAPI Server (:8000) → MySQL 8.0 +Browser/Tablet + | +Reverse Proxy (Nginx — sviluppo | Traefik+SSL — produzione) + | +Flask Client :5000 (rendering server-side, Jinja2 + Alpine.js) + | X-API-Key +FastAPI Server :8000 (API REST asincrona) + | +MySQL 8.0 ``` -Due modalità di deployment: -- **Sviluppo** (`docker-compose.dev.yml`): Nginx reverse proxy, porta 80 -- **Produzione** (`docker-compose.yml`): Traefik reverse proxy con SSL automatico (Let's Encrypt) +Il client Flask non espone mai le credenziali al browser: ogni chiamata al backend avviene server-side con l'header `X-API-Key` estratto dalla sessione Flask. -Il sistema è composto da: -- **Flask Client**: Frontend tablet-oriented con rendering server-side -- **FastAPI Server**: Backend API REST con autenticazione via API key -- **MySQL 8.0**: Database relazionale per persistenza dati +--- ## Stack Tecnologico -### Backend (Server) -- **FastAPI**: Framework asincrono per API REST -- **SQLAlchemy 2.0**: ORM con supporto async/await -- **asyncmy**: Driver MySQL asincrono -- **MySQL 8.0**: Database relazionale -- **Alembic**: Gestione migrazioni database -- **WeasyPrint**: Generazione report PDF da HTML -- **Kaleido**: Export grafici Plotly in formato SVG +### Backend (server/) -### Frontend (Client) -- **Flask 3.0**: Framework web per rendering server-side -- **Jinja2**: Template engine -- **Alpine.js 3.x**: Reattività leggera lato client -- **TailwindCSS 3.x**: Framework CSS utility-first -- **Plotly.js**: Libreria grafici interattivi -- **Fabric.js 5.3.1**: Editor annotazioni su disegni tecnici -- **Flask-Babel**: Sistema i18n per IT/EN +| Componente | Versione | Ruolo | +|---|---|---| +| FastAPI | ultima stabile | Framework API REST asincrono | +| SQLAlchemy 2.0 | async | ORM con pool connessioni | +| asyncmy | ultima stabile | Driver MySQL asincrono | +| MySQL | 8.0 | Database relazionale | +| Alembic | ultima stabile | Migrazioni schema | +| Pydantic v2 | v2 | Validazione I/O | +| WeasyPrint | ultima stabile | Generazione report PDF | +| Kaleido | ultima stabile | Export grafici Plotly in SVG | +| bcrypt | ultima stabile | Hashing password | +| Pillow | ultima stabile | Thumbnail automatici upload | -### Sicurezza e Auth -- **API Key**: Autenticazione via header X-API-Key -- **Rate Limiting**: Protezione endpoint sensibili -- **CORS**: Configurazione per deployment multi-dominio +### Frontend (client/) + +| Componente | Versione | Ruolo | +|---|---|---| +| Flask | 3.x | Framework web server-side | +| Jinja2 | incluso in Flask | Template engine | +| Alpine.js | 3.x (CDN) | Reattivita leggera lato client | +| TailwindCSS | 3.x | CSS utility-first | +| Plotly.js | CDN | Grafici SPC interattivi | +| Fabric.js | 5.3.1 (CDN) | Editor annotazioni disegni tecnici | +| Flask-Babel | ultima stabile | i18n IT/EN | + +--- ## Quick Start con Docker -Il metodo raccomandato per installare e avviare TieMeasureFlow è tramite Docker Compose: +Docker Compose è il metodo raccomandato. Gestisce database, migrazioni e configurazione Nginx in un solo comando. ```bash -# 1. Clone del repository +# 1. Clona il repository git clone cd TieMeasureFlow -# 2. Configurazione ambiente +# 2. Configura le variabili d'ambiente cp .env.example .env -# Modifica .env con le tue credenziali (DB, password admin, ecc.) +# Modifica .env: credenziali DB, chiavi segrete, SETUP_PASSWORD -# 3. Avvio dei servizi -docker compose -f docker-compose.dev.yml up -d # Sviluppo (Nginx, porta 80) -# oppure -docker compose up -d # Produzione (Traefik, SSL) +# 3. Avvia i servizi (ambiente di sviluppo) +docker compose -f docker-compose.dev.yml up -d -# 4. Setup iniziale +# 4. Verifica lo stato dei container +docker compose -f docker-compose.dev.yml ps + +# 5. Setup iniziale (solo al primo avvio) # Apri http://localhost/api/setup nel browser -# Usa SETUP_PASSWORD configurata in .env per: -# - Inizializzare il database -# - Creare l'utente admin -# - (Opzionale) Caricare dati demo - -# 5. Accesso all'applicazione -# Apri http://localhost nel browser -# Login con credenziali admin create nel setup +# Usa SETUP_PASSWORD configurata in .env ``` L'applicazione sarà disponibile su: + - Frontend: http://localhost -- API Backend: http://localhost/api -- Setup Page: http://localhost/api/setup +- API: http://localhost/api +- Pagina setup: http://localhost/api/setup + +Per il deployment in produzione (Traefik + SSL) consulta [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md). + +--- + +## Setup Iniziale + +Dopo il primo avvio, la pagina `/api/setup` (protetta da `SETUP_PASSWORD`) permette di: + +- **Initialize Database** — crea tutte le tabelle +- **Create Admin User** — crea l'utente amministratore con credenziali da `.env` +- **Seed Demo Data** — carica ricette, misurazioni e utenti di esempio +- **Reset Database** — elimina e ricrea tutte le tabelle (attenzione: cancella tutti i dati) +- **Gestione utenti** — crea, modifica, attiva/disattiva account dalla stessa pagina + +Se `SETUP_PASSWORD` è vuota o assente nel `.env`, l'endpoint è disabilitato. + +--- ## Setup Manuale (Senza Docker) -Per chi preferisce installare senza Docker: - ### Requisiti + - Python 3.11 o superiore - Node.js 18 o superiore - MySQL 8.0 -### Installazione +### 1. Database MySQL -#### 1. Database MySQL ```bash -# Crea database -mysql -u root -p +mysql -u root -p <<'SQL' CREATE DATABASE tiemeasureflow CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'tielogic'@'localhost' IDENTIFIED BY 'your_password'; GRANT ALL PRIVILEGES ON tiemeasureflow.* TO 'tielogic'@'localhost'; FLUSH PRIVILEGES; +SQL ``` -#### 2. Configurazione +### 2. Configurazione + ```bash -# Copia template configurazione cp .env.example .env - -# Modifica .env con: -# - Credenziali database MySQL -# - Chiavi segrete -# - Password admin +# Imposta DB_HOST, DB_USER, DB_PASSWORD, DB_NAME, SERVER_SECRET_KEY, CLIENT_SECRET_KEY, SETUP_PASSWORD ``` -#### 3. Server (FastAPI Backend) +### 3. Server FastAPI + ```bash cd server - -# Crea virtual environment python -m venv venv -source venv/bin/activate # Su Windows: venv\Scripts\activate - -# Installa dipendenze +source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt - -# Esegui migrazioni database -alembic upgrade head - -# Avvia server +alembic -c migrations/alembic.ini upgrade head uvicorn main:app --reload --host 0.0.0.0 --port 8000 ``` -#### 4. Client (Flask Frontend) +### 4. Client Flask + ```bash cd client - -# Crea virtual environment python -m venv venv -source venv/bin/activate # Su Windows: venv\Scripts\activate - -# Installa dipendenze +source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt - -# Build TailwindCSS -npx tailwindcss -i static/css/input.css -o static/css/tailwind.css --watch - -# In un altro terminale: Compila traduzioni -cd client pybabel compile -d translations - -# Avvia client flask run --host 0.0.0.0 --port 5000 ``` -Accesso: +### 5. TailwindCSS (watch per sviluppo) + +```bash +cd client +npx tailwindcss -i static/css/input.css -o static/css/tailwind.css --watch +``` + +Accesso diretto (senza Nginx): + - Frontend: http://localhost:5000 -- Backend API: http://localhost:8000 +- API: http://localhost:8000 -## Pagina di Setup +--- -TieMeasureFlow include una pagina di setup protetta accessibile su `/api/setup`: +## Ruoli Utente -- **Protezione**: Richiede SETUP_PASSWORD configurata in .env -- **Disabilitazione**: Se SETUP_PASSWORD è vuota/assente, endpoint disabilitato -- **Accesso**: - - Via nginx (produzione): http://localhost/api/setup - - Diretto (sviluppo): http://localhost:8000/api/setup +I ruoli sono combinabili (array JSON per utente). Il flag `is_admin` è separato dai ruoli funzionali. -### Funzionalità Setup -- **Initialize Database**: Crea tutte le tabelle necessarie -- **Create Admin User**: Crea utente amministratore con credenziali da .env -- **Seed Demo Data**: Carica dati di esempio (ricette, misurazioni, utenti) -- **Reset Database**: Elimina e ricrea tutte le tabelle (attenzione: cancella tutti i dati!) +| Ruolo | Descrizione | +|---|---| +| **Maker** | Crea e gestisce ricette di misurazione: caricamento disegni (PDF/immagini), annotazioni Fabric.js, definizione task/subtask, configurazione tolleranze, versioning copy-on-write | +| **MeasurementTec** | Esegue misurazioni: scansione barcode per selezione ricetta, interfaccia task-driven, input da calibro USB HID o numpad touch, validazione real-time pass/warning/fail | +| **Metrologist** | Analisi qualità: dashboard SPC (X-bar, R, Cp, Cpk, Pp, Ppk), filtri multi-dimensionali, export report PDF, analisi capability e control chart | +| **Admin** (flag) | Gestione sistema: CRUD utenti, cambio password, attivazione/disattivazione account | + +--- ## Struttura Progetto ``` TieMeasureFlow/ -├── server/ # FastAPI Backend (API REST) -│ ├── main.py # Entry point applicazione -│ ├── config.py # Configurazione da variabili .env -│ ├── database.py # SQLAlchemy async engine e sessioni -│ ├── models/ # ORM models (User, Recipe, Measurement, ecc.) -│ ├── schemas/ # Pydantic schemas per validazione I/O -│ ├── routers/ # API endpoints organizzati per dominio -│ ├── services/ # Business logic (SPC, PDF, auth, ecc.) -│ ├── middleware/ # Auth, logging, rate limiting -│ ├── migrations/ # Alembic migration scripts -│ └── templates/ # Template HTML per setup page -├── client/ # Flask Frontend (UI tablet) -│ ├── app.py # Entry point applicazione -│ ├── blueprints/ # Route blueprints (auth, maker, measure, statistics, admin) -│ ├── services/ # API client wrapper per chiamate a FastAPI -│ ├── templates/ # Jinja2 templates per rendering pagine -│ ├── static/ # Asset statici (CSS, JS, immagini) -│ │ ├── css/ # TailwindCSS compiled output -│ │ ├── js/ # Alpine.js components e utility -│ │ └── images/ # Loghi, icone, placeholder -│ └── translations/ # File i18n per IT/EN (Flask-Babel) -├── nginx/ # Configurazione reverse proxy (dev) -│ └── nginx.conf # Routing unificato client/server -├── docker-compose.yml # Produzione (Traefik, SSL) -├── docker-compose.dev.yml # Sviluppo (Nginx, porta 80) -├── .env.example # Template variabili d'ambiente -└── docs/ # Documentazione tecnica +├── server/ # FastAPI Backend +│ ├── main.py # Entry point, lifespan, middleware, 10 router +│ ├── config.py # Settings (pydantic_settings.BaseSettings) +│ ├── database.py # SQLAlchemy 2.0 async engine +│ ├── models/ # ORM: User, Recipe, RecipeVersion, RecipeTask, +│ │ # RecipeSubtask, Measurement, AccessLog, +│ │ # SystemSetting, RecipeVersionAudit +│ ├── schemas/ # Pydantic v2 per validazione I/O API +│ ├── routers/ # auth, users, recipes, tasks, measurements, +│ │ # files, settings, statistics, reports, setup +│ ├── services/ # recipe_service, measurement_service, +│ │ # spc_service, report_service, auth_service +│ ├── middleware/ # api_key, rate_limit, security_headers, logging +│ ├── migrations/ # Alembic (alembic.ini + env.py) +│ └── templates/ # Template HTML pagina setup +├── client/ # Flask Frontend +│ ├── app.py # Factory pattern, CSRF, Babel +│ ├── blueprints/ # auth, maker, measure, statistics, admin +│ ├── services/ # APIClient singleton (proxy verso FastAPI) +│ ├── templates/ # Jinja2 + Alpine.js +│ ├── static/ +│ │ ├── css/ # TailwindCSS compilato +│ │ └── js/ # numpad, caliper, barcode, csv-export, +│ │ # spc-charts, annotation-editor/viewer +│ └── translations/ # Flask-Babel .po/.mo IT/EN +├── nginx/ # Configurazione Nginx (dev) +├── docs/ # Documentazione tecnica +│ ├── API.md # Riferimento API REST +│ ├── DEPLOYMENT.md # Guida deployment VPS (Traefik, SSL, DNS) +│ └── USER_GUIDE.md # Manuale utente per ruolo +├── docker-compose.yml # Produzione (Traefik, SSL) +├── docker-compose.dev.yml # Sviluppo (Nginx, porta 80) +└── .env.example # Template variabili d'ambiente ``` -## Ruoli Utente - -TieMeasureFlow supporta tre ruoli principali, combinabili: - -### Maker -Responsabile della creazione e modifica delle ricette di misurazione: -- Caricamento disegni tecnici (PDF) -- Annotazioni grafiche con Fabric.js (linee, frecce, testi, ellissi) -- Definizione task e subtask di misurazione -- Configurazione tolleranze (UTL, UWL, LWL, LTL) -- Gestione versioni immutabili (copy-on-write) - -### MeasurementTec -Operatore che esegue le misurazioni: -- Accesso rapido via barcode scanner -- Interfaccia task-driven per guida passo-passo -- Input valori da calibro USB HID (rilevamento automatico burst) -- Validazione real-time pass/fail su tolleranze -- Salvataggio annotazioni fotografiche - -### Metrologist -Analista qualità con accesso alle statistiche: -- Dashboard SPC con grafici Plotly.js (X-bar, R, Cp, Cpk) -- Filtri multi-dimensionali (ricetta, utente, periodo, stato) -- Export report PDF con WeasyPrint -- Analisi tendenze e capability del processo - -I ruoli sono configurabili in fase di creazione utente e possono essere combinati. Flag `is_admin` separato per gestione sistema (CRUD utenti, cambio password, attivazione/disattivazione account). - -## Guida VPS Deployment - -### Requisiti VPS -- 2GB RAM minimo (4GB raccomandati) -- 20GB spazio disco -- Ubuntu 22.04 LTS o superiore -- Accesso SSH con privilegi sudo - -### Installazione Docker - -```bash -# Installa Docker -curl -fsSL https://get.docker.com | sh - -# Aggiungi utente al gruppo docker -sudo usermod -aG docker $USER - -# Installa Docker Compose (se non incluso) -sudo apt update -sudo apt install docker-compose-plugin - -# Ricarica gruppi (oppure logout/login) -newgrp docker -``` - -### Deploy Applicazione - -Il compose di produzione (`docker-compose.yml`) usa Traefik come reverse proxy con SSL automatico. Richiede un'istanza Traefik già configurata con rete Docker `root_default`. - -```bash -# Clone repository -git clone -cd TieMeasureFlow - -# Configura ambiente (IMPORTANTE: usa password sicure!) -cp .env.example .env -nano .env - -# Modifica almeno: -# - DB_ROOT_PASSWORD -# - DB_PASSWORD -# - SERVER_SECRET_KEY -# - CLIENT_SECRET_KEY -# - SETUP_PASSWORD - -# Avvia servizi (produzione con Traefik) -docker compose up -d - -# Verifica stato -docker compose ps -docker compose logs -f -``` - -### Configurazione Firewall - -```bash -# Abilita UFW -sudo ufw allow OpenSSH -sudo ufw allow 80/tcp -sudo ufw allow 443/tcp -sudo ufw enable - -# Verifica regole -sudo ufw status -``` - -### Configurazione DNS - -1. Accedi al pannello del tuo provider DNS -2. Crea un record A che punta il tuo dominio all'IP pubblico del VPS: - ``` - Type: A - Name: @ (o www) - Value: - TTL: 3600 - ``` -3. Attendi propagazione DNS (5-30 minuti) - -### SSL (HTTPS) - -Il compose di produzione usa Traefik con Let's Encrypt per certificati SSL automatici. Configurare il dominio nelle labels Traefik di `docker-compose.yml`. - -Per ambienti senza Traefik (compose dev con Nginx), configurare SSL manualmente: -- Impostare `SSL_CERTFILE` e `SSL_KEYFILE` in `.env` -- Decommentare le righe SSL in `nginx/nginx.conf` +--- ## Comandi Utili -> **Nota:** Per sviluppo locale aggiungere `-f docker-compose.dev.yml` ai comandi docker compose. +### Docker | Comando | Descrizione | -|---------|-------------| -| `docker compose up -d` | Avvia tutti i servizi in background | -| `docker compose down` | Ferma e rimuove tutti i container | -| `docker compose logs -f server` | Segui log del server in tempo reale | -| `docker compose logs -f client` | Segui log del client in tempo reale | -| `docker compose ps` | Mostra stato di tutti i servizi | -| `docker compose exec server alembic -c migrations/alembic.ini upgrade head` | Esegui migrazioni database | -| `docker compose exec server alembic -c migrations/alembic.ini revision --autogenerate -m "desc"` | Genera nuova migrazione | -| `docker compose build --no-cache` | Ricostruisci tutte le immagini senza cache | -| `docker compose exec mysql mysql -u root -p tiemeasureflow` | Accedi alla CLI MySQL | +|---|---| +| `docker compose -f docker-compose.dev.yml up -d` | Avvia servizi in sviluppo | +| `docker compose -f docker-compose.dev.yml down` | Ferma e rimuove i container | +| `docker compose logs -f server` | Segui log server in tempo reale | +| `docker compose logs -f client` | Segui log client in tempo reale | +| `docker compose ps` | Stato di tutti i servizi | +| `docker compose build --no-cache` | Ricostruisci immagini senza cache | +| `docker compose exec mysql mysql -u root -p tiemeasureflow` | CLI MySQL | -## Sviluppo +### Alembic (migrations) -### Hot Reload -- Server FastAPI: Uvicorn con `--reload` flag (automatico in docker-compose) -- Client Flask: Flask debug mode (automatico in docker-compose) -- TailwindCSS: `--watch` flag per rebuild automatico +Nota: `alembic.ini` si trova dentro `server/migrations/`, è richiesto il flag `-c`. -### Migrazioni Database ```bash cd server - -# Genera nuova migrazione -alembic -c migrations/alembic.ini revision --autogenerate -m "Descrizione modifica" - -# Applica migrazioni -alembic -c migrations/alembic.ini upgrade head - -# Rollback ultima migrazione -alembic -c migrations/alembic.ini downgrade -1 +alembic -c migrations/alembic.ini upgrade head # Applica migrazioni +alembic -c migrations/alembic.ini revision --autogenerate -m "descrizione" # Genera migrazione +alembic -c migrations/alembic.ini downgrade -1 # Rollback ultima ``` -### Testing +Via Docker: + ```bash -# Server (SQLite in-memory, no MySQL richiesto) -cd server && pytest # Tutti i test +docker compose exec server alembic -c migrations/alembic.ini upgrade head +``` + +### i18n (Traduzioni) + +```bash +cd client +pybabel extract -F babel.cfg -k _ -o translations/messages.pot . # Estrai stringhe +pybabel update -i translations/messages.pot -d translations # Aggiorna catalogo +pybabel compile -d translations # Compila .po → .mo +``` + +--- + +## Testing + +Il server usa SQLite in-memory tramite `aiosqlite`: i test girano senza MySQL installato. + +```bash +# Server +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 @@ -366,6 +289,39 @@ cd server && pytest --cov # Con copertura cd client && pytest ``` +--- + +## Variabili d'Ambiente + +Copia `.env.example` in `.env` e configura: + +| Variabile | Descrizione | +|---|---| +| `DB_HOST`, `DB_PORT`, `DB_NAME` | Connessione MySQL | +| `DB_USER`, `DB_PASSWORD` | Credenziali utente MySQL | +| `DB_ROOT_PASSWORD` | Password root MySQL (solo Docker) | +| `SERVER_SECRET_KEY` | Chiave segreta FastAPI | +| `SERVER_CORS_ORIGINS` | Origini CORS ammesse | +| `CLIENT_SECRET_KEY` | Chiave segreta Flask (sessioni, CSRF) | +| `API_SERVER_URL` | URL del backend visto dal client (es. `http://server:8000`) | +| `UPLOAD_DIR` | Percorso upload file (default: `uploads`, relativo a `server/`) | +| `MAX_UPLOAD_SIZE_MB` | Limite dimensione upload | +| `NGINX_PORT`, `NGINX_SSL_PORT` | Porte Nginx (solo compose dev) | +| `SETUP_PASSWORD` | Password pagina setup (vuota = endpoint disabilitato) | +| `SSL_CERTFILE`, `SSL_KEYFILE` | Certificato SSL (solo setup manuale) | + +--- + +## Documentazione + +| Documento | Contenuto | +|---|---| +| [docs/API.md](docs/API.md) | Riferimento completo API REST (endpoint, parametri, schemi) | +| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Guida deployment VPS: Docker, Traefik, SSL, DNS, firewall | +| [docs/USER_GUIDE.md](docs/USER_GUIDE.md) | Manuale utente per ruolo (Maker, MeasurementTec, Metrologist) | + +--- + ## Licenza Proprietary - Tielogic. All rights reserved.