Referencia: Aplicación de campo offline-first

Una referencia compuesta para operaciones de campo offline-first - inspecciones de servicios, auditorías de almacén o encuestas de activos municipales. Los técnicos capturan fotos, coordenadas GPS y respuestas de listas de verificación sin conectividad confiable. Stack: Expo SDK 57 (expo ~57.0.4), React Native 0.86.0, React 19.2.3.

Contexto

Realidad operativa:

• El 40% del trabajo ocurre en sótanos, subestaciones y sitios rurales con sin señal durante horas.
• Perder una inspección completada porque la aplicación falló antes de sincronizarse es un fallo de contrato, no una molestia UX.
• Los dispositivos son Android robusto (Zebra TC57, Honeywell CT40) más una minoría de iPhones corporativos.
• El backend acepta cargas por lotes REST; la política de conflictos es autorizada por servidor en timestamps de aprobación.

Restricciones del equipo: Cuatro ingenieros móviles, un ingeniero backend, sin especialista nativo on-call. Flujo de trabajo administrado por Expo con distribución interna EAS a dispositivos de flota.

Arquitectura

┌──────────────────────────────────────────────────────────────────────────┐
│                    Aplicación de campo - plano de datos offline-first     │
├──────────────────────────────────────────────────────────────────────────┤
│  Expo Router                                                             │
│    (app)/jobs/[jobId]/inspection/[id]   ← enlace profundo desde SMS      │
├──────────────────────────────────────────────────────────────────────────┤
│  Capa UI                                                                 │
│    DataFreshnessLabel (live|stale|syncing|unavailable)                   │
│    Guardado optimista → SQLite inmediatamente                            │
├──────────────────────────────────────────────────────────────────────────┤
│  expo-sqlite (fuente de verdad)                                          │
│    inspections, answers, attachments_meta                                │
│    outbox (cola de mutaciones, idempotency_key, payload_json)            │
│    sync_cursor (last_server_seq)                                         │
├──────────────────────────────────────────────────────────────────────────┤
│  TanStack Query                                                          │
│    lista de trabajos / datos de referencia - stale-while-revalidate      │
├──────────────────────────────────────────────────────────────────────────┤
│  NetInfo → onlineManager + vaciado en primer plano                       │
│  expo-background-task → drenaje de outbox diferido (intervalo ≥15 min)   │
├──────────────────────────────────────────────────────────────────────────┤
│  expo-file-system + expo-image                                           │
│    archivos adjuntos en disco; cargar en worker en segundo plano         │
└──────────────────────────────────────────────────────────────────────────┘

Ruta de escritura (creación offline):

Usuario toca Guardar → SQLite INSERT (synced=0) → outbox INSERT
  → UI muestra "Carga pendiente" → (más tarde) NetInfo online
  → flushOutbox() → POST /inspections + Idempotency-Key
  → server ack → UPDATE synced=1, elimina fila outbox

Ruta de sincronización (red de seguridad en segundo plano):

OS programa BACKGROUND_SYNC_TASK
  → abrir SQLite → flushOutbox (máx 50 filas, 25 MB adjuntos)
  → retorna Success | Failed

La puerta de arranque en _layout.tsx raíz ejecuta migraciones de PRAGMA user_version antes de que cualquier pantalla lea tablas - ver expo-sqlite.

Relacionado: Offline-First Basics - suposiciones de conectividad y contrato UX

Receta

Tarjeta de referencia rápida de stack para captura de campo en SDK 57.

npx create-expo-app@latest FieldInspect --template default@sdk-57
npx expo install expo-sqlite expo-background-task expo-task-manager \
  @react-native-community/netinfo @tanstack/react-query expo-file-system expo-image

// src/sync/outboxFlush.ts (extracto)
export async function flushOutbox(db: SQLiteDatabase) {
  const rows = await db.getAllAsync<OutboxRow>(
    `SELECT * FROM outbox ORDER BY created_at LIMIT 50`
  );
  for (const row of rows) {
    const res = await api.post("/inspections", row.payload_json, {
      headers: { "Idempotency-Key": row.idempotency_key },
    });
    if (res.ok) await markSynced(db, row.id);
  }
}

// index.ts - registrar tarea en segundo plano en scope global
import "./src/background/syncTask";
import "expo-router/entry";

Laboratorio de dispositivos mínimo: Un Android robusto en Android 11+, un iPhone de dos generaciones anteriores al actual, ambos en compilaciones release - no Expo Go.

Decisiones tomadas

Alternativas rechazadas:

• CRDT para respuestas de lista de verificación - el backend no tenía motor de fusión; autorizado por servidor más simple para cumplimiento.
• Sincronización en segundo plano como única ruta - intervalo mínimo de 15 minutos perdió plazo de despacho; vaciado en primer plano obligatorio.
• Outbox AsyncStorage - 200+ elementos pendientes después de interrupción de varios días superó tamaño JSON cómodo.

Resultados

Flota piloto: 120 dispositivos robustos en Android 11-14, compilación SDK 57 1.6.0.

Recuperación de corrupción: un dispositivo con OTA fallida a mitad de la migración activó cuarentena safeParse - la aplicación renderizó inspecciones última-conocida-buena sin pantalla blanca por Data Layer Best Practices #13.

Lecciones

1. Migraciones SQLite antes de primer renderizado. Un bump de user_version enviado en una OTA sin compilación de almacén rompió arranque en frío una vez - ahora los cambios de schema nativo requieren bump binario.

2. Mostrar estado pendiente por fila, no spinner global. Los inspectores trabajan en trabajo B mientras trabajo A se carga; el indicador synced por fila superó un modal de bloqueo.

3. Los dispositivos robustos mienten sobre batería. BatterySaver en Zebra retrasó tareas en segundo plano; documenta que el vaciado en primer plano es la ruta de entrega real.

4. Las cargas de fotos necesitan progreso de bytes. Carga de expo-file-system con onUploadProgress redujo llamadas "¿se guardó?" a despacho.

5. Cierre de sesión limpia todas las capas. Caché de inspección obsoleta en dispositivos compartidos fue una clase de incidente de privacidad - queryClient.clear() + tablas de usuario SQLite + directorios de adjuntos.

6. Fijar SDK 57 en runbooks. TI de campo instala APKs meses después; documentos de soporte deben indicar qué runtimeVersion acepta qué OTA.

Relacionado

• Offline-First Basics - contrato UX y NetInfo
• expo-sqlite - WAL, migraciones, transacciones
• Sync Strategies - reconciliación del servidor
• Optimistic UI - patrones de reversión
• Background Sync & TaskManager - vaciado diferido
• expo-image - miniaturas de adjuntos y caché
• Network Failure UX - banners y copia de reintentos
• Internal Distribution - entrega de APK de flota

Versiones de stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0, y Expo SDK 57 (expo ~57.0.4).