From 8e8042c851e179406d4f7ca59fb72a8ac4c97215 Mon Sep 17 00:00:00 2001 From: EmanueleAlfano Date: Wed, 4 Feb 2026 15:33:20 +0100 Subject: [PATCH] feat: add debug build command and update documentation for frontend path changes --- FRONTEND_BASE_PATH.md | 208 ++++++++++++++++++++++++++++++++++++++++++ dev.sh | 54 +++++++---- 2 files changed, 245 insertions(+), 17 deletions(-) create mode 100644 FRONTEND_BASE_PATH.md diff --git a/FRONTEND_BASE_PATH.md b/FRONTEND_BASE_PATH.md new file mode 100644 index 0000000..f71a70d --- /dev/null +++ b/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` diff --git a/dev.sh b/dev.sh index b0e089b..b062969 100755 --- a/dev.sh +++ b/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 [opzioni]" echo "" echo "Comandi disponibili:" - echo " install Installa dipendenze frontend e backend" - echo " dev Avvia frontend (dev) + backend (api-only) in parallelo" - echo " build Builda il frontend per produzione" - echo " server Builda frontend (se cambiato) e avvia server completo" - echo " backend Avvia solo il backend (api-only)" - echo " frontend Avvia solo il frontend in dev mode" - echo " test Esegue i test frontend (unit)" - 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 " install Installa dipendenze frontend e backend" + echo " dev Avvia frontend (dev) + backend (api-only) in parallelo" + echo " build Builda il frontend per produzione" + echo " build:debug Builda il frontend in modalitΓ  DEBUG (no minify, sourcemap)" + echo " server Builda frontend (se cambiato) e avvia server completo" + echo " server:debug Builda DEBUG + avvia server (per debug con Chrome DevTools)" + echo " backend Avvia solo il backend (api-only)" + echo " frontend Avvia solo il frontend in dev mode" + echo " test Esegue i test frontend (unit)" + 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 " clean Pulisce build e cache" - echo " help Mostra questo messaggio" + echo " shell Apre shell pipenv del backend" + echo " clean Pulisce build e cache" + echo " help Mostra questo messaggio" echo "" echo "Esempi:" - echo " ./dev.sh install # Setup iniziale" - echo " ./dev.sh dev # Sviluppo (hot reload)" - echo " ./dev.sh server # Produzione locale (accessibile da rete)" - echo " ./dev.sh server -p 9000 # Server su porta 9000" + echo " ./dev.sh install # Setup iniziale" + echo " ./dev.sh dev # Sviluppo (hot reload)" + echo " ./dev.sh server # Produzione locale (accessibile da rete)" + 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 "$@"