Avante Móvil

App de seguimiento de obra offline-first para ConstruProgress (React Native + Expo). Descarga un proyecto, permite trabajar sin conexión (progreso, inspecciones, incidencias con tareas/comentarios/fotos) y sincroniza al recuperar red.

Contrato de la API: docs/openapi.yaml · brief: docs/MOBILE_APP_BRIEF.md · protocolo de sync: docs/MOBILE_SYNC_PROTOCOL.md.

Arranque

npm install
npm start          # abre Expo; pulsa 'a' (Android) / 'i' (iOS) / 'w' (web)
npm run typecheck  # comprobación de tipos

Backend local (XAMPP): ajusta BASE_URL en src/config.ts. Desde emulador Android usa http://10.0.2.2/...; desde dispositivo físico, la IP LAN del PC. localhost apunta al propio teléfono, no al PC.

Arquitectura

App.tsx                  Providers (SafeArea, Session) + apertura de la BD
src/
  config.ts              BASE_URL, versión de app, nombre de BD
  api/
    types.ts             Tipos del contrato (DTOs)
    client.ts            fetch + Bearer token + X-App-Version + manejo de 401
    endpoints.ts         Los 8 endpoints tipados
  db/
    schema.ts            DDL: entidades del bundle + outbox + media_outbox + meta
    database.ts          Apertura/migración (singleton) + wipe
    repositories.ts      applyBundle (upsert + tombstones + cursor), lecturas UI
    outbox.ts            Cola de salida de operaciones y de ficheros
  sync/
    uuid.ts              UUID v4 (idempotencia) + timestamp de cliente
    engine.ts            runSync = PUSH /sync → PUSH /media → PULL bundle?since
    mutations.ts         API de alto nivel: write local optimista + encolar
  net/connectivity.ts    Estado de red (NetInfo)
  auth/session.tsx       Token en SecureStore + contexto de sesión
  navigation/            Stack: Login → Proyectos → Detalle
  screens/, components/  UI mínima (login, lista, detalle, barra de estado)

Modelo de sincronización (resumen)

• PULL: GET /projects/{id}/bundle?since=<cursor>. El cursor es el server_time guardado en meta. applyBundle hace upsert de cada entidad, borra los deleted (tombstones) y avanza el cursor — todo en una transacción.
• Trabajo offline: las funciones de sync/mutations.ts escriben en local (optimista) y encolan una operación en outbox con un uuid propio (clave de idempotencia).
• PUSH: runSync envía el outbox a POST /sync por lotes y procesa el resultado por operación: applied/duplicate → sent; conflict → vuelca el valor del servidor a la BD local (last-write-wins servidor) y marca la op para revisión; error → guarda el motivo.
• Media: los ficheros pendientes (media_outbox) se suben a POST /media (multipart), también idempotentes por uuid.

El servidor SIEMPRE fija user_id/reported_by/project_id y valida permisos: el cliente nunca los envía.

Pendiente (siguientes tandas)

• Sincronización en segundo plano / al recuperar conexión (hoy es manual con el botón).
• Reconciliación de creaciones offline (mapear filas locales temporales al server_id).
• Captura de fotos (expo-image-picker) e integración con enqueueMedia.
• Pantallas ricas: mapa/GeoJSON de features, formulario de inspección desde plantilla, detalle de incidencia con checklist + comentarios + fotos.
• Resolución de conflictos en UI.