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

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

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

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

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