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 /  │────▶│    Nginx     │────▶│  MySQL   │
│   Tablet    │     │  (Reverse    │     │   8.0    │
└─────────────┘     │   Proxy)     │     └────▲─────┘
                    └──┬───────┬───┘          │
                       │       │              │
                 ┌─────▼──┐ ┌──▼──────┐       │
                 │ Flask   │ │ FastAPI │───────┘
                 │ Client  │ │ Server  │
                 │ :5000   │ │ :8000   │
                 └─────────┘ └─────────┘

Il sistema è composto da:

• Flask Client: Frontend tablet-oriented con interfaccia responsive
• FastAPI Server: Backend API REST con autenticazione via API key
• Nginx: Reverse proxy per routing unificato
• MySQL: 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
• htmx 2.0: Interazioni AJAX dichiarative
• Alpine.js 3.x: Reattività leggera lato client
• TailwindCSS 3.x: Framework CSS utility-first
• Plotly.js: Libreria grafici interattivi
• Fabric.js 5.x: 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 up -d

# 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, measurement, metrologist)
│   ├── 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
│   └── nginx.conf       # Routing unificato client/server
├── docker-compose.yml   # Orchestrazione servizi Docker
├── .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.

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

# Clone repository
git clone <repository-url>
cd TieMeasureFlow

# Configura ambiente (IMPORTANTE: usa password sicure!)
cp .env.example .env
nano .env

# Modifica almeno:
# - MYSQL_ROOT_PASSWORD
# - MYSQL_PASSWORD
# - SECRET_KEY
# - API_KEY_ADMIN
# - SETUP_PASSWORD

# Avvia servizi
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 con Certbot (HTTPS)

# Installa Certbot
sudo apt update
sudo apt install certbot

# Genera certificati (usa il tuo dominio)
sudo certbot certonly --webroot -w /var/www/certbot -d yourdomain.com -d www.yourdomain.com

# Decommentare linee SSL in nginx/nginx.conf
nano nginx/nginx.conf
# Rimuovi commenti (#) dalle righe:
#   listen 443 ssl http2;
#   ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
#   ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

# Riavvia nginx
docker compose restart nginx

# Verifica rinnovo automatico
sudo certbot renew --dry-run

Accesso produzione: https://yourdomain.com

Comandi Utili

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 upgrade head	Esegui migrazioni database
docker compose exec server alembic revision --autogenerate -m "description"	Genera nuova migrazione
docker compose restart nginx	Riavvia solo nginx
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 exec server python -c "from config import settings; print(settings.database_url)"	Verifica configurazione server

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

# Genera nuova migrazione
cd server
alembic revision --autogenerate -m "Descrizione modifica"

# Applica migrazioni
alembic upgrade head

# Rollback ultima migrazione
alembic downgrade -1

Testing

# Test server (da implementare)
cd server
pytest

# Test client (da implementare)
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.