docs: aggiorna README e documentazione con feature attuali

2026-04-25 18:10:49 +02:00
parent bfed2f60aa
commit 831b41f487
3 changed files with 116 additions and 39 deletions
@@ -4,13 +4,16 @@ Una dashboard web moderna e intuitiva per monitorare e gestire i modelli LLM car

 ## 🎯 Caratteristiche

- ✨ **Dashboard intuitiva** - Visualizza in tempo reale i modelli caricati in Ollama
+- ✨ **Dashboard intuitiva** - Visualizza in tempo reale i modelli disponibili e in esecuzione su Ollama
 - 📊 **Monitoraggio modelli** - Dettagli completi di ogni modello (nome, dimensione, memoria, stato)
- 🧩 **Dettagli avanzati on click** - Clic su una card modello per visualizzare i dati Ollama `show`
+- 🧩 **Dettagli accordion on click** - Clic su una card per esplorare i dati `ollama show` in pannelli collassabili (dettagli, parametri, template, modelfile, licenza)
+- 🖥️ **Multi-server** - Gestione di più istanze Ollama con switch istantaneo (pagina `/servers`)
+- 🏃 **Modelli in esecuzione** - Pagina dedicata `/models-running` con VRAM, tempo rimanente e backend GPU/CPU
+- 📱 **PWA** - Installabile come app desktop/mobile con Service Worker e cache offline
 - 🔌 **API REST documentata** - Documentazione interattiva con Swagger/OpenAPI
- 🎨 **UI moderna** - Interfaccia elegante realizzata con TailwindCSS
- 🐳 **Docker ready** - Container sempre acceso (until stopped)
- ⚡ **Performance** - Costruito su FastAPI e uVicorn
+- 🎨 **UI moderna** - Interfaccia dark-mode realizzata con TailwindCSS
+- 🐳 **Docker ready** - Container sempre acceso (restart: unless-stopped)
+- ⚡ **Performance** - FastAPI + uVicorn, aggiornamenti ogni 30s via Web Worker senza bloccare l'UI
 - 🔐 **Configurazione flessibile** - File `.env` per personalizzazione

 ## 📋 Requisiti
@@ -309,38 +312,59 @@ docker start llm-monitor
 llm-monitor/
 ├── main.py                 # Entry point dell'applicazione
 ├── requirements.txt        # Dipendenze Python
-├── env.example            # Esempio di configurazione
-├── Dockerfile             # Configurazione Docker
-├── docker-compose.yml     # Composizione servizi
-├── README.md              # Questo file
-├── .gitignore
+├── requirements-dev.txt    # Dipendenze sviluppo (pytest, black, flake8…)
+├── env.example             # Esempio di configurazione
+├── Dockerfile              # Build multi-stage (Node CSS + Python runtime)
+├── docker-compose.yml      # Composizione servizi
+├── package.json            # Script Node (Tailwind, Playwright)
+├── tailwind.config.js      # Configurazione TailwindCSS
+├── playwright.config.js    # Configurazione test E2E
+├── Makefile                # Comandi rapidi (dev, test, deploy…)
+├── README.md               # Questo file
+├── CONTRIBUTING.md         # Guida ai contributi
 │
 ├── app/
-│   ├── __init__.py
-│   ├── config.py          # Configurazione (variabili ambiente)
-│   ├── main.py            # Inizializzazione FastAPI
+│   ├── config.py           # Configurazione via variabili d'ambiente
 │   │
 │   ├── api/
-│   │   ├── __init__.py
-│   │   ├── models.py      # Endpoint modelli
-│   │   ├── health.py      # Endpoint health
-│   │   └── v1/
-│   │       └── __init__.py
+│   │   ├── models.py       # Endpoint modelli (/api/v1/models)
+│   │   └── health.py       # Endpoint health (/api/v1/health)
 │   │
 │   ├── services/
-│   │   ├── __init__.py
-│   │   ├── ollama.py      # Client Ollama
-│   │   └── cache.py       # Cache in-memory (opzionale)
+│   │   └── ollama.py       # Client HTTP verso Ollama
 │   │
 │   └── web/
-│       ├── __init__.py
-│       ├── static/        # Assets statici (CSS compilato TailwindCSS)
-│       └── templates/     # Template HTML
+│       ├── static/
+│       │   ├── css/
+│       │   │   ├── input.css    # Sorgente Tailwind
+│       │   │   └── output.css   # CSS compilato (generato)
+│       │   └── js/
+│       │       ├── app.js              # App principale (dashboard modelli)
+│       │       ├── servers.js          # Pagina gestione server
+│       │       ├── models-running.js   # Pagina modelli in esecuzione
+│       │       ├── data-sync.worker.js # Web Worker sincronizzazione dati
+│       │       ├── server-config.js    # Utilità multi-server e localStorage
+│       │       ├── pwa-register.js     # Registrazione Service Worker
+│       │       └── service-worker.js   # PWA Service Worker (cache-first)
+│       └── templates/
+│           ├── index.html             # Dashboard modelli disponibili
+│           ├── servers.html           # Gestione istanze Ollama
+│           └── models_running.html    # Modelli attualmente in esecuzione
+│
+├── docs/
+│   ├── PRD.md              # Product Requirements Document
+│   ├── DEVELOPMENT.md      # Guida al setup e sviluppo locale
+│   └── WEB_WORKERS.md      # Architettura Web Worker e PWA
+│
+├── scripts/
+│   ├── deploy-no-cache.sh       # Deploy Docker con rebuild forzato
+│   └── verify-tailwind-css.sh   # Verifica CSS compilato in container
 │
 └── tests/
