MII-005: Procesamiento IA
id: MII-005
type: Epic
status: Pendiente
priority: P0
phase: 1
story_points: 34
created_date: 2026-01-10
updated_date: 2026-01-10
simco_version: "4.0.0"
Metadata
| Campo |
Valor |
| ID |
MII-005 |
| Nombre |
Procesamiento IA |
| Fase |
1 - MVP Core |
| Prioridad |
P0 |
| Story Points |
34 |
| Estado |
Pendiente |
1. Descripcion
Implementar el pipeline de procesamiento de video con IA para deteccion, identificacion y conteo de productos, incluyendo el job asincrono, abstraccion de proveedores, y consolidacion multi-frame.
Objetivo
Procesar videos de anaqueles para identificar y contar productos automaticamente, entregando resultados precisos al usuario.
2. Requerimientos Relacionados
| RF |
Descripcion |
Prioridad |
| FR-031 |
Job asincrono con estados PENDING/PROCESSING/DONE/FAILED |
P0 |
| FR-032 |
Notificacion push o polling para "resultado listo" |
P1 |
| FR-033 |
Almacenamiento temporal (7-30 dias) y borrado automatico |
P1 |
| FR-040 |
Deteccion con bounding boxes/segmentacion |
P0 |
| FR-041 |
Identificacion SKU (multiclase o 2 etapas) |
P0 |
| FR-042 |
Consolidacion multi-frame (evitar doble conteo) |
P0 |
| FR-043 |
Umbrales de confianza (Duda, Desconocido) |
P0 |
3. Criterios de Aceptacion
AC-001: Job Asincrono
DADO que un video fue subido exitosamente
CUANDO el sistema lo recibe
ENTONCES se crea un job con status PENDING
Y se encola para procesamiento
Y el usuario puede ver el status en tiempo real
AC-002: Deteccion de Productos
DADO que el job esta en PROCESSING
CUANDO el sistema analiza los frames
ENTONCES detecta productos con bounding boxes
Y cada deteccion tiene coordenadas y confianza
AC-003: Identificacion de SKU
DADO que hay productos detectados
CUANDO el sistema los identifica
ENTONCES asocia cada producto a un SKU conocido
O lo marca como "Desconocido" si no hay match
O lo marca como "Duda" si conf < threshold
AC-004: Consolidacion Multi-frame
DADO que un producto aparece en multiples frames
CUANDO el sistema consolida resultados
ENTONCES lo cuenta una sola vez
Y usa tracking espacial-temporal
Y el conteo final es preciso
AC-005: Notificacion de Resultado
DADO que el procesamiento termino
CUANDO el status cambia a DONE
ENTONCES el usuario recibe notificacion push
Y puede ver el reporte inmediatamente
AC-006: Almacenamiento Temporal
DADO que un video fue procesado
CUANDO pasan N dias (configurable)
ENTONCES el video y artefactos se eliminan automaticamente
Y los resultados del inventario se mantienen
4. Tareas Tecnicas
| ID |
Tarea |
Estimacion |
Estado |
| T-001 |
Crear modulo ia-provider en NestJS |
2 SP |
Pendiente |
| T-002 |
Implementar abstraccion de proveedores IA |
3 SP |
Pendiente |
| T-003 |
Crear adapter para proveedor inicial |
2 SP |
Pendiente |
| T-004 |
Implementar servicio de extraccion de frames |
2 SP |
Pendiente |
| T-005 |
Crear procesador de queue (Bull) |
3 SP |
Pendiente |
| T-006 |
Implementar pipeline de deteccion |
4 SP |
Pendiente |
| T-007 |
Implementar identificacion de SKU |
4 SP |
Pendiente |
| T-008 |
Crear algoritmo de consolidacion multi-frame |
5 SP |
Pendiente |
| T-009 |
Implementar tracking espacial-temporal |
3 SP |
Pendiente |
| T-010 |
Crear logica de umbrales y estados |
2 SP |
Pendiente |
| T-011 |
Implementar notificaciones push |
2 SP |
Pendiente |
| T-012 |
Crear job de limpieza automatica |
2 SP |
Pendiente |
5. Arquitectura del Pipeline
┌─────────────────────────────────────────────────────────────────────────────┐
│ PIPELINE DE PROCESAMIENTO IA │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Video │──▶│ Extract │──▶│ Detect │──▶│ Identify │──▶│Consolidate│ │
│ │ Input │ │ Frames │ │ Products │ │ SKU │ │ Results │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ S3 Key 10-30 frames Bounding Product IDs Final Count │
│ @ 1 fps Boxes + Confidence per SKU │
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ IA PROVIDER ABSTRACTION │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ OpenAI │ │ Claude │ │ Google │ │ Custom │ │ │
│ │ │ Vision │ │ Vision │ │ Vision │ │ Model │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
6. Modelo de Datos
Tabla: inventory_sessions
CREATE TABLE inventory_sessions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
store_id UUID REFERENCES stores(id),
user_id UUID REFERENCES users(id),
video_id UUID REFERENCES videos(id),
status VARCHAR(20) DEFAULT 'PENDING',
started_at TIMESTAMP,
completed_at TIMESTAMP,
total_products INT,
total_items INT,
confidence_avg DECIMAL(5,2),
credits_consumed INT,
cogs_amount DECIMAL(10,4),
ia_provider VARCHAR(50),
processing_metadata JSONB,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- Status: PENDING, PROCESSING, DONE, FAILED
Tabla: inventory_items
CREATE TABLE inventory_items (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
session_id UUID REFERENCES inventory_sessions(id) ON DELETE CASCADE,
product_id UUID REFERENCES products(id),
quantity INT NOT NULL,
confidence DECIMAL(5,2),
status VARCHAR(20) DEFAULT 'DETECTED',
bounding_boxes JSONB, -- Array de boxes por frame
frame_numbers INT[],
evidence_urls TEXT[],
user_corrected BOOLEAN DEFAULT false,
original_product_id UUID,
original_quantity INT,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- Status: DETECTED, DOUBT, UNKNOWN, CONFIRMED, CORRECTED
Tabla: products
CREATE TABLE products (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(200) NOT NULL,
brand VARCHAR(100),
category VARCHAR(100),
subcategory VARCHAR(100),
barcode VARCHAR(50),
presentation VARCHAR(100),
embedding VECTOR(1536), -- Para busqueda por similitud
image_url VARCHAR(500),
is_verified BOOLEAN DEFAULT false,
created_by UUID REFERENCES users(id),
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
Tabla: cogs_records
CREATE TABLE cogs_records (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
session_id UUID REFERENCES inventory_sessions(id),
provider VARCHAR(50),
frames_processed INT,
tokens_used INT,
cost_usd DECIMAL(10,6),
cost_mxn DECIMAL(10,4),
exchange_rate DECIMAL(10,4),
created_at TIMESTAMP DEFAULT NOW()
);
7. Endpoints API
| Metodo |
Endpoint |
Descripcion |
Auth |
| POST |
/inventory/sessions |
Crear sesion de inventario |
JWT |
| GET |
/inventory/sessions/:id |
Obtener sesion |
JWT |
| GET |
/inventory/sessions/:id/status |
Estado del procesamiento |
JWT |
| GET |
/inventory/sessions/:id/items |
Items detectados |
JWT |
| POST |
/inventory/sessions/:id/reprocess |
Reprocesar sesion |
JWT |
8. Abstraccion de Proveedores
Interface IAProvider
interface IAProvider {
name: string;
detectProducts(frames: Buffer[]): Promise<Detection[]>;
identifyProduct(detection: Detection): Promise<ProductMatch>;
getCostPerFrame(): number;
isAvailable(): Promise<boolean>;
}
interface Detection {
frameNumber: number;
boundingBox: BoundingBox;
confidence: number;
embedding?: number[];
}
interface ProductMatch {
productId: string | null;
confidence: number;
alternatives: Array<{productId: string; confidence: number}>;
isKnown: boolean;
}
9. Algoritmo de Consolidacion
1. Para cada frame F[i]:
- Obtener detecciones D[i] = detect(F[i])
2. Para cada deteccion d en D[i]:
- Calcular embedding e(d)
- Buscar match en detecciones anteriores por:
a. Posicion similar (IoU > 0.5)
b. Embedding similar (cosine > 0.8)
3. Si hay match:
- Actualizar track existente
- Promediar confianza
4. Si no hay match:
- Crear nuevo track
5. Al final:
- Agrupar tracks por producto
- Contar instancias unicas
- Aplicar umbrales de confianza
10. Umbrales de Confianza
| Rango |
Estado |
Accion |
| >= 0.85 |
DETECTED |
Incluir en reporte |
| 0.60 - 0.84 |
DOUBT |
Solicitar confirmacion |
| < 0.60 |
UNKNOWN |
Permitir etiquetado |
11. Dependencias
Entrada (Requiere)
- MII-001: Infraestructura Base
- MII-002: Autenticacion
- MII-003: Gestion de Tiendas
- MII-004: Captura de Video
Salida (Bloquea)
- MII-006: Reportes de Inventario
- MII-007: Retroalimentacion
- MII-009: Wallet y Creditos (COGS)
12. Integraciones
| Servicio |
Uso |
| Bull/Redis |
Job queue |
| S3/MinIO |
Frames y artefactos |
| OpenAI/Claude |
Vision API |
| Firebase FCM |
Push notifications |
| PostgreSQL |
Resultados |
13. Riesgos
| Riesgo |
Probabilidad |
Impacto |
Mitigacion |
| IA imprecisa |
Alta |
Alto |
Retroalimentacion, fine-tuning |
| Costos altos |
Media |
Alto |
Optimizar frames, cache |
| Latencia |
Media |
Medio |
Async, notificaciones |
| Proveedor caido |
Baja |
Alto |
Fallback a otro proveedor |
14. Metricas
| Metrica |
Objetivo |
| Precision |
> 80% en productos conocidos |
| Tiempo promedio |
< 2 minutos por sesion |
| Costo promedio |
< $0.50 USD por sesion |
| Tasa de "Duda" |
< 15% de detecciones |
| Tasa de "Desconocido" |
< 10% de detecciones |
15. Referencias
Ultima Actualizacion: 2026-01-10
rckrdmrd
1a53b5c4d3