Cómo funciona la sincronización

SyncEngine

SyncEngine es el componente central de la arquitectura offline de tikento. Se encarga de:

• Guardar los cambios en la base de datos local (IndexedDB mediante Dexie.js)
• Rastrear los cambios pendientes de sincronización (pendingSync=true)
• Enviar los cambios al servidor cuando se restablece la conexión
• Recibir actualizaciones del servidor (delta sync)
• Deduplicación para prevenir duplicados

Ciclo de vida de un cambio

1. Creación del cambio

Cuando realizas una acción (por ejemplo, check-in de un participante), SyncEngine:

1. Registra el cambio en IndexedDB con la marca pendingSync=true
2. Asigna una marca de tiempo clientTs (hora actual del dispositivo)
3. Incrementa el contador de cambios pendientes en el indicador
4. Refleja el cambio inmediatamente en la interfaz (actualización optimista)

2. Envío al servidor

Con conexión disponible, SyncEngine:

1. Extrae todos los registros con pendingSync=true
2. Los ordena por clientTs (de más antiguo a más reciente)
3. Los envía en lote al servidor
4. Espera la confirmación del servidor

3. Confirmación

Tras la respuesta exitosa del servidor:

1. La marca pendingSync se elimina (false) para cada registro enviado
2. El contador de cambios pendientes disminuye
3. Si todos los cambios se han enviado, el indicador cambia a verde

4. Manejo de errores

Si hay un error en el envío:

1. Los cambios permanecen con pendingSync=true
2. Se realiza un nuevo intento a los 30 segundos
3. Máximo 5 intentos; después, se notifica al usuario

Delta sync

Delta sync permite recibir del servidor solo los datos que han cambiado desde la última sincronización, en lugar de descargar todo el conjunto de datos.

Cómo funciona

1. SyncEngine almacena la marca de tiempo de la última sincronización exitosa en la tabla meta.
2. Durante la sincronización, se envía una solicitud con el parámetro since:

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

3. El servidor devuelve solo los registros modificados después del tiempo indicado.
4. SyncEngine actualiza la base de datos local y guarda la nueva marca de tiempo.

Parámetros de la solicitud

Ventajas

• Ahorro de tráfico. Solo se transmiten los cambios, no todos los datos
• Rapidez. La sincronización tarda segundos, no minutos
• Fiabilidad. Si la sincronización se interrumpe, el siguiente intento comenzará desde el mismo since

Sincronización automática

SyncEngine monitoriza el estado de la red e inicia automáticamente la sincronización en los siguientes casos:

Al restablecerse la conexión

Cuando el dispositivo pasa de offline a online:

1. Se detecta el evento online (Network Information API)
2. SyncEngine verifica la disponibilidad del servidor (ping)
3. Se envían los cambios pendientes (upload)
4. Se solicitan actualizaciones del servidor (download via delta sync)

Sincronización periódica

En modo online, SyncEngine verifica periódicamente la existencia de actualizaciones en el servidor para mantener los datos actualizados (por ejemplo, si otro miembro del equipo ha marcado un check-in desde otro dispositivo).

Deduplicación

Para prevenir la duplicación de cambios se utiliza una clave compuesta:

clientTs + userId

Cada cambio se identifica de forma única mediante la combinación de la marca de tiempo de creación en el cliente y el identificador del usuario. Si un mismo cambio se envía de nuevo (por ejemplo, por un timeout de red), el servidor reconoce el duplicado por esta clave y devuelve una confirmación sin aplicarlo de nuevo.

Esto garantiza la idempotencia: el reenvío del mismo conjunto de cambios no produce errores ni duplicación de datos.

Orden de sincronización

Los cambios se envían estrictamente en orden cronológico por clientTs. Esto es crítico para la corrección:

• El check-in de un participante a las 10:05 no puede ser sobrescrito por una cancelación de check-in a las 10:03
• El marcado manual de pago a las 11:00 se aplica después del cambio de estado a las 10:55

Si el reloj del dispositivo difiere de la hora del servidor, SyncEngine compensa la diferencia en la primera sincronización exitosa.

Volumen de almacenamiento local

La base de datos local IndexedDB tiene limitaciones que dependen del navegador y el dispositivo:

Para un evento típico (hasta 2 000 participantes), el volumen de datos es de 5-20 MB, muy lejos de los límites de cualquier navegador.

Cuando se acerca al límite de almacenamiento, SyncEngine muestra una advertencia y sugiere limpiar los datos de eventos finalizados.