08 - Gestione Spese Intelligente: Oltre il Foglio Excel

Gestione Spese Intelligente: Oltre il Foglio Excel

Chiunque abbia organizzato un evento con altre persone conosce il problema: "Chi ha pagato cosa? Quanto devo a chi?". In Play The Event la gestione delle spese non e un semplice elenco di costi. E un sistema intelligente che calcola, suddivide e traccia ogni centesimo in tempo reale.

4 Metodi di Suddivisione: Ognuno Paga il Giusto

Il cuore del sistema spese e la flessibilità nella suddivisione. Non tutti gli eventi sono uguali e non tutte le spese vanno divise allo stesso modo. Per questo Play The Event supporta quattro modalità distinte.

EQUAL: Divisione Equa

Il caso più semplice: il totale viene diviso in parti uguali tra tutti i partecipanti selezionati. Se una cena costa 120 euro e partecipano 4 persone, ognuno deve 30 euro. Il sistema gestisce automaticamente gli arrotondamenti.

PERCENTAGE: Divisione Percentuale

Utile quando i contributi non sono uguali ma proporzionali. Ad esempio, per un regalo collettivo dove alcuni vogliono contribuire di più. Il sistema valida che le percentuali sommino esattamente al 100%.

FIXED: Importi Fissi

Ogni partecipante paga un importo predefinito. Perfetto per eventi dove i costi sono già concordati: "Tu paghi il DJ, io pago il catering".

CUSTOM: Suddivisione Personalizzata

La modalità più flessibile: si possono combinare importi fissi e proporzioni variabili. Gestisce scenari complessi come "3 persone dividono equamente il 70%, una persona paga il restante 30%".

public enum TipoSuddivisione {
    EQUAL,       // Divisione equa tra partecipanti
    PERCENTAGE,  // Suddivisione per percentuale
    FIXED,       // Importi fissi per persona
    CUSTOM       // Combinazione personalizzata
}

// Entità Spesa (semplificata)
@Entity
public class Spesa {
    private Long id;
    private String descrizione;
    private BigDecimal importo;
    private String valuta;            // EUR, USD, GBP...
    private CategoriaSpesa categoria;
    private TipoSuddivisione tipoSuddivisione;
    private LocalDateTime dataCreazione;
    private String urlRicevuta;       // Link alla ricevuta
    private Long eventoId;
    private Long creatoDaUtenteId;
    private List<RipartizionePartecipante> ripartizioni;
}

Categorie Spese: Ordine nel Caos

Ogni spesa appartiene a una categoria predefinita. Questo permette di generare report dettagliati e capire dove vanno i soldi.

public enum CategoriaSpesa {
    FOOD,            // Cibo e bevande
    TRANSPORT,       // Trasporti
    ACCOMMODATION,   // Alloggio
    ENTERTAINMENT,   // Intrattenimento
    DECORATION,      // Decorazioni
    EQUIPMENT,       // Attrezzature
    VENUE,           // Affitto location
    STAFF,           // Personale
    MARKETING,       // Promozione
    OTHER            // Altro
}

Le categorie sono utilizzate anche nel dashboard analytics per visualizzare la distribuzione dei costi tramite grafici a torta e barre, permettendo agli organizzatori di ottimizzare il budget degli eventi futuri.

Supporto Multi-Valuta

Per eventi internazionali o viaggi di gruppo, le spese possono essere in valute diverse. Il servizio ExchangeRateService si occupa delle conversioni.

@Service
public class ExchangeRateService {

    // Cache dei tassi con TTL di 1 ora
    private final Map<String, CachedRate> rateCache;

    public BigDecimal convert(BigDecimal amount,
                              String fromCurrency,
                              String toCurrency) {
        if (fromCurrency.equals(toCurrency)) {
            return amount;
        }
        BigDecimal rate = getExchangeRate(fromCurrency, toCurrency);
        return amount.multiply(rate)
                     .setScale(2, RoundingMode.HALF_UP);
    }

