avante-movil/README.md

# 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 (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.

```bash
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`](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](https://docs.expo.dev/build/introduction/) (nube de Expo, no necesita Mac):

```bash
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`](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`](app.config.js) — **no se commitea**:

```bash
# 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.

## Estado de implementación

Todas las funcionalidades están implementadas y el typecheck pasa limpio (`npm run typecheck`).

| Área | Estado |
|------|--------|
| Auto-sync (red/primer plano/intervalo 60s) | ✓ `src/sync/useAutoSync.ts` |
| Reconciliación de creaciones offline (temp-id → server_id, remap FKs) | ✓ `src/sync/engine.ts` |
| Captura de fotos (cámara/galería) + cola offline | ✓ `src/ui/MediaStrip.tsx` |
| Mapa GeoJSON de features (react-native-maps) | ✓ `src/ui/FeatureMap.tsx` + `src/ui/geojson.ts` |
| Formulario de inspección dinámico desde plantilla | ✓ `src/screens/InspectionFormScreen.tsx` |
| Detalle de incidencia (checklist + comentarios + fotos) | ✓ `src/screens/detail/IssueDetailContent.tsx` |
| Resolución de conflictos en UI (Outbox) | ✓ `src/screens/OutboxScreen.tsx` |
| Maestro-detalle adaptativo (tablet 2 paneles / móvil navegación) | ✓ `src/ui/MasterDetail.tsx` |

## Pendiente (próximas tandas)

- **Google Maps API key**: el mapa dibuja la geometría offline, pero los tiles base requieren
  una key. Configurar con `GOOGLE_MAPS_API_KEY` (ver sección Mapa arriba).
- **Test en dispositivo real**: ejecutar `npx expo run:android` o distribuir el APK
  con `eas build -p android --profile preview` (ver sección Arranque).
- **Sincronización en segundo plano con app cerrada** (requiere `expo-task-manager` +
  `expo-background-fetch`): actualmente solo sincroniza con la app en primer plano.
- **Push notifications** para alertas de nuevas incidencias o comentarios.