feat: add debug build command and update documentation for frontend path changes

FRONTEND_BASE_PATH.md

@@ -0,0 +1,208 @@
+# 📍 Guida Modifica Base Path Frontend
+
+## Situazione Attuale
+
+Il frontend è servito su `/badge` e le API su `/api/*`.
+
+- **Frontend URL:** `http://server:8000/badge`
+- **API URL:** `http://server:8000/api/*`
+
+---
+
+## 🔧 Quando Cambia il Base Path
+
+Se in futuro il frontend deve essere servito su un path diverso (es. `/admin`, `/voting`, `/`), segui questi passi:
+
+### 1. Frontend - Vite Config (`frontend/vite.config.ts`)
+
+```typescript
+export default defineConfig({
+    // ...
+    base: '/nuovo-path/',  // ⚠️ IMPORTANTE: trailing slash!
+    // ...
+})
+```
+
+**❗ Attenzione:** Il trailing slash `/` finale è **obbligatorio** per il corretto funzionamento degli asset statici (JS, CSS, immagini).
+
+### 2. Backend - Configurazione Mount Point
+
+#### File: `backend-mock/main.py`
+
+Cerca la sezione **"Mount frontend statico"** e modifica:
+
+```python
+# Mount frontend statico su /nuovo-path
+app.mount(
+    "/nuovo-path",  # ⚠️ Cambia questo path
+    StaticFiles(directory=frontend_dist, html=True),
+    name="frontend"
+)
+```
+
+**📝 Esempi comuni:**
+
+- Root path: `base: '/'` → `app.mount("/", ...)`
+- Admin panel: `base: '/admin/'` → `app.mount("/admin", ...)`
+- Voting: `base: '/voting/'` → `app.mount("/voting", ...)`
+
+### 3. Backend - Messaggio Startup
+
+Nello stesso file `main.py`, cerca i messaggi di logging all'avvio e aggiorna:
+
+```python
+logger.info("=" * 50)
+logger.info(f"📍 Server in ascolto su http://{args.host}:{args.port}")
+logger.info(f"📚 Documentazione API su http://{args.host}:{args.port}/docs")
+logger.info(f"🌐 Frontend disponibile su http://{args.host}:{args.port}/nuovo-path")  # ⚠️ Aggiorna
+logger.info("=" * 50)
+```
+
+### 4. Documentazione - Aggiorna README
+
+Nei file:
+- `README.md`
+- `ai-prompts/01-backend-plan.md`
+- `ai-prompts/02-frontend-plan.md`
+
+Cerca tutte le occorrenze di `http://localhost:8000/badge` e sostituisci con il nuovo path.
+
+---
+
+## 🧪 Test Dopo la Modifica
+
+### Build e Test Locale
+
+```bash
+# 1. Pulisci build precedente
+./dev.sh clean
+
+# 2. Rebuilda frontend
+./dev.sh build
+
+# 3. Avvia server
+./dev.sh server
+
+# 4. Apri browser e verifica:
+#    - Frontend carica correttamente
+#    - Asset JS/CSS caricano (non 404)
+#    - Logo e immagini caricano
+#    - API chiamano /api/* correttamente
+```
+
+### Verifica Network Tab (Chrome DevTools)
+
+1. Apri `http://localhost:8000/nuovo-path`
+2. Apri DevTools (F12) → Tab **Network**
+3. Ricarica pagina (Ctrl+R / Cmd+R)
+4. Verifica che **non ci siano 404**:
+   - ✅ `/nuovo-path/` → 200 OK (index.html)
+   - ✅ `/nuovo-path/assets/index-*.js` → 200 OK
+   - ✅ `/nuovo-path/assets/index-*.css` → 200 OK
+   - ✅ `/api/info-room` → 200 OK
+
+---
+
+## 🐛 Debug Build in Produzione
+
+Se hai problemi con la build di produzione (codice minificato difficile da debuggare), usa:
+
+```bash
+./dev.sh server:debug
+```
+
+Questo comando:
+- Buildar **senza minificazione**
+- Genera **sourcemap** per debug
+- Permette di vedere codice leggibile in Chrome DevTools
+
+**⚠️ Nota:** Non usare `server:debug` in produzione reale, solo per debugging locale!
+
+---
+
+## 📊 Checklist Completa Cambio Path
+
+- [ ] `frontend/vite.config.ts` → `base: '/nuovo-path/'` (con trailing slash)
+- [ ] `backend-mock/main.py` → `app.mount("/nuovo-path", ...)`
+- [ ] `backend-mock/main.py` → Aggiorna messaggio startup
+- [ ] `README.md` → Aggiorna esempi URL
+- [ ] `ai-prompts/*.md` → Aggiorna documentazione
+- [ ] `./dev.sh clean` → Pulisci cache
+- [ ] `./dev.sh build` → Rebuilda
+- [ ] `./dev.sh server` → Testa
+- [ ] Browser → Verifica Network Tab (no 404)
+- [ ] Test E2E → `./dev.sh test:e2e` (aggiorna baseURL se necessario)
+
+---
+
+## 🔍 File Rilevanti
+
+| File | Cosa Modificare |
+|------|-----------------|
+| `frontend/vite.config.ts` | `base: '/path/'` |
+| `backend-mock/main.py` | `app.mount("/path", ...)` |
+| `frontend/playwright.config.ts` | `baseURL` (solo se cambi porta) |
+| `README.md` | Esempi URL nella documentazione |
+
+---
+
+## ⚡ Path API (Separati dal Frontend)
+
+Le API sono **sempre** servite su `/api/*` indipendentemente dal path del frontend.
+
+**Esempi:**
+
+- Frontend su `/badge` → API su `/api/*` ✅
+- Frontend su `/admin` → API su `/api/*` ✅
+- Frontend su `/` → API su `/api/*` ✅
+
+**NON serve modificare nulla nelle chiamate API del frontend**, il proxy Vite gestisce tutto automaticamente.
+
+---
+
+## 💡 Best Practices
+
+1. **Trailing slash**: Usa sempre `/path/` (non `/path`) in `vite.config.ts`
+2. **Test incrementale**: Cambia un file alla volta e testa subito
+3. **Pulisci cache**: Dopo ogni cambio, fai `./dev.sh clean`
+4. **Browser cache**: In DevTools, usa "Disable cache" durante test
+5. **Debug mode**: Usa `server:debug` per vedere codice non minificato
+
+---
+
+## 📞 Risoluzione Problemi
+
+### Asset 404 dopo cambio path
+
+**Causa:** Probabilmente manca trailing slash in `vite.config.ts`
+
+```typescript
+// ❌ SBAGLIATO
+base: '/badge'
+
+// ✅ CORRETTO
+base: '/badge/'
+```
+
+### API 404 (es. /api/info-room)
+
+**Causa:** Backend non ha montato correttamente le routes API
+
+**Soluzione:** Verifica che in `main.py` ci sia:
+
+```python
+app.include_router(api_router, prefix="/api")
+```
+
+### Frontend carica ma è tutto bianco
+
+**Causa:** Path base non corrisponde tra frontend e backend
+
+**Soluzione:**
+- Frontend `base: '/badge/'` → Backend `app.mount("/badge", ...)`
+- Devono coincidere!
+
+---
+
+**Ultimo aggiornamento:** 2024-02-04  
+**Path corrente:** `/badge`

