Come costruire un'agenda collaborativa con filtri

L'agenda di TAMSIV è iniziato come un semplice componente: un elenco di eventi, un calendario, una vista giornaliera. Poi sono arrivati i gruppi collaborativi. Improvvisamente, un evento non era più personale — poteva avere partecipanti, inviti, stati. E con 15 persone in un gruppo attivo, l'agenda è diventata illeggibile senza filtri.

Ho dovuto ripensare l'intero sistema: sistema di partecipanti con inviti e notifiche, filtri avanzati per navigare nel flusso, eventi multi-giorno e un overlay privato per vedere i propri impegni personali nel contesto del gruppo. L'agenda è diventata il componente più complesso di TAMSIV — ma anche il più utile quotidianamente.

Punti chiave da ricordare:
- Un'agenda collaborativa richiede un sistema di partecipanti con stati (invitato, accettato, rifiutato)
- I filtri avanzati sono indispensabili non appena l'attività del gruppo supera i 10 eventi/settimana
- Gli eventi multi-giorno richiedono un calcolo degli intervalli con gestione dei fusi orari
- L'overlay privato nell'agenda di gruppo preserva la riservatezza evitando i conflitti
- 5 viste del calendario (giorno, 3 giorni, settimana, mese, lista) coprono tutti i casi d'uso

Perché un'agenda personale non è sufficiente in un'app collaborativa?

Finché TAMSIV era un'app strettamente personale, l'agenda era semplice. Tu crei un evento, lo vedi nel tuo calendario, punto. Ma quando ho aggiunto i gruppi gerarchici, tutto è cambiato.

In un gruppo (famiglia, team, associazione), gli eventi sono condivisi. Una riunione, una cena di famiglia, una partita sportiva — tutti devono vederlo. Ma non tutti vogliono vedere tutti gli eventi. Il manager vuole vedere le riunioni del suo team, non le uscite del gruppo bowling. Il genitore vuole vedere le attività dei figli, non gli incontri professionali del coniuge.

È qui che i filtri e il sistema di partecipanti diventano essenziali. Senza di essi, l'agenda collaborativa è un inutile caos.

Come funziona il sistema di partecipanti in TAMSIV?

Ogni evento in TAMSIV può avere partecipanti invitati tra i membri del gruppo. L'architettura si basa su una tabella di collegamento nello schema collaborative:

-- Tabella semplificata
calendar_event_participants (
  id UUID PRIMARY KEY,
  event_id UUID REFERENCES privat.calendar_events,
  user_id UUID REFERENCES auth.users,
  status TEXT CHECK (status IN ('invited', 'accepted', 'declined')),
  invited_at TIMESTAMPTZ,
  responded_at TIMESTAMPTZ
)

Il flusso di invito è il seguente:

1. Il creatore aggiunge partecipanti durante la creazione o la modifica dell'evento. Sceglie tra i membri del gruppo tramite un picker.
2. Notifica push: Ogni partecipante invitato riceve una notifica FCM con il titolo dell'evento, la data e un pulsante per accettare o rifiutare.
3. Risposta: Il partecipante accetta o rifiuta. Il suo stato viene aggiornato in tempo reale nel database.
4. Visibilità: L'evento appare nell'agenda di tutti i partecipanti (invitati, accettati). I rifiutati non lo vedono più (a meno che non cambino idea).

È un flusso simile a quello che trovi in Google Calendar, ma adattato al contesto dei gruppi gerarchici di TAMSIV. La differenza principale: i partecipanti sono limitati ai membri del gruppo, non a qualsiasi indirizzo email.

Quali filtri avanzati sono indispensabili in un'agenda di gruppo?

La FilterBar dell'agenda propone tre modalità di filtraggio:

• "Tutti": Mostra tutti gli eventi del gruppo. Utile per avere una panoramica, ma rapidamente rumoroso in un gruppo attivo.
• "Le mie creazioni": Mostra solo gli eventi che tu hai creato. Utile per verificare che i tuoi eventi siano ben pianificati.
• "Partecipante": Mostra solo gli eventi a cui tu sei partecipante (invitato o accettato). È la modalità più utilizzata — risponde alla domanda "A cosa devo essere presente?".

Questi filtri si applicano in tempo reale, senza ricaricare la pagina. Il ContentCacheService memorizza gli eventi in cache, e i filtri operano lato client sui dati memorizzati. Il risultato: un cambio di filtro è istantaneo, anche con centinaia di eventi.

