# US-MAI006-020: Tomar Fotos con Evidencia GPS Offline

**Modulo:** MAI-006-tracking
**Version:** 1.0.0
**Fecha:** 2026-01-27
**Story Points:** 5
**Prioridad:** MEDIA

---

## Descripcion

**Como** conductor,
**Quiero** tomar fotos de evidencia (carga, sellos, danos, entrega) que incluyan automaticamente informacion GPS y timestamp,
**Para** documentar visualmente el estado de la mercancia y tener evidencia con ubicacion y fecha verificables, incluso sin conexion.

---

## Actor Principal

**Operador / Conductor**

---

## Precondiciones

1. El conductor tiene un viaje activo
2. El dispositivo tiene camara funcional
3. Hay suficiente almacenamiento local (>100 MB)
4. Los permisos de camara y ubicacion estan otorgados

---

## Criterios de Aceptacion

### CA-1: Captura de foto sin conexion

**Given** el conductor esta sin conexion a internet
**And** necesita documentar evidencia
**When** abre la camara desde la app
**Then** puede tomar fotos normalmente
**And** las fotos se guardan localmente
**And** se muestran en la galeria de evidencias del viaje

### CA-2: Metadata GPS automatica

**Given** el conductor toma una foto
**And** el GPS del dispositivo esta activo
**When** la foto se guarda
**Then** se captura automaticamente:
  - Latitud y longitud
  - Precision del GPS (en metros)
  - Altitud (si disponible)
  - Rumbo/Heading (si disponible)
**And** esta informacion se almacena junto con la foto

### CA-3: Timestamp inmutable

**Given** el conductor toma una foto
**When** la foto se procesa
**Then** se registra:
  - Fecha y hora del dispositivo
  - Timezone del dispositivo
  - Timestamp en formato UTC
**And** el timestamp no puede ser modificado posteriormente

### CA-4: Categorizacion de fotos

**Given** el conductor toma una foto
**When** guarda la foto
**Then** debe seleccionar una categoria:
  - Carga (estado de mercancia al cargar)
  - Descarga (estado de mercancia al descargar)
  - Sello (numero de sello)
  - Dano (evidencia de dano)
  - Incidencia (accidente, obstruccion, etc.)
  - Documentos (remision, guia, etc.)
  - Otro (especificar)

### CA-5: Notas opcionales en foto

**Given** el conductor ha tomado una foto
**When** la esta guardando
**Then** puede agregar notas de texto (opcional)
  - Maximo 500 caracteres
  - Descripcion de lo que muestra la foto
  - Numero de sello si aplica

### CA-6: Compresion automatica

**Given** el conductor toma una foto de alta resolucion
**When** la foto se procesa para almacenamiento
**Then** se comprime automaticamente:
  - Resolucion maxima: 1920x1080
  - Calidad: 80%
  - Formato: JPEG
  - Tamano objetivo: <500 KB
**And** se preserva la foto original si hay espacio

### CA-7: Limite de fotos por viaje

**Given** el conductor ha tomado multiples fotos
**When** alcanza el limite de 50 fotos por viaje
**Then** la app muestra alerta "Limite de fotos alcanzado"
**And** sugiere sincronizar para liberar espacio
**And** no permite tomar mas fotos hasta sincronizar o eliminar

### CA-8: Visualizacion de galeria offline

**Given** el conductor quiere revisar fotos tomadas
**When** accede a la galeria de evidencias
**Then** ve todas las fotos del viaje actual
**And** puede ver la metadata de cada foto (GPS, fecha, categoria)
**And** puede eliminar fotos no sincronizadas
**And** no puede eliminar fotos ya sincronizadas

---

## Flujo Principal

1. Conductor selecciona "Tomar foto" o abre camara
2. Sistema verifica permisos de camara y GPS
3. Conductor encuadra y toma foto
4. Sistema captura metadata (GPS, timestamp)
5. Conductor selecciona categoria de foto
6. Conductor agrega notas (opcional)
7. Sistema comprime foto
8. Sistema guarda foto localmente
9. Sistema actualiza galeria y contador de pendientes