dev.sh

@@ -85,6 +85,15 @@ cmd_build() {
     success "Frontend buildato in $FRONTEND_DIST"
 }
 
+# Build frontend in modalità debug (senza minificazione)
+cmd_build_debug() {
+    info "Build frontend in modalità DEBUG (no minification)..."
+    cd "$FRONTEND_DIR"
+    npm run build -- --minify false --sourcemap
+    success "Frontend DEBUG buildato in $FRONTEND_DIST"
+    warn "Nota: questa build NON è ottimizzata per produzione"
+}
+
 # Verifica se serve rebuild
 needs_rebuild() {
     # Se dist non esiste, serve build
@@ -330,29 +339,33 @@ cmd_help() {
     echo "Utilizzo: ./dev.sh <comando> [opzioni]"
     echo ""
     echo "Comandi disponibili:"
-    echo "  install    Installa dipendenze frontend e backend"
+    echo "  install        Installa dipendenze frontend e backend"
-    echo "  dev        Avvia frontend (dev) + backend (api-only) in parallelo"
+    echo "  dev            Avvia frontend (dev) + backend (api-only) in parallelo"
-    echo "  build      Builda il frontend per produzione"
+    echo "  build          Builda il frontend per produzione"
-    echo "  server     Builda frontend (se cambiato) e avvia server completo"
+    echo "  build:debug    Builda il frontend in modalità DEBUG (no minify, sourcemap)"
-    echo "  backend    Avvia solo il backend (api-only)"
+    echo "  server         Builda frontend (se cambiato) e avvia server completo"
-    echo "  frontend   Avvia solo il frontend in dev mode"
+    echo "  server:debug   Builda DEBUG + avvia server (per debug con Chrome DevTools)"
-    echo "  test       Esegue i test frontend (unit)"
+    echo "  backend        Avvia solo il backend (api-only)"
-    echo "  test:watch Esegue i test frontend in watch mode"
+    echo "  frontend       Avvia solo il frontend in dev mode"
-    echo "  test:dev   Avvia server + test in watch mode"
+    echo "  test           Esegue i test frontend (unit)"
-    echo "  test:e2e   Test E2E headless (server auto)"
+    echo "  test:watch     Esegue i test frontend in watch mode"
+    echo "  test:dev       Avvia server + test in watch mode"
+    echo "  test:e2e       Test E2E headless (server auto)"
     echo "  test:e2e:headed  Test E2E con browser visibile"
     echo "  test:e2e:ui      Playwright UI per debug interattivo"
-    echo "  shell      Apre shell pipenv del backend"
+    echo "  shell          Apre shell pipenv del backend"
-    echo "  clean      Pulisce build e cache"
+    echo "  clean          Pulisce build e cache"
-    echo "  help       Mostra questo messaggio"
+    echo "  help           Mostra questo messaggio"
     echo ""
     echo "Esempi:"
-    echo "  ./dev.sh install              # Setup iniziale"
+    echo "  ./dev.sh install                  # Setup iniziale"
-    echo "  ./dev.sh dev                  # Sviluppo (hot reload)"
+    echo "  ./dev.sh dev                      # Sviluppo (hot reload)"
-    echo "  ./dev.sh server               # Produzione locale (accessibile da rete)"
+    echo "  ./dev.sh server                   # Produzione locale (accessibile da rete)"
-    echo "  ./dev.sh server -p 9000       # Server su porta 9000"
+    echo "  ./dev.sh server:debug             # Build DEBUG + server (per debug Chrome)"
+    echo "  ./dev.sh server -p 9000           # Server su porta 9000"
     echo "  ./dev.sh server --host 127.0.0.1  # Solo localhost (non accessibile da rete)"
     echo "  ./dev.sh server -d data/users_test.json  # Con dataset test"
+    echo "  ./dev.sh build:debug              # Solo build DEBUG (senza avviare server)"
     echo ""
     echo "Note:"
     echo "  - Il server usa --host 0.0.0.0 di default (accessibile da tutta la rete locale)"
@@ -369,10 +382,17 @@ case "${1:-help}" in
     build)
         cmd_build
         ;;
+    "build:debug")
+        cmd_build_debug
+        ;;
     server)
         shift
         cmd_server "$@"
         ;;
+    "server:debug")
+        shift
+        cmd_server_debug "$@"
+        ;;
     backend)
         shift
         cmd_backend "$@"