erp-transportistas-v2/docs/02-definicion-modulos/MAI-006-tracking/historias-usuario/US-MAI006-017-sincronizar-al-reconectar.md

US-MAI006-017: Sincronizar al Reconectar

Modulo: MAI-006-tracking Version: 1.0.0 Fecha: 2026-01-27 Story Points: 5 Prioridad: ALTA

---

Descripcion

Como sistema de la app de conductores, Quiero enviar automaticamente todos los datos pendientes cuando se recupera la conexion, Para garantizar que la informacion operativa llegue al servidor sin intervencion del conductor y sin perdida de datos.

---

Actor Principal

Sistema (App Movil)

Actor Secundario: Operador / Conductor (observador)

---

Precondiciones

1. Existen eventos/datos pendientes de sincronizar en el dispositivo
2. La conexion a internet se ha restablecido
3. El token de autenticacion es valido (no expirado)
4. El servidor backend esta disponible

---

Criterios de Aceptacion

CA-1: Deteccion automatica de conexion

Given el dispositivo estaba sin conexion When la conexion a internet se restablece Then el sistema detecta el cambio en menos de 5 segundos And cambia el indicador de "Offline" a "Sincronizando" And inicia el proceso de sincronizacion automaticamente

CA-2: Priorizacion de datos a enviar

Given hay multiples tipos de datos pendientes When inicia la sincronizacion Then el sistema envia los datos en el siguiente orden de prioridad:

1. Firmas POD (prioridad critica)
2. Eventos de viaje (prioridad alta)
3. Respuestas de checklist (prioridad alta)
4. Posiciones GPS (prioridad media)
5. Fotos de evidencia (prioridad baja)

CA-3: Procesamiento por lotes (batching)

Given hay 50 eventos pendientes de sincronizar When el sistema envia los eventos Then los agrupa en lotes de maximo 50 eventos por request And envia un lote a la vez And espera confirmacion antes de enviar el siguiente And marca los eventos enviados como "SENT"

CA-4: Manejo de errores con retry automatico

Given un lote de datos falla al enviarse (error de red o servidor) When el sistema detecta el error Then espera un tiempo con exponential backoff antes de reintentar

• Intento 1: Inmediato
• Intento 2: 1 segundo
• Intento 3: 2 segundos
• Intento 4: 4 segundos
• Hasta maximo 60 segundos And muestra contador de reintentos al usuario si >3 intentos

CA-5: Notificacion de sincronizacion completada

Given todos los datos pendientes fueron enviados exitosamente When el servidor confirma la recepcion Then el sistema muestra toast "Sincronizacion completada" And actualiza el contador de pendientes a 0 And cambia indicador a "Online" (verde) And registra timestamp de ultima sincronizacion

CA-6: Sincronizacion en background

Given la app esta en segundo plano (background) And hay datos pendientes When el dispositivo tiene conexion Then el sistema intenta sincronizar usando Background Sync API And muestra notificacion push al completar "X eventos sincronizados"

CA-7: Pull de cambios del servidor

Given el push de datos locales se completo exitosamente When el sistema inicia el pull de cambios Then solicita al servidor cambios desde el ultimo sync_timestamp And aplica cambios a los datos locales (viaje, instrucciones, paradas) And notifica al usuario si hay cambios relevantes And actualiza la UI reactivamente

---

Flujo Principal

1. Sistema detecta conexion restablecida
2. Sistema verifica token de autenticacion
3. Sistema obtiene items pendientes de la cola
4. Sistema ordena items por prioridad
5. Sistema envia primer batch al servidor
6. Servidor responde con confirmacion
7. Sistema marca items como enviados
8. Sistema repite hasta vaciar cola
9. Sistema solicita pull de cambios del servidor
10. Sistema aplica cambios locales
11. Sistema notifica al usuario
12. Sistema actualiza UI (indicadores, contadores)

---

Flujo Alternativo: Error de Autenticacion (401)

1. Sistema intenta enviar batch
2. Servidor responde 401 Unauthorized
3. Sistema intenta refresh token
4. Si refresh exitoso: continua sync
5. Si refresh falla: notifica usuario "Sesion expirada"
6. Pausar sync hasta re-autenticacion

---

Flujo Alternativo: Error de Servidor (5xx)

1. Sistema intenta enviar batch
2. Servidor responde error 5xx
3. Sistema registra error en log
4. Sistema espera con exponential backoff
5. Sistema reintenta automaticamente
6. Si >8 intentos: mover a dead letter queue
7. Notificar usuario si items criticos en dead letter

---

Notas Tecnicas

Tecnologias Involucradas

Componente	Tecnologia	Proposito
Sync Manager	Custom Service	Orquestar sincronizacion
Queue	WatermelonDB	Cola de items pendientes
Background Sync	Workbox	Sync en background
Network	NetInfo API	Detectar conexion
Retry	Custom	Exponential backoff

Endpoints de Backend

Metodo	Endpoint	Descripcion
POST	/api/sync/events	Batch de eventos
POST	/api/sync/positions	Batch de posiciones GPS
POST	/api/sync/photos	Upload de fotos
POST	/api/sync/signatures	Upload de firmas
GET	/api/sync/pull	Delta sync desde timestamp

Formato de Request

// POST /api/sync/events
interface SyncEventsRequest {
  items: Array<{
    localId: string;
    tipo: string;
    timestamp: string;
    lat: number | null;
    lng: number | null;
    viajeId: string;
    data: Record<string, unknown>;
  }>;
}

// Response
interface SyncEventsResponse {
  accepted: string[];  // IDs aceptados
  rejected: Array<{
    localId: string;
    reason: string;
  }>;
  serverTimestamp: string;
}

Metricas a Capturar

Metrica	Descripcion
sync_duration_ms	Tiempo total de sincronizacion
sync_items_count	Cantidad de items sincronizados
sync_retry_count	Numero de reintentos
sync_error_rate	Porcentaje de errores

---

Dependencias

Dependencia	Tipo	Descripcion
US-MAI006-016	Funcional	Operar sin conexion
US-MAI006-018	Funcional	Ver estado de sincronizacion
SINCRONIZACION-OFFLINE.md	Documento	Detalles de implementacion

---

Riesgos y Mitigaciones

Riesgo	Probabilidad	Impacto	Mitigacion
Conexion inestable durante sync	Alta	Medio	Transacciones atomicas, retry
Servidor no disponible	Media	Alto	Dead letter queue, alertas
Conflictos de datos	Baja	Medio	Estrategias de conflict resolution
Bateria baja durante sync	Baja	Medio	Pausar si bateria <15%

---

Definition of Done

• Sync automatico al recuperar conexion
• Priorizacion de datos implementada
• Batching configurado correctamente
• Exponential backoff funcionando
• Dead letter queue implementada
• Background sync funcionando
• Pull de cambios implementado
• Notificaciones de estado correctas
• Metricas capturadas
• Pruebas de integracion completadas
• Pruebas de stress (1000+ items) pasadas

---

US-MAI006-017 v1.0.0 - erp-transportistas - Sistema SIMCO v4.0.0