09 - Viaggi e Itinerari Multi-Tappa: Organizzare l\

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.

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 partenza

Ogni 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.

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.

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.

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.

Il codice sorgente e disponibile su GitHub. Per esplorare il modulo viaggi in azione, visita www.playtheevent.com.