Oltre ai filtri per partecipazione, la FilterBar propone i 3 contesti classici di TAMSIV:

• Privato: Solo i tuoi eventi personali
• Condiviso: Eventi dei gruppi a cui tu appartieni
• Tutto: Fusione delle due viste

Questi filtri sono coerenti con quelli del feed e delle attività. L'utente ritrova gli stessi paradigmi di navigazione in tutta l'app.

Come gestire gli eventi multi-giorno in un componente calendario?

Un evento "Conferenza lunedì→mercoledì" deve apparire per 3 giorni nella vista calendario. Sembra banale, ma l'implementazione è piena di insidie.

Il componente AgendaView calcola gli span — la durata in giorni di ogni evento. Per ogni giorno visualizzato, determina quali eventi lo coprono e li posiziona visivamente:

• Vista giorno: L'evento multi-giorno appare come una fascia in alto, sopra gli eventi orari.
• Vista settimana: L'evento si estende orizzontalmente sulle colonne corrispondenti ai giorni coperti.
• Vista mese: Stesso principio, con un sistema di troncamento se troppi eventi si sovrappongono.
• Vista lista: L'evento appare una sola volta, con le sue date di inizio e fine.

L'insidia principale: i fusi orari ai confini del giorno. Un evento che inizia alle 23:00 di lunedì in UTC+1 e finisce alle 2:00 di martedì copre 1 o 2 giorni? La risposta dipende dal fuso orario dell'utente. Ho optato per una logica semplice: un evento copre un giorno se ha almeno un'ora di presenza in quel giorno, nel fuso orario locale dell'utente.

Cos'è l'overlay privato e perché è essenziale?

Ecco lo scenario: tu sei nell'agenda del tuo gruppo professionale. Vuoi pianificare una riunione martedì alle 14:00. Ma martedì alle 14:00, tu hai un appuntamento medico personale. Come saperlo senza uscire dall'agenda del gruppo?

Questo è il ruolo dell'overlay privato. Nell'agenda di gruppo, i tuoi eventi personali appaiono in trasparenza, ingrigiti. Non sono cliccabili, non ci sono dettagli visibili — solo un blocco per segnalare "tu hai già qualcosa qui".

Le regole dell'overlay:

• Visibile solo a te: Gli altri membri del gruppo non vedono i tuoi eventi privati.
• Non interattivo: Nessun clic, nessun dettaglio, nessuna modifica dalla vista gruppo.
• Visivamente discreto: Opacità ridotta (30%), colore grigio, nessun titolo visibile. Solo un indicatore di "slot occupato".
• Disattivabile: Un toggle nelle impostazioni permette di nascondere l'overlay se non lo desideri.

Questo overlay rispetta la riservatezza evitando i conflitti di orario. È un pattern che ho ripreso da Google Calendar (che mostra "Occupato" per gli eventi degli altri), adattato al contesto di un gruppo dove la vita privata è importante.

Come le 5 viste del calendario coprono tutti i casi d'uso?

TAMSIV propone 5 viste del calendario, ognuna adattata a un'esigenza diversa:

1. Vista giorno: Timeline ora per ora. Ideale per pianificare una giornata intensa, vedere gli slot liberi. Utilizzata quando tu cerchi "Quando sono libero oggi?".
2. Vista 3 giorni: Compromesso tra il dettaglio del giorno e la visione della settimana. La mia preferita per la pianificazione a breve termine. Tu vedi oggi + i prossimi 2 giorni.
3. Vista settimana: La classica vista business. 7 colonne, ogni giorno visibile. Utile per i team che pianificano settimanalmente.
4. Vista mese: Panoramica. Gli eventi sono pastiglie colorate. Utile per individuare i periodi intensi e i giorni liberi. Coerente con la visione di produttività dell'app.
5. Vista lista: Lista cronologica semplice. Nessuna griglia, nessun posizionamento. Utile su mobile quando la vista settimana è troppo piccola, o per esportare/condividere.

Ogni vista mantiene la data corrente durante il cambio di vista. Se tu sei sul mercoledì 15 in vista giorno e passi alla vista settimana, tu vedi la settimana del 15. Lo swipe orizzontale permette di navigare nel tempo (giorno precedente/successivo, settimana precedente/successiva).

Come interagisce l'agenda con la pipeline vocale di TAMSIV?

