feat: add debug build command and update documentation for frontend path changes
This commit is contained in:
EmanueleAlfano
208
FRONTEND_BASE_PATH.md
Normal file
208
FRONTEND_BASE_PATH.md
Normal file
@@ -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`
|
||||
Reference in New Issue
Block a user