🗺️ 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

Separazione chiara: Frontend e API sono completamente isolati
Flessibilità: Puoi cambiare il path del frontend senza toccare le API
Sicurezza: Le API sono su un path fisso, facile da proteggere con firewall/proxy
Debugging: È chiaro se un errore viene dal frontend o dalle API
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:

# 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

4.2 KiB Raw Blame History