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 (Android)

La app usa módulos nativos (expo-sqlite, expo-secure-store, react-native-maps) que no funcionan en Expo Go: hay que usar un development build o un APK.

npm install
npm run typecheck          # comprobación de tipos

# Development build (emulador o dispositivo con depuración USB):
npx expo run:android       # compila e instala un dev client con hot reload

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.

APK para repartir (sideload)

Con EAS Build (nube de Expo, no necesita Mac):

npm i -g eas-cli           # una vez
eas login                  # cuenta Expo
eas build -p android --profile preview   # genera un .apk (distribution: internal)

Al terminar, EAS da un enlace de descarga del .apk; instálalo en el dispositivo (habilitando "orígenes desconocidos"). Perfiles en eas.json: development (dev client), preview (APK interno), production (AAB, para Play más adelante).

Mapa (Google Maps)

La sección Features incluye un mapa (react-native-maps) que dibuja la geometría GeoJSON. Requiere una API key de Google Maps (Android), que se inyecta vía variable de entorno GOOGLE_MAPS_API_KEY en app.config.js — no se commitea:

# local
export GOOGLE_MAPS_API_KEY=AIza...   # (PowerShell: $env:GOOGLE_MAPS_API_KEY="AIza...")
npx expo run:android

# EAS: guárdala como secreto
eas secret:create --name GOOGLE_MAPS_API_KEY --value AIza...

Sin key, la app funciona pero el mapa no carga tiles (la lista de features sí). Las tiles necesitan conexión; la geometría se dibuja también sin red.

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.