6ed7f9e2ec
- Updated docs and inventory files - Added new architecture docs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
244 lines
7.0 KiB
Markdown
244 lines
7.0 KiB
Markdown
# 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
|
|
|
|
```typescript
|
|
// 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*
|