feat: update frontend path to '/badge' and adjust related documentation

2026-02-04 13:12:15 +01:00
parent 77bea025fa
commit 458b074f45
10 changed files with 471 additions and 37 deletions
--- a/PATH_STRUCTURE.md
+++ b/PATH_STRUCTURE.md
@@ -0,0 +1,147 @@
+# 🗺️ Struttura Path del Sistema
+
+## Riepilogo Configurazione Attuale
+
+Il sistema Focolari Voting System utilizza una **struttura path separata** per frontend e API:
+
+```
+http://localhost:8000/
+├── /badge              ← Frontend React SPA
+│   ├── /               ← Pagina principale
+│   ├── /debug          ← Pagina diagnostica
+│   └── /assets/*       ← File statici (JS, CSS, immagini)
+│
+├── /api/*              ← API REST
+│   ├── /info-room      ← Informazioni sala
+│   ├── /login-validate ← Login validatore
+│   ├── /anagrafica/{badge} ← Ricerca utente
+│   └── /entry-request  ← Registrazione ingresso
+│
+├── /docs               ← Documentazione API (Swagger)
+└── /                   ← Health check (solo se frontend non buildato)
+```
+
+---
+
+## 🎯 Vantaggi di questa Struttura
+
+1. **Separazione chiara**: Frontend e API sono completamente isolati
+2. **Flessibilità**: Puoi cambiare il path del frontend senza toccare le API
+3. **Sicurezza**: Le API sono su un path fisso, facile da proteggere con firewall/proxy
+4. **Debugging**: È chiaro se un errore viene dal frontend o dalle API
+5. **Deployment**: Puoi servire frontend e API da server diversi in futuro
+
+---
+
+## 📁 Files Coinvolti
+
+### Backend
+
+**File: `backend-mock/main.py`**
+- Gestisce le route del frontend su `/badge`
+- Include il router API che gestisce `/api/*`
+
+**File: `backend-mock/api/routes.py`**
+- Definisce tutte le route API con prefisso `/api/*`
+
+### Frontend
+
+**File: `frontend/src/main.tsx`**
+- Configura il router React con `basename="/badge"`
+
+**File: `frontend/src/services/api.ts`**
+- Tutte le chiamate API usano il prefisso `/api/*`
+
+**File: `frontend/vite.config.ts`**
+- Proxy per development: `/api` → `http://127.0.0.1:8000`
+
+**File: `frontend/playwright.config.ts`**
+- Test E2E configurati per `baseURL: http://localhost:8000/badge`
+
+**File: `frontend/e2e/app.spec.ts`**
+- Intercept delle chiamate API su `**/api/entry-request`
+
+---
+
+## 🔄 Flusso Richieste
+
+### In Sviluppo (Vite Dev Server)
+
+```
+Browser → http://localhost:5173/
+          ↓
+Frontend React (Vite)
+          ↓
+API call to /api/info-room
+          ↓
+Vite Proxy: /api/* → http://127.0.0.1:8000/api/*
+          ↓
+Backend FastAPI
+```
+
+### In Produzione (Server Integrato)
+
+```
+Browser → http://localhost:8000/badge
+          ↓
+Backend FastAPI
+          ├─→ /badge → Serve frontend statico
+          └─→ /api/* → Gestisce API REST
+```
+
+---
+
+## 📋 Checklist Verifica
+
+Per verificare che tutto funzioni correttamente:
+
+```bash
+# 1. Avvia il server
+./dev.sh server
+
+# 2. Testa il frontend
+open http://localhost:8000/badge
+
+# 3. Testa le API
+curl http://localhost:8000/api/info-room
+curl http://localhost:8000/api/anagrafica/0008988288
+
+# 4. Verifica documentazione API
+open http://localhost:8000/docs
+
+# 5. Esegui i test E2E
+./dev.sh test:e2e
+```
+
+---
+
+## 🔧 Come Modificare
+
+Per modificare i path, consulta **`CHANGE_BASE_PATH.md`** che spiega:
+
+- Come cambiare il path del frontend (es. `/badge` → `/votazioni`)
+- Come cambiare il path delle API (es. `/api/*` → `/v1/*`)
+- Quali file modificare per ogni cambiamento
+- Checklist completa di test
+
+---
+
+## 📊 Tabella Riassuntiva
+
+| Componente | Path | Gestito da | File Config |
+|------------|------|------------|-------------|
+| **Frontend principale** | `/badge` | Backend (serve static) | `backend-mock/main.py` |
+| **Frontend debug** | `/badge/debug` | Backend (serve static) | `backend-mock/main.py` |
+| **Frontend assets** | `/badge/assets/*` | Backend (StaticFiles) | `backend-mock/main.py` |
+| **Frontend router** | `/badge` (basename) | React Router | `frontend/src/main.tsx` |
+| **API info sala** | `/api/info-room` | Backend API | `backend-mock/api/routes.py` |
+| **API login** | `/api/login-validate` | Backend API | `backend-mock/api/routes.py` |
+| **API anagrafica** | `/api/anagrafica/{badge}` | Backend API | `backend-mock/api/routes.py` |
+| **API ingresso** | `/api/entry-request` | Backend API | `backend-mock/api/routes.py` |
+| **Proxy dev** | `/api` → `:8000` | Vite | `frontend/vite.config.ts` |
+| **Test E2E** | `baseURL: /badge` | Playwright | `frontend/playwright.config.ts` |
+
+---
+
+Documento creato: 2025-02-04  
+Ultima modifica: 2025-02-04