209 lines
5.3 KiB
Markdown
209 lines
5.3 KiB
Markdown
# 📍 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`
|