# TieMeasureFlow by Tielogic

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

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.

---

## Stack Tecnologico

### Backend (server/)

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

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

Docker Compose è il metodo raccomandato. Gestisce database, migrazioni e configurazione Nginx in un solo comando.

```bash
# 1. Clona il repository
git clone <repository-url>
cd TieMeasureFlow

# 2. Configura le variabili d'ambiente
cp .env.example .env
# Modifica .env: credenziali DB, chiavi segrete, SETUP_PASSWORD

# 3. Avvia i servizi (ambiente di sviluppo)
docker compose -f docker-compose.dev.yml up -d

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

L'applicazione sarà disponibile su:

- Frontend: http://localhost
- 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)

### Requisiti

- Python 3.11 o superiore
- Node.js 18 o superiore
- MySQL 8.0

### 1. Database MySQL

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

```bash
cp .env.example .env
# Imposta DB_HOST, DB_USER, DB_PASSWORD, DB_NAME, SERVER_SECRET_KEY, CLIENT_SECRET_KEY, SETUP_PASSWORD
```

### 3. Server FastAPI

```bash
cd server
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
alembic -c migrations/alembic.ini upgrade head
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

### 4. Client Flask

```bash
cd client
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
pybabel compile -d translations
flask run --host 0.0.0.0 --port 5000
```

### 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
- API: http://localhost:8000

---

## Ruoli Utente

I ruoli sono combinabili (array JSON per utente). Il flag `is_admin` è separato dai ruoli funzionali.

| 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
│   ├── 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
```

---

## Comandi Utili

### Docker

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

### Alembic (migrations)

Nota: `alembic.ini` si trova dentro `server/migrations/`, è richiesto il flag `-c`.

```bash
cd server
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
```

Via Docker:

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

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

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