miinventario-v2/docs/01-epicas/MII-004-captura-video.md

# MII-004: Captura de Video

---
id: MII-004
type: Epic
status: Completado
priority: P0
phase: 1
story_points: 21
created_date: 2026-01-10
updated_date: 2026-01-13
simco_version: "4.0.0"
---

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | MII-004 |
| **Nombre** | Captura de Video |
| **Fase** | 1 - MVP Core |
| **Prioridad** | P0 |
| **Story Points** | 21 |
| **Estado** | Completado |

---

## 1. Descripcion

Implementar la captura guiada de video en la aplicacion movil, incluyendo validaciones de calidad, preprocesamiento local, y carga resiliente al servidor.

### Objetivo

Permitir a los usuarios grabar videos de alta calidad de sus anaqueles de forma guiada para su posterior procesamiento por IA.

---

## 2. Requerimientos Relacionados

| RF | Descripcion | Prioridad |
|----|-------------|-----------|
| FR-020 | Captura guiada (30-60s, distancia, luz, movimiento) | P0 |
| FR-021 | Preprocesado movil (compresion, estabilizacion) | P1 |
| FR-022 | Evidencia adicional (foto close-up en duda) | P1 |
| FR-030 | Carga de video resiliente (reintentos, resume) | P0 |

---

## 3. Criterios de Aceptacion

### AC-001: Captura Guiada
```gherkin
DADO que inicio una sesion de inventario
CUANDO activo la camara
ENTONCES veo indicaciones visuales de:
  - Distancia optima (50-100cm)
  - Nivel de iluminacion
  - Velocidad de movimiento
Y la duracion sugerida es 30-60 segundos
```

### AC-002: Validacion de Calidad
```gherkin
DADO que estoy grabando
CUANDO la calidad es insuficiente
ENTONCES veo alertas en tiempo real:
  - "Acercate mas" / "Alejate un poco"
  - "Necesitas mas luz"
  - "Muevete mas lento"
Y no puedo finalizar si la calidad es inaceptable
```

### AC-003: Preprocesamiento
```gherkin
DADO que termine de grabar
CUANDO el video se preprocesa
ENTONCES se comprime a un bitrate optimo
Y la resolucion es minimo 720p
Y el tamano final es manejable para upload
```

### AC-004: Upload Resiliente
```gherkin
DADO que tengo un video listo
CUANDO inicio la carga
ENTONCES puedo ver el progreso
Y si se interrumpe, se reanuda automaticamente
Y si falla multiples veces, se notifica al usuario
```

### AC-005: Evidencia Adicional
```gherkin
DADO que el sistema detecto productos con duda
CUANDO me solicita evidencia adicional
ENTONCES puedo tomar una foto close-up
Y la foto se asocia al item dudoso
```

---

## 4. Tareas Tecnicas

| ID | Tarea | Estimacion | Estado |
|----|-------|------------|--------|
| T-001 | Implementar pantalla de captura con expo-camera | 3 SP | Completado |
| T-002 | Crear overlay de guia visual | 2 SP | Completado |
| T-003 | Implementar validaciones en tiempo real | 3 SP | Completado |
| T-004 | Configurar compresion de video | 2 SP | Completado |
| T-005 | Implementar extraccion de keyframes | 2 SP | Completado |
| T-006 | Crear servicio de upload con retry | 3 SP | Completado |
| T-007 | Implementar resume de uploads | 2 SP | Completado |
| T-008 | Crear endpoint de upload en backend | 2 SP | Completado |
| T-009 | Integrar con S3/MinIO | 1 SP | Completado |
| T-010 | Implementar captura de foto adicional | 1 SP | Completado |

---

## 5. Modelo de Datos

### Tabla: videos
```sql
CREATE TABLE videos (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  session_id UUID REFERENCES inventory_sessions(id),
  store_id UUID REFERENCES stores(id),
  user_id UUID REFERENCES users(id),
  s3_key VARCHAR(500) NOT NULL,
  original_filename VARCHAR(255),
  file_size BIGINT,
  duration_seconds INT,
  resolution VARCHAR(20),
  fps INT,
  status VARCHAR(20) DEFAULT 'UPLOADING',
  upload_progress INT DEFAULT 0,
  processing_metadata JSONB,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Status: UPLOADING, UPLOADED, PROCESSING, PROCESSED, FAILED
```

