Come funziona la sincronizzazione

SyncEngine

SyncEngine e il componente centrale dell'architettura offline di tikento. E responsabile di:

• Salvare le modifiche nel database locale (IndexedDB tramite Dexie.js)
• Tracciare le modifiche in attesa di sincronizzazione (pendingSync=true)
• Inviare le modifiche al server al ripristino della connessione
• Ricevere aggiornamenti dal server (delta sync)
• Deduplicazione per prevenire duplicati

Ciclo di vita di una modifica

1. Creazione della modifica

Quando esegui un'azione (ad esempio il check-in di un partecipante), SyncEngine:

1. Registra la modifica in IndexedDB con il flag pendingSync=true
2. Assegna un timestamp clientTs (ora corrente del dispositivo)
3. Incrementa il contatore delle modifiche in sospeso nell'indicatore
4. Riflette immediatamente la modifica nell'interfaccia (aggiornamento ottimistico)

2. Invio al server

Con la connessione disponibile, SyncEngine:

1. Estrae tutti i record con pendingSync=true
2. Li ordina per clientTs (dai piu vecchi ai piu recenti)
3. Li invia in batch al server
4. Attende la conferma dal server

3. Conferma

Dopo la risposta positiva del server:

1. Il flag pendingSync viene rimosso (false) per ogni record inviato
2. Il contatore delle modifiche in sospeso diminuisce
3. Se tutte le modifiche sono state inviate, l'indicatore diventa verde

4. Gestione degli errori

In caso di errore nell'invio:

1. Le modifiche rimangono con pendingSync=true
2. Un nuovo tentativo viene eseguito dopo 30 secondi
3. Massimo 5 tentativi, dopodiche viene inviata una notifica all'utente

Delta sync

Il delta sync permette di ricevere dal server solo i dati modificati dopo l'ultima sincronizzazione, invece di scaricare l'intero set di dati.

Come funziona

1. SyncEngine memorizza il timestamp dell'ultima sincronizzazione riuscita nella tabella meta.
2. Durante la sincronizzazione viene inviata una richiesta con il parametro since:

GET /sync/delta?since=2026-07-15T10:30:00Z&entities=registrations,payments

3. Il server restituisce solo i record modificati dopo il tempo indicato.
4. SyncEngine aggiorna il database locale e salva il nuovo timestamp.

Parametri della richiesta

Vantaggi

• Risparmio di traffico. Vengono trasmesse solo le modifiche, non tutti i dati
• Velocita. La sincronizzazione richiede secondi, non minuti
• Affidabilita. Se la sincronizzazione viene interrotta, il tentativo successivo riparte dallo stesso since

Sincronizzazione automatica

SyncEngine monitora lo stato della rete e avvia automaticamente la sincronizzazione nei seguenti casi:

Al ripristino della connessione

Quando il dispositivo passa da offline a online:

1. Viene rilevato l'evento online (Network Information API)
2. SyncEngine verifica la disponibilita del server (ping)
3. Vengono inviate le modifiche in sospeso (upload)
4. Vengono richiesti gli aggiornamenti dal server (download via delta sync)

Sincronizzazione periodica

In modalita online, SyncEngine verifica periodicamente la presenza di aggiornamenti sul server per mantenere i dati aggiornati (ad esempio, se un altro membro del team ha registrato un check-in da un altro dispositivo).

Deduplicazione

Per prevenire la duplicazione delle modifiche viene utilizzata una chiave composita:

clientTs + userId

Ogni modifica e identificata univocamente dalla combinazione del timestamp di creazione sul client e dell'identificatore dell'utente. Se la stessa modifica viene inviata nuovamente (ad esempio a causa di un timeout di rete), il server riconosce il duplicato tramite questa chiave e restituisce la conferma senza riapplicare la modifica.

Questo garantisce l'idempotenza -- l'invio ripetuto dello stesso set di modifiche non causa errori o duplicazione dei dati.

Ordine di sincronizzazione

Le modifiche vengono inviate rigorosamente in ordine cronologico per clientTs. Questo e fondamentale per la correttezza:

• Il check-in di un partecipante alle 10:05 non puo essere sovrascritto dall'annullamento del check-in alle 10:03
• La conferma manuale del pagamento alle 11:00 viene applicata dopo la modifica dello stato alle 10:55

Se l'orologio del dispositivo differisce dall'ora del server, SyncEngine compensa la differenza alla prima sincronizzazione riuscita.

Capacita dell'archivio locale

Il database locale IndexedDB ha limitazioni che dipendono dal browser e dal dispositivo:

Per un evento tipico (fino a 2.000 partecipanti) il volume dei dati e di 5-20 MB, ben al di sotto dei limiti di qualsiasi browser.

Quando ci si avvicina al limite di archiviazione, SyncEngine mostra un avviso e propone di cancellare i dati degli eventi conclusi.