javierandClaude Opus 4.8
9bcc51e3b2
Fase 0: config Android (package, permisos, orientación), eas.json (APK), deps nativas (react-native-maps, image-picker, location), app.config.js para la key de Google Maps por secreto EAS. Fase 1: capa responsive (useLayout) + componente MasterDetail (dos paneles en tablet, navegación en móvil). Fase 2: pantallas funcionales — detalle de proyecto con secciones Fases/Features/ Incidencias, edición de progreso/estado, formulario de inspección dinámico desde plantilla, incidencias maestro-detalle (checklist + comentarios), alta de incidencia; gating por permisos Spatie. Fase 3: fotos (cámara/galería) → cola de media, con miniaturas pendientes/sync. Fase 4: mapa de features (Google Maps) con geometría GeoJSON y selección. Fase 5: auto-sync (foreground/reconexión/intervalo, con candado) + reconciliación de creaciones offline (id temporal negativo → server_id, remapeo de FKs hijas). Fase 6: revisión de conflictos/errores del outbox, indicadores y APK preview. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
109 lines
4.8 KiB
Markdown
109 lines
4.8 KiB
Markdown
# 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.
|
|
|
|
## 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.
|