# 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`](docs/openapi.yaml) ·
brief: [`docs/MOBILE_APP_BRIEF.md`](docs/MOBILE_APP_BRIEF.md) ·
protocolo de sync: [`docs/MOBILE_SYNC_PROTOCOL.md`](docs/MOBILE_SYNC_PROTOCOL.md).

## Arranque

```bash
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`](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.