# 📍 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`