---

## Flujo Alternativo: GPS No Disponible

1. Conductor toma foto
2. Sistema detecta que GPS no esta disponible
3. Sistema muestra advertencia "Foto sin ubicacion GPS"
4. Sistema permite guardar con metadata parcial
5. Sistema marca foto como "SIN_GPS"
6. Foto se sincroniza normalmente pero sin coordenadas

---

## Flujo Alternativo: Almacenamiento Lleno

1. Conductor intenta tomar foto
2. Sistema detecta almacenamiento < 50 MB
3. Sistema muestra alerta "Almacenamiento casi lleno"
4. Sistema sugiere:
   - Sincronizar fotos pendientes
   - Eliminar fotos innecesarias
5. Si almacenamiento < 10 MB: bloquea captura

---

## Wireframe ASCII de Pantalla de Camara

```
+----------------------------------------------------------+
|  < Volver              CAPTURAR EVIDENCIA                |
+----------------------------------------------------------+
|                                                          |
|  +----------------------------------------------------+  |
|  |                                                    |  |
|  |                                                    |  |
|  |                                                    |  |
|  |                                                    |  |
|  |              [VISTA PREVIA CAMARA]                 |  |
|  |                                                    |  |
|  |                                                    |  |
|  |                                                    |  |
|  |                                                    |  |
|  +----------------------------------------------------+  |
|                                                          |
|  GPS: 25.6866, -100.3161 (5m)  |  27/01/2026 14:35     |
|                                                          |
+----------------------------------------------------------+
|                                                          |
|          [GALERIA]    ( O )    [FLASH]                  |
|                       CAPTURAR                          |
|                                                          |
+----------------------------------------------------------+
```

### Post-Captura

```
+----------------------------------------------------------+
|  < Retomar             GUARDAR FOTO                      |
+----------------------------------------------------------+
|                                                          |
|  +----------------------------------------------------+  |
|  |                                                    |  |
|  |              [PREVIEW DE FOTO]                     |  |
|  |                                                    |  |
|  +----------------------------------------------------+  |
|                                                          |
|  Ubicacion: 25.6866, -100.3161                          |
|  Fecha: 27/01/2026 14:35:22                             |
|  Tamano: 342 KB                                          |
|                                                          |
+----------------------------------------------------------+
|  Categoria: *                                            |
|  +----------------------------------------------------+  |
|  |  [v] Seleccionar categoria...                      |  |
|  +----------------------------------------------------+  |
|  | ( ) Carga                                          |  |
|  | ( ) Descarga                                       |  |
|  | (o) Sello                                          |  |
|  | ( ) Dano                                           |  |
|  | ( ) Incidencia                                     |  |
|  | ( ) Documentos                                     |  |
|  | ( ) Otro                                           |  |
|  +----------------------------------------------------+  |
|                                                          |
|  Notas: (opcional)                                       |
|  +----------------------------------------------------+  |
|  | Sello #ABC12345                                    |  |
|  +----------------------------------------------------+  |
|                                                          |
+----------------------------------------------------------+
|                                                          |
|  [  DESCARTAR  ]    [======= GUARDAR =======]           |
|                                                          |
+----------------------------------------------------------+
```

---

## Notas Tecnicas

### Tecnologias Involucradas

| Componente | Tecnologia | Proposito |
|------------|------------|-----------|
| Camara | expo-camera / react-native-camera | Captura de imagen |
| GPS | expo-location | Coordenadas |
| Compresion | react-native-image-resizer | Reducir tamano |
| Storage | IndexedDB | Almacenar blobs |
| EXIF | piexifjs | Metadata de imagen |

### Estructura de Foto Local

