Focolari-Voting-System/FRONTEND_BASE_PATH.md

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

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:

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

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

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

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

// ❌ 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:

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