Uno dei punti di forza di TAMSIV è la creazione di eventi tramite la voce. Tu dici "Aggiungi una riunione con Marco martedì prossimo alle 14:00" e il dittafono crea l'evento. Il backend utilizza la funzione tool create_calendar_event per estrarre la data, l'ora, il titolo e i partecipanti menzionati.

Il sistema di PendingCreation si applica anche agli eventi: l'IA crea un'anteprima, l'utente può modificare i dettagli (aggiungere partecipanti, modificare l'ora) prima di convalidare. Questo evita errori di trascrizione — "martedì" vs "mercoledì" è un classico errore STT.

Una volta creato l'evento, la cache Realtime propaga il cambiamento: tutti i partecipanti vedono l'evento apparire nella loro agenda senza aggiornare. La notifica push parte in parallelo. L'intero flusso — voce → IA → creazione → notifica → visualizzazione — richiede circa 3 secondi.

Quali sono state le maggiori difficoltà tecniche?

L'agenda è il componente più complesso di TAMSIV. Ecco le principali sfide che ho incontrato:

• Performance di rendering: La vista settimana con oltre 50 eventi e l'overlay privato deve rimanere fluida. Ho dovuto usare React.memo in modo aggressivo e virtualizzare le liste di eventi nella vista lista.
• Gestione dello scroll: Lo swipe orizzontale per navigare tra giorni/settimane entra in conflitto con lo scroll verticale della timeline. Ho usato un GestureDetector di react-native-gesture-handler con soglie di direzione per disambiguare.
• Eventi impilati: Quando 3 eventi si sovrappongono nello stesso slot, è necessario disporli fianco a fianco nella timeline. L'algoritmo di layout degli eventi impilati non è banale — è un problema di pianificazione degli intervalli.
• RLS Supabase: Le politiche Row Level Security per gli eventi di gruppo sono complesse. Un evento è visibile se: tu l'hai creato, OPPURE tu sei partecipante, OPPURE tu sei membro del gruppo e l'evento è pubblico. Tre condizioni OR in una singola politica RLS.

Come questa architettura si estende alle future esigenze?

L'architettura attuale è progettata per evolvere. Ecco le estensioni previste nella roadmap:

• Ricorrenza: Eventi ricorrenti (ogni lunedì, il 1° di ogni mese). Lo schema DB è pronto, il frontend non ancora.
• Sincronizzazione calendario esterno: Import/export iCal per sincronizzare con Google Calendar, Outlook, Apple Calendar.
• Disponibilità condivisa: Mostrare gli slot di disponibilità dei membri del gruppo per facilitare la pianificazione.
• Promemoria personalizzati: Ogni partecipante può configurare i propri promemoria (5 min prima, 1h prima, il giorno prima).

FAQ

Si possono invitare partecipanti al di fuori del gruppo?

Attualmente no. I partecipanti sono limitati ai membri del gruppo in cui l'evento è creato. È una scelta deliberata per semplificare la gestione dei permessi. L'invito via email (come Google Calendar) è previsto in una versione futura.

Come funzionano le notifiche di invito?

Gli inviti attivano una notifica push tramite Firebase Cloud Messaging. Il partecipante riceve il titolo dell'evento, la data/ora, e può accettare o rifiutare direttamente dalla notifica (pulsanti di azione FCM). La risposta viene registrata in tempo reale in Supabase.

L'overlay privato funziona in tutte le viste?

Sì, l'overlay privato è attivo in tutte le 5 viste (giorno, 3 giorni, settimana, mese, lista). Nella vista mese, gli eventi privati appaiono come discreti punti grigi. Nelle viste temporali (giorno, settimana), appaiono come blocchi trasparenti.

L'agenda di TAMSIV sostituisce Google Calendar?

No, lo completa. L'agenda TAMSIV è progettata per la gestione di attività e progetti collaborativi, con la voce come modalità di interazione principale. Google Calendar rimane più adatto per la gestione di calendari puri (ricorrenze complesse, sincronizzazione multi-dispositivo). La sincronizzazione tra i due è nella roadmap.

Si può creare un evento tramite la voce con partecipanti?

Sì. Tu puoi dire "Riunione con Marco e Sofia venerdì alle 10:00" e l'IA rileverà i partecipanti menzionati, a condizione che siano membri del gruppo attivo. Il sistema di PendingCreation ti permette di verificare e regolare i partecipanti prima della convalida.