### Tabla: video_artifacts
```sql
CREATE TABLE video_artifacts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  video_id UUID REFERENCES videos(id) ON DELETE CASCADE,
  type VARCHAR(50), -- 'keyframe', 'closeup', 'thumbnail'
  s3_key VARCHAR(500),
  frame_number INT,
  timestamp_ms INT,
  metadata JSONB,
  created_at TIMESTAMP DEFAULT NOW()
);
```

---

## 6. Endpoints API

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| POST | /videos/init-upload | Iniciar upload multipart | JWT |
| PUT | /videos/:id/part/:partNum | Subir parte | JWT |
| POST | /videos/:id/complete | Completar upload | JWT |
| POST | /videos/:id/abort | Abortar upload | JWT |
| GET | /videos/:id/status | Estado del video | JWT |
| POST | /videos/:id/artifacts | Agregar artefacto | JWT |

---

## 7. Pantallas Mobile

| Pantalla | Componentes |
|----------|-------------|
| **CaptureScreen** | Camara, overlay guia, controles |
| **PreviewScreen** | Preview video, opciones regrabar/usar |
| **UploadScreen** | Progreso, estado, retry |
| **CloseupCaptureScreen** | Camara foto, instrucciones |

---

## 8. Guia Visual de Captura

```
┌─────────────────────────────────────────┐
│  ┌───────────────────────────────────┐  │
│  │                                   │  │
│  │     [Visor de Camara]            │  │
│  │                                   │  │
│  │  ┌─────────────────────────────┐  │  │
│  │  │    ZONA OPTIMA DE ENFOQUE   │  │  │
│  │  │    (marco guia verde)       │  │  │
│  │  └─────────────────────────────┘  │  │
│  │                                   │  │
│  └───────────────────────────────────┘  │
│                                         │
│  [💡 Buena luz]  [📏 Distancia OK]     │
│                                         │
│  [⏱️ 00:32 / 00:60]                    │
│                                         │
│  [     🔴 GRABANDO     ]               │
│                                         │
└─────────────────────────────────────────┘
```

---

## 9. Especificaciones Tecnicas

### Video

| Parametro | Valor |
|-----------|-------|
| Resolucion minima | 720p |
| Resolucion optima | 1080p |
| FPS | 30 |
| Codec | H.264 |
| Bitrate target | 2-4 Mbps |
| Duracion | 30-60 segundos |
| Tamano maximo | ~30 MB |

### Upload

| Parametro | Valor |
|-----------|-------|
| Chunk size | 5 MB |
| Max retries | 3 |
| Retry delay | Exponential backoff |
| Resume window | 24 horas |
| Timeout por chunk | 60 segundos |

### Validaciones

| Validacion | Umbral |
|------------|--------|
| Luz minima | 100 lux |
| Movimiento maximo | 30 px/frame |
| Enfoque | >70% sharpness |
| Distancia | 50-150 cm |

---

## 10. Dependencias

### Entrada (Requiere)
- MII-001: Infraestructura Base
- MII-002: Autenticacion
- MII-003: Gestion de Tiendas

### Salida (Bloquea)
- MII-005: Procesamiento IA
- MII-006: Reportes

---

## 11. Integraciones

| Servicio | Uso |
|----------|-----|
| expo-camera | Captura de video |
| expo-av | Reproduccion y procesamiento |
| S3/MinIO | Almacenamiento |
| FFmpeg (si aplica) | Compresion avanzada |

---

## 12. Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Dispositivos lentos | Alta | Medio | Ajustar calidad dinamicamente |
| Red intermitente | Alta | Alto | Resume, queue local |
| Almacenamiento lleno | Media | Medio | Limpiar videos procesados |
| Calidad insuficiente | Media | Alto | Validacion estricta, feedback |

---

## 13. Notas de Implementacion

- Usar expo-camera para captura nativa
- Implementar queue local para uploads pendientes (offline)
- Considerar WebSocket para progreso en tiempo real
- Limpiar videos locales despues de upload exitoso
- Guardar thumbnail para preview rapido

---

## 14. Referencias

- [REQUERIMIENTOS-FUNCIONALES.md](../00-vision-general/REQUERIMIENTOS-FUNCIONALES.md) - Secciones 5.3, 5.4
- [ARQUITECTURA-TECNICA.md](../00-vision-general/ARQUITECTURA-TECNICA.md)
- [INT-005](../02-integraciones/INT-005-s3-storage.md) - Integracion S3

---

**Ultima Actualizacion:** 2026-01-10