-    ├── __init__.py
-    ├── test_api.py
-    └── test_ollama.py
+    ├── test_api.py         # Unit test endpoint FastAPI
+    ├── test_ollama.py      # Unit test client Ollama
+    └── e2e/
+        └── cache-navigation.spec.js  # Test E2E Playwright (cache/PWA)
 ```

 ## 🛠️ Sviluppo
@@ -453,6 +477,6 @@ Per domande o segnalazioni di bug, apri un **Issue** nel repository.

 **Fatto con ❤️ da [LucaSacchi.Net](https://lucasacchi.net)**

-**Versione**: 1.0.0  
+**Versione**: 1.1.0  
 **Ultima modifica**: Aprile 2026  
-**Status**: 🟢 In Development
+**Status**: 🟢 Active
@@ -73,9 +73,11 @@ Accedi a: http://localhost:8000
   ```

 3. **Modificare i file:**
-   - HTML: `app/web/templates/index.html`
+   - HTML: `app/web/templates/index.html`, `servers.html`, `models_running.html`
   - CSS input: `app/web/static/css/input.css` (raramente, usa classi Tailwind)
-   - JavaScript: `app/web/static/js/app.js` e `data-sync.worker.js`
+   - JavaScript: `app/web/static/js/app.js`, `servers.js`, `models-running.js`, `data-sync.worker.js`
+
+   > ⚠️ **Classi Tailwind dinamiche**: Le classi generate dinamicamente via `innerHTML` (es. in accordion o card) **non** vengono rilevate dal JIT scanner. Usa stili inline (`style="..."`) o classi hardcoded nei template HTML per queste situazioni.

 4. **Compilato automaticamente:**
   - Tailwind genera `app/web/static/css/output.css` automaticamente
@@ -198,6 +200,49 @@ npm run tailwind:build

 - [ ] Eseguire `npm run tailwind:build` per minificare
 - [ ] Verificare che `output.css` sia generato
+- [ ] Eseguire i test Python: `make test`
+- [ ] Eseguire i test E2E: `npm run test:e2e`
+
+---
+
+## 🧪 Testing
+
+### Unit Test (pytest)
+
+```bash
+# Tutti i test
+pytest tests/ -v
+
+# Con coverage
+pytest tests/ --cov=app
+```
+
+### E2E Test (Playwright)
+
+I test E2E verificano il comportamento del browser (cache-first, navigazione, PWA).
+
+```bash
+# Installare i browser Playwright (prima volta)
+npx playwright install --with-deps
+
+# Eseguire i test E2E (richiede Ollama attivo)
+OLLAMA_HOST=http://<ollama-host>:11434 npm run test:e2e
+
+# Con report HTML
+npm run test:e2e -- --reporter=html
+```
+
+I test si trovano in `tests/e2e/`. Il report viene generato in `playwright-report/` (gitignored).
+
+### Makefile
+
+```bash
+make test          # pytest
+make lint          # flake8
+make format        # black
+make dev           # uvicorn --reload
+make deploy-no-cache  # Docker rebuild forzato
+```
 - [ ] Controllare che il container Docker usi il CSS compilato
 - [ ] Test performance con Lighthouse
 - [ ] Verifica bundle size `output.css`
@@ -54,13 +54,17 @@ Template HTML con struttura base e caricamento di app.js

 ## 💾 LocalStorage

-### Chiavi memorizzate:
- `llm_monitor_health` - Dati health check (status, ollama_status, timestamp)
- `llm_monitor_models` - Dati modelli (lista, total, totalSize, timestamp)
+I dati sono memorizzati **per server** con chiavi dinamiche:

-### Struttura dati:
+- `llm_monitor_health_<serverId>` - Dati health check
+- `llm_monitor_models_<serverId>` - Dati modelli disponibili
+- `llm_monitor_running_<serverId>` - Modelli in esecuzione
+- `llm_monitor_servers` - Lista istanze Ollama configurate
+- `llm_monitor_active_server` - ID del server attivo

-**Health:**
+La funzione `getServerStorageKey(serverId, suffix)` in `server-config.js` costruisce le chiavi.
+
+### Struttura dati health:
 ```json
 {
  "status": "healthy",
@@ -69,7 +73,7 @@ Template HTML con struttura base e caricamento di app.js
 }
 ```

-**Models:**
+### Struttura dati models:
 ```json
 {
  "models": [
@@ -82,6 +86,9 @@ Template HTML con struttura base e caricamento di app.js
  ],
  "total": 1,
  "totalSize": "3.56 GB",
+  "showByModel": {
+    "llama2": { "details": {}, "model_info": {}, "parameters": "..." }
+  },
  "timestamp": "2024-01-15T10:30:00.000Z"
 }
 ```
@@ -96,6 +103,8 @@ Template HTML con struttura base e caricamento di app.js
 ### ✅ Offline Support
 - I dati rimangono in **localStorage** anche se il server è offline
 - La dashboard mostra l'ultimo stato noto
+- Il **Service Worker** (`service-worker.js`) mette in cache l'app shell (HTML, CSS, JS) per navigazione offline
+- Cache name corrente: `llm-monitor-v3`

 ### ✅ Efficienza di Rete
 - Una sola fetch ogni 30 secondi (dal Worker)
@@ -149,7 +158,6 @@ JSON.parse(localStorage.getItem('llm_monitor_models'))
 ## 🚀 Ottimizzazioni Future

 - [ ] IndexedDB per dati maggiori
- [ ] Service Worker per offline mode completo
 - [ ] Sincronizzazione tra tab (BroadcastChannel API)
 - [ ] Caching intelligente con TTL
 - [ ] Compressione dati (Zstandard/Brotli)
@@ -179,4 +187,4 @@ JSON.parse(localStorage.getItem('llm_monitor_models'))

 ---

-**Sviluppato per LLM Monitor v1.0.0** 🦙
+**Sviluppato per LLM Monitor v1.1.0** 🦙