    // Recupera tasso da API esterna con fallback su cache
    private BigDecimal getExchangeRate(String from, String to) {
        String key = from + "_" + to;
        CachedRate cached = rateCache.get(key);
        if (cached != null && !cached.isExpired()) {
            return cached.getRate();
        }
        // Chiamata API esterna per tasso aggiornato
        BigDecimal freshRate = fetchFromExternalApi(from, to);
        rateCache.put(key, new CachedRate(freshRate));
        return freshRate;
    }
}

Settlement Tracking: Chi Deve Cosa a Chi

Una volta inserite tutte le spese, il sistema calcola automaticamente i settlement: i trasferimenti necessari per pareggiare i conti. L'algoritmo minimizza il numero di transazioni necessarie.

Ogni settlement include un timestamp di creazione e uno di completamento. Quando un partecipante salda il debito, l'organizzatore segna il pagamento come completato e il sistema registra data e ora esatta.

@Entity
public class RipartizionePartecipante {
    private Long id;
    private Long partecipanteId;
    private Long spesaId;
    private BigDecimal importoDovuto;
    private BigDecimal importoPagato;
    private Boolean saldato;
    private LocalDateTime dataSaldamento;
    private String note;
}

Ricevute e Documentazione

Ogni spesa può avere una ricevuta allegata tramite URL. Gli utenti possono caricare foto di scontrini o fatture, e il link viene salvato nel campo urlRicevuta. Questo e fondamentale per la trasparenza: ogni partecipante può verificare la spesa consultando la ricevuta originale.

Spese Viaggio: Un Mondo a Parte

Le spese di viaggio (SpesaViaggio) sono gestite separatamente dalle spese evento. Hanno un proprio ciclo di vita, categorie dedicate (trasporto, alloggio, visti) e sono collegate a una specifica tappa del viaggio.

API Riepilogo e Export Excel

Il backend espone un endpoint dedicato per il riepilogo spese che aggrega tutti i dati: totale per categoria, totale per partecipante, saldo di ogni persona e lista dei settlement pendenti.

Per chi ha bisogno di un report formale, il sistema offre l'export in formato Excel generato con Apache POI. Il file include fogli separati per il riepilogo generale, il dettaglio per categoria e la situazione debitoria di ogni partecipante.

GET /api/eventi/{eventoId}/spese/riepilogo

Response:
{
  "totaleEvento": 1250.00,
  "valuta": "EUR",
  "numeroSpese": 15,
  "perCategoria": {
    "FOOD": 450.00,
    "VENUE": 500.00,
    "ENTERTAINMENT": 200.00,
    "DECORATION": 100.00
  },
  "perPartecipante": [ ... ],
  "settlementPendenti": [ ... ]
}

GET /api/eventi/{eventoId}/spese/export/excel
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Budget Template con Univerjs

Una delle funzionalità più apprezzate e il foglio di calcolo integrato. Grazie all'integrazione con Univerjs, gli organizzatori hanno a disposizione un vero spreadsheet nel browser per pianificare il budget.

Il sistema offre entità dedicate: FoglioCalcolo per i fogli personalizzati e TemplateFoglioCalcolo per template riutilizzabili. Gli organizzatori possono partire da un template (es. "Budget Matrimonio", "Budget Team Building") e personalizzarlo per il proprio evento.

Calcoli in Tempo Reale

Ogni volta che una spesa viene aggiunta o modificata, il sistema ricalcola automaticamente tutte le ripartizioni. Non serve premere "aggiorna" o "ricalcola": i saldi sono sempre aggiornati.

Questo approccio reattivo e fondamentale per la user experience. L'organizzatore vede in tempo reale l'impatto di ogni spesa sul budget complessivo e sulla situazione debitoria di ogni partecipante.

Il codice sorgente del progetto e disponibile su GitHub. Per provare il sistema completo, visita www.playtheevent.com.