Viaggi e Itinerari Multi-Tappa: Organizzare l'Avventura
Un viaggio di gruppo non e un semplice evento. E una sequenza di tappe, spostamenti, prenotazioni e attivita che si intrecciano su più giorni e più destinazioni. In Play The Event il modulo viaggi e stato progettato come un aggregato autonomo, con il proprio ciclo di vita, budget e logica di gestione.
Cosa Troverai in Questo Articolo
- L'aggregato Viaggio e il suo ciclo di vita
- Tappe, attivita, alloggi e trasporti
- Budget viaggio separato dal budget evento
- Integrazione con API esterne per suggerimenti
- Mappe interattive con MapLibre GL
- QR code per condivisione rapida
L'Aggregato Viaggio
Il Viaggio e il concetto centrale. Non e semplicemente un "evento che dura più giorni": ha una propria identità, un proprio stato e un set di entità figlie che lo compongono.
public enum StatoViaggio {
DRAFT, // Bozza: in fase di pianificazione
PLANNED, // Pianificato: itinerario definito
CONFIRMED, // Confermato: partecipanti e prenotazioni ok
IN_PROGRESS, // In corso: il viaggio e iniziato
COMPLETED // Completato: viaggio terminato
}
TRANSIZIONI VALIDE:
DRAFT ──────► PLANNED ──────► CONFIRMED
│
▼
IN_PROGRESS ──► COMPLETED
Note:
- Da qualsiasi stato si può tornare a DRAFT (ripianificazione)
- COMPLETED e uno stato finale
- IN_PROGRESS si attiva automaticamente alla data di partenzaOgni transizione di stato può scatenare azioni automatiche: ad esempio, passando a CONFIRMED il sistema invia notifiche ai partecipanti con i dettagli definitivi dell'itinerario.
TappaViaggio: I Mattoni dell'Itinerario
Un viaggio e composto da una o più TappaViaggio. Ogni tappa rappresenta una destinazione con le proprie date, attivita e logistica.
@Entity
public class TappaViaggio {
private Long id;
private Long viaggioId;
private String nome; // "Roma - Centro Storico"
private Integer ordine; // Posizione nell'itinerario
private Destinazione destinazione; // Coordinate + citta + paese
private LocalDate dataArrivo;
private LocalDate dataPartenza;
private String note;
// Relazioni
private List<AttivitaViaggio> attivita;
private List<AlloggioViaggio> alloggi;
private List<TrasportoViaggio> trasporti;
}Destinazione con Coordinate
Ogni tappa ha una Destinazione che include coordinate geografiche (latitudine e longitudine), nome della citta e paese. Le coordinate servono per posizionare i marker sulla mappa interattiva e per calcolare distanze e tempi di percorrenza tra le tappe.
Attivita, Alloggi e Trasporti
Ogni tappa può contenere tre tipi di sotto-entità che coprono tutti gli aspetti logistici del viaggio.
AttivitaViaggio
Le attivita previste durante la tappa: visite guidate, escursioni, cene, eventi locali. Ogni attivita ha un orario, una durata stimata, un costo opzionale e un link per la prenotazione.
AlloggioViaggio
Le informazioni sull'alloggio: nome della struttura, indirizzo, date di check-in e check-out, numero di prenotazione e costo. Il sistema supporta più alloggi per tappa, utile quando il gruppo si divide tra strutture diverse.
TrasportoViaggio
Come ci si sposta tra una tappa e l'altra: voli, treni, autobus, auto a noleggio. Ogni trasporto include il tipo di mezzo, gli orari di partenza e arrivo, il numero di prenotazione e il costo.
VIAGGIO: "Weekend a Roma" (3 giorni, 6 partecipanti)
TAPPA 1: Roma Centro (Giorno 1-2)
├── Destinazione: Roma, Italia (41.9028, 12.4964)
├── Alloggio: Hotel Forum ★★★★
│ ├── Check-in: 14:00
│ └── Costo: 180 EUR/notte
├── Attivita:
│ ├── Colosseo e Foro Romano (09:00 - 12:00, 16 EUR/persona)
│ ├── Pranzo a Trastevere (12:30 - 14:00)
│ └── Musei Vaticani (15:00 - 18:00, 17 EUR/persona)
└── Trasporto IN: Volo FR1234 (Bari → Roma Fiumicino, 07:00)
TAPPA 2: Roma Nord (Giorno 3)
├── Destinazione: Roma, Italia (41.9109, 12.4818)
├── Attivita:
│ ├── Villa Borghese (09:00 - 11:00, gratuito)
│ └── Shopping Via del Corso (11:30 - 14:00)
└── Trasporto OUT: Treno FR9876 (Roma Termini → Bari, 16:00)Budget Viaggio Dedicato
Il budget del viaggio e completamente separato dal budget dell'evento associato. Questo perchè le dinamiche di spesa sono diverse: in un viaggio i costi si distribuiscono su più giorni, categorie e tappe.
Separazione dei Budget
Le SpesaViaggio hanno le proprie categorie (trasporto, alloggio, visti, attivita) e i propri metodi di suddivisione. Un partecipante potrebbe unirsi solo a una tappa del viaggio e quindi contribuire solo alle spese di quella tappa specifica.
Task Viaggio: La To-Do List del Viaggiatore
Ogni viaggio ha una lista di TaskViaggio: le cose da fare prima, durante e dopo il viaggio. Prenotare i voli, fare i visti, preparare i bagagli, confermare gli hotel.
I task possono essere assegnati a specifici partecipanti e hanno scadenze, priorità e stato (da fare, in corso, completato). Il sistema invia promemoria automatici per i task in scadenza.
API Esterne: Suggerimenti Intelligenti
Una delle funzionalità più interessanti e l'integrazione con API esterne per fornire suggerimenti durante la pianificazione.
API Integrate per i Suggerimenti
- Nominatim (OpenStreetMap): Geocoding e reverse geocoding. Dato il nome di una citta, restituisce le coordinate e viceversa.
- WikiVoyage: Informazioni turistiche sulle destinazioni. Guide, consigli pratici e punti di interesse dalla community.
- Foursquare: Suggerimenti per ristoranti, bar, attrazioni e attivita nelle vicinanze della destinazione.
- OpenTripMap: Database di punti di interesse turistici con descrizioni, foto e valutazioni.
Quando l'utente seleziona una destinazione, il sistema interroga queste API in parallelo e presenta i risultati organizzati per categoria: cosa vedere, dove mangiare, dove dormire, cosa fare.
Frontend (Angular)
│
▼
Spring Boot API Gateway
│
├──► Nominatim API → Coordinate, indirizzi
├──► WikiVoyage API → Guide turistiche
├──► Foursquare API → Ristoranti, attrazioni
└──► OpenTripMap API → Punti di interesse
Risultati aggregati e cachati (TTL: 24h)
│
▼
Frontend: Card suggerimenti con "Aggiungi alla tappa"Mappe Interattive con MapLibre GL
L'itinerario prende vita sulla mappa grazie a MapLibre GL. Ogni tappa e visualizzata come un marker numerato, collegato alle altre tappe da linee che rappresentano gli spostamenti.
L'utente può interagire con la mappa: cliccare su un marker per vedere i dettagli della tappa, trascinare i marker per riordinare l'itinerario, e zoomare per esplorare i punti di interesse nelle vicinanze.
Funzionalità della Mappa
- Marker numerati per ogni tappa dell'itinerario
- Linee di collegamento tra tappe consecutive
- Popup con dettagli della tappa al click
- Layer per punti di interesse suggeriti
- Calcolo distanze tra le tappe
- Vista satellite e mappa stradale
QR Code per Condivisione
Ogni viaggio genera un QR code unico che permette di condividere rapidamente l'itinerario. Scansionando il codice, un nuovo partecipante accede alla pagina del viaggio con tutte le informazioni: tappe, date, alloggi, attivita e trasporti.
Questo e particolarmente utile in contesti dal vivo: durante una riunione organizzativa, l'organizzatore proietta il QR code e tutti i partecipanti possono unirsi al viaggio con un semplice scan.
Date di Partenza e Ritorno
Il viaggio ha date globali di partenza e ritorno che delimitano l'intero periodo. Le date delle singole tappe devono rientrare in questo intervallo. Il sistema valida automaticamente la coerenza temporale: una tappa non può iniziare prima della partenza o finire dopo il ritorno.
Validazioni Temporali Automatiche
- Le tappe non possono sovrapporsi temporalmente
- L'ordine delle tappe deve rispettare la cronologia
- I trasporti devono collegare tappe consecutive
- Il check-in dell'alloggio deve coincidere con l'arrivo alla tappa
- Lo stato IN_PROGRESS si attiva alla data di partenza
Punti Chiave
- Il Viaggio e un aggregato autonomo con 5 stati nel ciclo di vita
- Ogni tappa organizza attivita, alloggi e trasporti
- Budget viaggio separato per gestione finanziaria precisa
- 4 API esterne per suggerimenti intelligenti sulle destinazioni
- MapLibre GL per visualizzazione interattiva dell'itinerario
- QR code per condivisione immediata con i partecipanti
Il codice sorgente e disponibile su GitHub. Per esplorare il modulo viaggi in azione, visita www.playtheevent.com.