TieMeasureFlow/README.md

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

```bash
# 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
```bash
# 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
```bash
# Copia template configurazione
cp .env.example .env

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

#### 3. Server (FastAPI Backend)
```bash
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)
```bash
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

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

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

```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: <VPS_IP>
   TTL: 3600
   ```
3. Attendi propagazione DNS (5-30 minuti)

### SSL con Certbot (HTTPS)

```bash
# 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
```bash
# Genera nuova migrazione
cd server
alembic revision --autogenerate -m "Descrizione modifica"

# Applica migrazioni
alembic upgrade head

# Rollback ultima migrazione
alembic downgrade -1
```

### Testing
```bash
# 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.