148 lines
4.2 KiB
Markdown
148 lines
4.2 KiB
Markdown
# 🗺️ 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
|