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

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

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

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

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

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

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

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 - Secciones 5.3, 5.4
• ARQUITECTURA-TECNICA.md
• INT-005 - Integracion S3

---

Ultima Actualizacion: 2026-01-10