TieMeasureFlow by Tielogic

Sistema di gestione task per misurazioni con calibro manuale. Soluzione tablet-first, multi-ruolo, con statistiche SPC (Statistical Process Control) integrate.

Architettura

Browser/Tablet → Reverse Proxy → Flask Client (:5000) → FastAPI Server (:8000) → 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 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

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

Sicurezza e Auth

• API Key: Autenticazione via header X-API-Key
• Rate Limiting: Protezione endpoint sensibili
• CORS: Configurazione per deployment multi-dominio

Quick Start con Docker

Il metodo raccomandato per installare e avviare TieMeasureFlow è tramite Docker Compose:

# 1. Clone del repository
git clone <repository-url>
cd TieMeasureFlow

# 2. Configurazione ambiente
cp .env.example .env
# Modifica .env con le tue credenziali (DB, password admin, ecc.)

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

# 4. Setup iniziale
# 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

L'applicazione sarà disponibile su:

• Frontend: http://localhost
• API Backend: http://localhost/api
• Setup Page: http://localhost/api/setup

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

# Crea database
mysql -u root -p
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;

2. Configurazione

# Copia template configurazione
cp .env.example .env

# Modifica .env con:
# - Credenziali database MySQL
# - Chiavi segrete
# - Password admin

3. Server (FastAPI Backend)

cd server

# Crea virtual environment
python -m venv venv
source venv/bin/activate  # Su Windows: venv\Scripts\activate

# Installa dipendenze
pip install -r requirements.txt

# Esegui migrazioni database
alembic upgrade head

# Avvia server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

4. Client (Flask Frontend)

cd client

# Crea virtual environment
python -m venv venv
source venv/bin/activate  # Su Windows: venv\Scripts\activate

# Installa dipendenze
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:

• Frontend: http://localhost:5000
• Backend API: http://localhost:8000

Pagina di Setup

TieMeasureFlow include una pagina di setup protetta accessibile su /api/setup:

• 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

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!)

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

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

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

# Clone repository
git clone <repository-url>
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

# 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: <VPS_IP>
   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.

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

Sviluppo

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

Migrazioni Database

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

Testing

# Server (SQLite in-memory, 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

Licenza

Proprietary - Tielogic. All rights reserved.

Questo software è di proprietà esclusiva di Tielogic ed è protetto dalle leggi sul copyright. Non è consentita la distribuzione, modifica o utilizzo senza autorizzazione scritta.