Focolari-Voting-System/CHANGE_BASE_PATH.md

🔧 Guida: Come Cambiare il Path Base dell'Applicazione

Contesto

Il sistema Focolari Voting è composto da:

• Backend (FastAPI) che serve sia le API REST che il frontend statico
• Frontend (React SPA) che viene buildato e servito dal backend

Attualmente il frontend è servito su: /badge

---

📍 Configurazione Attuale

Backend serve su:

• API: http://localhost:8000/api/info-room, /api/login-validate, /api/anagrafica/{badge}, /api/entry-request
• Frontend: http://localhost:8000/badge
• Debug page: http://localhost:8000/badge/debug

Frontend in sviluppo:

• Vite dev server su http://localhost:5173 (qualsiasi base path)
• Proxy /api/* verso http://127.0.0.1:8000

---

🔄 Come Cambiare il Path Base

Se in futuro vuoi servire il frontend su un path diverso (es. /votazioni, /app, / per la root), segui questi passaggi:

1️⃣ Backend - backend-mock/main.py

File: /backend-mock/main.py

Cerca le route del frontend (circa linea 94-114):

# Serve index.html su /badge e sue sub-route
@app.get("/badge")
@app.get("/badge/")  # Con trailing slash per Playwright e redirect browser
async def serve_badge_index():
    return FileResponse(STATIC_DIR / "index.html")

@app.get("/badge/debug")
async def serve_badge_debug():
    return FileResponse(STATIC_DIR / "index.html")

# Monta i file statici (JS, CSS, assets) sotto /badge
app.mount("/badge/assets", StaticFiles(directory=STATIC_DIR / "assets"), name="assets")

# Fallback per altri file statici sotto /badge
@app.get("/badge/{filename:path}")
async def serve_static(filename: str):
    # ...

Modifica necessaria:

• Sostituisci /badge con il nuovo path desiderato in TUTTE le occorrenze
• ⚠️ Importante: FastAPI richiede ENTRAMBE le route /path e /path/ (con e senza trailing slash)
• Esempio per /votazioni:

  @app.get("/votazioni")
  @app.get("/votazioni/")  # Con trailing slash
  async def serve_index():
      return FileResponse(STATIC_DIR / "index.html")
  
  @app.get("/votazioni/debug")
  app.mount("/votazioni/assets", ...)
  @app.get("/votazioni/{filename:path}")
  

Cerca anche il messaggio di avvio (circa linea 177):

print(f"🌐 Frontend disponibile su http://{args.host}:{args.port}/badge")

Cambia in:

print(f"🌐 Frontend disponibile su http://{args.host}:{args.port}/NUOVO_PATH")

---

2️⃣ Frontend - frontend/src/main.tsx

File: /frontend/src/main.tsx

Cerca il BrowserRouter (circa linea 12):

<BrowserRouter basename="/badge">

Modifica necessaria:

• Cambia basename="/badge" con il nuovo path
• Esempio: basename="/votazioni" oppure basename="/" per la root

Cerca anche il callback onBack (circa linea 8):

return <DebugScreen onBack={() => window.location.href = '/badge'}/>

Cambia in:

return <DebugScreen onBack={() => window.location.href = '/NUOVO_PATH'}/>

---

3️⃣ Frontend - frontend/vite.config.ts

File: /frontend/vite.config.ts

Cerca il base path per il build (circa linea 10):

// Base path per il frontend servito su /badge
base: '/badge/',

Modifica necessaria:

• Cambia base: '/badge/' con il nuovo path
• Esempio: base: '/votazioni/' oppure base: '/' per la root
• ⚠️ Il trailing slash è importante!

Cerca anche la configurazione proxy (circa linea 32):

// Proxy API in sviluppo verso il backend (porta 8000)
// In produzione il backend serve il frontend su /badge e le API su /api/*
server: {
    proxy: {
        '/api': {
            target: 'http://127.0.0.1:8000',
            changeOrigin: true,
        },
    },
},

Modifica necessaria (solo se cambi il path delle API):

• Se le API cambiano da /api/* a un altro path, aggiorna qui
• Normalmente NON è necessario cambiare questo

Aggiorna anche il commento per riflettere il nuovo path frontend (solo documentazione).

---

4️⃣ Frontend - frontend/playwright.config.ts

File: /frontend/playwright.config.ts

Cerca baseURL (circa linea 22):

use: {
    // URL base del server (frontend servito su /badge)
    baseURL: 'http://localhost:8000/badge',

Cerca webServer.url (circa linea 58):

webServer: {
    command: 'cd .. && ./dev.sh server -d backend-mock/data/users_test.json',
    url: 'http://localhost:8000/badge',

Modifica necessaria:

• Aggiorna entrambi gli URL con il nuovo path
• Esempio: http://localhost:8000/votazioni

---

5️⃣ Come Cambiare il Path delle API (Opzionale)

⚠️ Attenzione: Questo è separato dal path del frontend!

Attualmente le API sono su /api/*. Se vuoi cambiarle (es. /v1/* o /rest/*):

Backend - backend-mock/api/routes.py:

# Cerca tutte le route decorator (4 endpoint)
@router.get("/api/info-room", ...)        # → @router.get("/v1/info-room", ...)
@router.post("/api/login-validate", ...)  # → @router.post("/v1/login-validate", ...)
@router.get("/api/anagrafica/{badge_code}", ...)  # → @router.get("/v1/anagrafica/{badge_code}", ...)
@router.post("/api/entry-request", ...)   # → @router.post("/v1/entry-request", ...)

Frontend - frontend/src/services/api.ts:

// Cerca tutte le chiamate API (4 endpoint)
return apiFetch<RoomInfo>('/api/info-room');        // → '/v1/info-room'
return apiFetch<LoginResponse>('/api/login-validate', ...);  // → '/v1/login-validate'
return apiFetch<User>(`/api/anagrafica/${...}`);    // → `/v1/anagrafica/${...}`
return apiFetch<EntryResponse>('/api/entry-request', ...);   // → '/v1/entry-request'

Frontend - frontend/vite.config.ts:

proxy: {
    '/api': {              // → '/v1': {
        target: 'http://127.0.0.1:8000',
        changeOrigin: true,
    },
},

---

📝 Caso Speciale: Root Path /

Se vuoi servire il frontend direttamente sulla root (http://localhost:8000/):

Backend:

@app.get("/")
async def serve_index():
    return FileResponse(STATIC_DIR / "index.html")

@app.get("/debug")
async def serve_debug():
    return FileResponse(STATIC_DIR / "index.html")

app.mount("/assets", StaticFiles(directory=STATIC_DIR / "assets"), name="assets")

@app.get("/{filename:path}")
async def serve_static(filename: str):
    # ... fallback logic

Frontend:

<BrowserRouter basename="/">
// oppure semplicemente:
<BrowserRouter>

⚠️ Attenzione: Se usi la root, le API REST devono essere montate PRIMA del catch-all /{filename:path}, altrimenti verranno intercettate dal frontend.

---

✅ Checklist Completa

Per Cambiare il Path del Frontend (es. /badge → /votazioni):

• Backend: Modifica tutte le route @app.get("/badge...") → @app.get("/NUOVO_PATH...")
• Backend: ⚠️ Aggiungi route con trailing slash @app.get("/NUOVO_PATH/") per Playwright
• Backend: Modifica app.mount("/badge/assets", ...) → app.mount("/NUOVO_PATH/assets", ...)
• Backend: Aggiorna il messaggio di avvio con il nuovo URL
• Frontend: Aggiorna basename="/badge" in main.tsx
• Frontend: Aggiorna il link di ritorno in DebugWrapper
• Frontend: Aggiorna base: '/badge/' in vite.config.ts
• Frontend: Aggiorna baseURL e webServer.url in playwright.config.ts
• Frontend: (Opzionale) Aggiorna i commenti in vite.config.ts
• Test: Rebuild del frontend con ./dev.sh build
• Test: Avvio del server con ./dev.sh server
• Test: Verifica che http://localhost:8000/NUOVO_PATH funzioni
• Test: Verifica che http://localhost:8000/NUOVO_PATH/ (con slash) funzioni
• Test: Verifica che http://localhost:8000/NUOVO_PATH/debug funzioni
• Test: Verifica che le API continuino a funzionare (servite su /api/*)
• Test: Test E2E con ./dev.sh test:e2e

Per Cambiare il Path delle API (es. /api/* → /v1/*):

• Backend: Modifica tutti i @router.get("/api/...") in api/routes.py
• Frontend: Modifica tutte le chiamate apiFetch('/api/...') in services/api.ts
• Frontend: Aggiorna il proxy in vite.config.ts
• Frontend: Aggiorna baseURL in playwright.config.ts se usi test E2E
• Test: Verifica che tutte le API rispondano sul nuovo path
• Test: Test E2E (./dev.sh test:e2e) per verificare integrazione completa

---

🔬 Test dopo il Cambio

# 1. Pulisci e rebuilda
./dev.sh clean
./dev.sh build

# 2. Avvia il server completo
./dev.sh server

# 3. Testa nel browser
# - http://localhost:8000/NUOVO_PATH
# - http://localhost:8000/NUOVO_PATH/debug
# - http://localhost:8000/docs (API docs, deve rimanere fuori dal path frontend)

# 4. Test API dirette (servite su /api/*)
curl http://localhost:8000/api/info-room
curl http://localhost:8000/api/anagrafica/0008988288

---

🎯 Files da Modificare - Riepilogo

Cambio Path Frontend (/badge → altro):

File	Cosa Modificare	Linee Circa
backend-mock/main.py	Route @app.get("/badge") e varianti	~94-114
backend-mock/main.py	Messaggio avvio print(...)	~177
frontend/src/main.tsx	basename="/badge" in BrowserRouter	~12
frontend/src/main.tsx	window.location.href = '/badge'	~8
frontend/vite.config.ts	base: '/badge/' per build	~10
frontend/vite.config.ts	Commento documentazione (opzionale)	~32
frontend/playwright.config.ts	baseURL in use	~22
frontend/playwright.config.ts	webServer.url	~58

Cambio Path API (/api/* → altro):

File	Cosa Modificare	Linee Circa
backend-mock/api/routes.py	Tutti i @router.get("/api/...") (4 route)	~58, 67, 96, 118
frontend/src/services/api.ts	Tutte le chiamate apiFetch('/api/...') (4 chiamate)	~95, 108, 120, 135
frontend/vite.config.ts	Proxy '/api'	~35

---

💡 Nota Importante

Il sistema usa due path separati:

1. Frontend SPA (React): servito su /badge

   • http://localhost:8000/badge → App principale
   • http://localhost:8000/badge/debug → Pagina debug
   • http://localhost:8000/badge/assets/* → File statici (JS, CSS, immagini)

2. API REST (FastAPI): servite su /api/*

   • http://localhost:8000/api/info-room
   • http://localhost:8000/api/login-validate
   • http://localhost:8000/api/anagrafica/{badge}
   • http://localhost:8000/api/entry-request

Questi due path sono indipendenti e possono essere cambiati separatamente.

Vantaggio: Le API sono sempre accessibili su un path fisso, anche se il frontend cambia posizione.

---

Documento creato: 2026-02-04