```typescript
interface FotoEvidencia {
  id: string;                    // UUID generado localmente
  viajeId: string;               // ID del viaje
  paradaId: string | null;       // ID de la parada (si aplica)
  eventoId: string | null;       // ID del evento relacionado

  // Datos de la foto
  filename: string;              // nombre_uuid.jpg
  mimeType: string;              // image/jpeg
  sizeBytes: number;             // Tamano en bytes
  width: number;                 // Ancho en pixeles
  height: number;                // Alto en pixeles

  // Categoria y descripcion
  categoria: CategoriaFoto;
  notas: string | null;

  // Metadata GPS
  lat: number | null;
  lng: number | null;
  altitude: number | null;
  gpsAccuracy: number | null;
  heading: number | null;
  hasGPS: boolean;

  // Metadata temporal
  capturedAt: Date;
  timezone: string;

  // Referencias
  operadorId: string;
  dispositivoId: string;

  // Estado de sync
  syncStatus: 'PENDING' | 'UPLOADING' | 'SENT' | 'FAILED';
  syncProgress: number;          // 0-100 para uploads grandes
  syncAttempts: number;
  lastSyncError: string | null;

  // Timestamps
  createdAt: Date;
  updatedAt: Date;
  syncedAt: Date | null;
}

type CategoriaFoto =
  | 'CARGA'
  | 'DESCARGA'
  | 'SELLO'
  | 'DANO'
  | 'INCIDENCIA'
  | 'DOCUMENTOS'
  | 'OTRO';
```

### Configuracion de Compresion

```typescript
const PHOTO_CONFIG = {
  maxWidth: 1920,
  maxHeight: 1080,
  quality: 80,
  format: 'JPEG',
  rotation: 0,  // Auto-corregir orientacion

  // Limites
  maxSizeKB: 500,
  maxPhotosPerTrip: 50,
  maxStorageMB: 200,

  // Categorias que requieren mayor calidad
  highQualityCategories: ['DANO', 'DOCUMENTOS', 'SELLO']
};
```

### Estrategia de Upload

```typescript
// Fotos se suben con prioridad BAJA despues de eventos y firmas
// Upload en chunks para conexiones lentas
const UPLOAD_CONFIG = {
  chunkSize: 256 * 1024,  // 256 KB chunks
  maxConcurrent: 2,       // 2 uploads simultaneos
  retryAttempts: 5,
  retryDelay: 30000,      // 30 segundos entre reintentos

  // Si la foto es >1MB, usar upload resumable
  resumableThreshold: 1024 * 1024
};
```

---

## Dependencias

| Dependencia | Tipo | Descripcion |
|-------------|------|-------------|
| US-MAI006-016 | Funcional | Operar sin conexion |
| US-MAI006-017 | Funcional | Sincronizar al reconectar |
| US-MAI005-003 | Funcional | Evidencias de carga |
| US-MAI008-003 | Funcional | Evidencias de incidencia |
| expo-camera | Tecnica | Libreria de camara |
| expo-location | Tecnica | Libreria de GPS |

---

## Consideraciones de Privacidad

| Aspecto | Implementacion |
|---------|----------------|
| Metadata | Solo ubicacion y tiempo, no datos personales |
| Rostros | No se requiere blur automatico (fotos de mercancia) |
| Retencion | Fotos se eliminan del dispositivo post-sync |
| Acceso | Solo el conductor y admins pueden ver fotos |

---

## Riesgos y Mitigaciones

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Fotos muy grandes | Media | Medio | Compresion automatica |
| GPS impreciso | Alta | Bajo | Mostrar precision, permitir sin GPS |
| Almacenamiento lleno | Media | Alto | Alertas proactivas, limites |
| Camara no funciona | Baja | Alto | Mensaje de error claro |
| Foto borrosa | Media | Bajo | Preview antes de guardar |

---

## Definition of Done

- [ ] Captura de foto funciona sin conexion
- [ ] Metadata GPS se captura automaticamente
- [ ] Timestamp inmutable implementado
- [ ] Categorias de foto funcionan
- [ ] Notas opcionales implementadas
- [ ] Compresion automatica configurada
- [ ] Limite de 50 fotos por viaje
- [ ] Galeria offline funciona
- [ ] Upload con progreso visible
- [ ] Pruebas con fotos de diferentes tamanos
- [ ] Pruebas en condiciones de baja senal GPS

---

*US-MAI006-020 v1.0.0 - erp-transportistas - Sistema SIMCO v4.0.0*