docs: update README with Traefik deployment, correct blueprints, fix commands

- Architecture: document dual compose (dev Nginx / prod Traefik) - Stack: remove htmx (unused), pin Fabric.js to 5.3.1 - Fix blueprint names (measure, statistics, admin instead of measurement, metrologist) - Fix alembic commands with -c migrations/alembic.ini flag - Fix .env variable names to match actual config - Update testing section with real examples (not "da implementare") - Replace Certbot/Nginx SSL section with Traefik auto-SSL - Document is_admin capabilities (user CRUD) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-20 11:57:04 +01:00
parent 6c8c60900b
commit 08bcb87d6b
1 changed files with 47 additions and 66 deletions
@@ -5,24 +5,17 @@ Sistema di gestione task per misurazioni con calibro manuale. Soluzione tablet-f
 ## Architettura

 ```
-┌─────────────┐     ┌──────────────┐     ┌──────────┐
-│  Browser /  │────▶│    Nginx     │────▶│  MySQL   │
-│   Tablet    │     │  (Reverse    │     │   8.0    │
-└─────────────┘     │   Proxy)     │     └────▲─────┘
-                    └──┬───────┬───┘          │
-                       │       │              │
-                 ┌─────▼──┐ ┌──▼──────┐       │
-                 │ Flask   │ │ FastAPI │───────┘
-                 │ Client  │ │ Server  │
-                 │ :5000   │ │ :8000   │
-                 └─────────┘ └─────────┘
+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 interfaccia responsive
+- **Flask Client**: Frontend tablet-oriented con rendering server-side
 - **FastAPI Server**: Backend API REST con autenticazione via API key
- **Nginx**: Reverse proxy per routing unificato
- **MySQL**: Database relazionale per persistenza dati
+- **MySQL 8.0**: Database relazionale per persistenza dati

 ## Stack Tecnologico

@@ -38,11 +31,10 @@ Il sistema è composto da:
 ### 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
+- **Fabric.js 5.3.1**: Editor annotazioni su disegni tecnici
 - **Flask-Babel**: Sistema i18n per IT/EN

 ### Sicurezza e Auth
@@ -64,7 +56,9 @@ cp .env.example .env
 # Modifica .env con le tue credenziali (DB, password admin, ecc.)

 # 3. Avvio dei servizi
-docker compose up -d
+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
@@ -192,7 +186,7 @@ TieMeasureFlow/
 │   └── templates/       # Template HTML per setup page
 ├── client/              # Flask Frontend (UI tablet)
 │   ├── app.py           # Entry point applicazione
-│   ├── blueprints/      # Route blueprints (auth, maker, measurement, metrologist)
+│   ├── 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)
@@ -200,9 +194,10 @@ TieMeasureFlow/
 │   │   ├── js/          # Alpine.js components e utility
 │   │   └── images/      # Loghi, icone, placeholder
 │   └── translations/    # File i18n per IT/EN (Flask-Babel)
-├── nginx/               # Configurazione reverse proxy
+├── nginx/                   # Configurazione reverse proxy (dev)
 │   └── nginx.conf           # Routing unificato client/server
-├── docker-compose.yml   # Orchestrazione servizi Docker
+├── docker-compose.yml       # Produzione (Traefik, SSL)
+├── docker-compose.dev.yml   # Sviluppo (Nginx, porta 80)
 ├── .env.example             # Template variabili d'ambiente
 └── docs/                    # Documentazione tecnica
 ```
@@ -234,7 +229,7 @@ Analista qualità con accesso alle statistiche:
 - 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.
+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

@@ -263,6 +258,8 @@ 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>
@@ -273,13 +270,13 @@ cp .env.example .env
 nano .env

 # Modifica almeno:
-# - MYSQL_ROOT_PASSWORD
-# - MYSQL_PASSWORD
-# - SECRET_KEY
-# - API_KEY_ADMIN
+# - DB_ROOT_PASSWORD
+# - DB_PASSWORD
+# - SERVER_SECRET_KEY
+# - CLIENT_SECRET_KEY
 # - SETUP_PASSWORD

-# Avvia servizi
+# Avvia servizi (produzione con Traefik)
 docker compose up -d

 # Verifica stato
@@ -312,34 +309,18 @@ sudo ufw status
   ```
 3. Attendi propagazione DNS (5-30 minuti)

-### SSL con Certbot (HTTPS)
+### SSL (HTTPS)

-```bash
-# Installa Certbot
-sudo apt update
-sudo apt install certbot
+Il compose di produzione usa Traefik con Let's Encrypt per certificati SSL automatici. Configurare il dominio nelle labels Traefik di `docker-compose.yml`.

-# 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
+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 |
@@ -347,12 +328,10 @@ Accesso produzione: https://yourdomain.com
 | `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 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 |
-| `docker compose exec server python -c "from config import settings; print(settings.database_url)"` | Verifica configurazione server |

 ## Sviluppo

@@ -363,26 +342,28 @@ Accesso produzione: https://yourdomain.com

 ### Migrazioni Database
 ```bash
-# Genera nuova migrazione
 cd server
-alembic revision --autogenerate -m "Descrizione modifica"
+
+# Genera nuova migrazione
+alembic -c migrations/alembic.ini revision --autogenerate -m "Descrizione modifica"

 # Applica migrazioni
-alembic upgrade head
+alembic -c migrations/alembic.ini upgrade head

 # Rollback ultima migrazione
-alembic downgrade -1
+alembic -c migrations/alembic.ini downgrade -1
 ```

 ### Testing
 ```bash
-# Test server (da implementare)
-cd server
-pytest
+# 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

-# Test client (da implementare)
-cd client
-pytest
+# Client
+cd client && pytest
 ```

 ## Licenza