miinventario-v2/docs/01-epicas/MII-008-validacion-aleatoria.md

# MII-008: Validacion Aleatoria

---
id: MII-008
type: Epic
status: Completado
priority: P1
phase: 2
story_points: 8
created_date: 2026-01-10
updated_date: 2026-01-13
simco_version: "4.0.0"
---

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | MII-008 |
| **Nombre** | Validacion Aleatoria |
| **Fase** | 2 - Retroalimentacion |
| **Prioridad** | P1 |
| **Story Points** | 8 |
| **Estado** | Completado |

---

## 1. Descripcion

Implementar un sistema de micro-auditorias aleatorias que solicite confirmacion de items seleccionados para mejorar la calidad de los datos de entrenamiento.

### Objetivo

Obtener validaciones de alta calidad de forma no intrusiva para mejorar continuamente el modelo de IA.

---

## 2. Requerimientos Relacionados

| RF | Descripcion | Prioridad |
|----|-------------|-----------|
| FR-070 | Micro-auditorias en X% de sesiones (1-3 items) | P1 |
| FR-071 | Reglas de activacion (baja calidad, confianza, usuario nuevo) | P1 |

---

## 3. Criterios de Aceptacion

### AC-001: Validacion Aleatoria Basica
```gherkin
DADO que complete una sesion de inventario
CUANDO el sistema activa una micro-auditoria
ENTONCES me muestra 1-3 items aleatorios
Y me pide confirmar si la deteccion es correcta
Y puedo confirmar o corregir cada item
```

### AC-002: Reglas de Activacion
```gherkin
DADO que complete una sesion
CUANDO se evaluan las reglas de activacion
ENTONCES la probabilidad de auditoria aumenta si:
  - La calidad del video fue baja
  - Hay items con baja confianza
  - Soy un usuario nuevo (< 5 sesiones)
  - Es un horario de bajo trafico
```

### AC-003: Items Prioritarios
```gherkin
DADO que se activo una micro-auditoria
CUANDO se seleccionan los items
ENTONCES se priorizan items con:
  - Confianza media (0.60-0.85)
  - Productos nuevos o poco vistos
  - Productos de alto valor
```

### AC-004: Experiencia No Intrusiva
```gherkin
DADO que me muestran una micro-auditoria
CUANDO respondo
ENTONCES el proceso es rapido (< 30 segundos)
Y puedo saltar si estoy ocupado
Y no se repite en la siguiente sesion
```

### AC-005: Registro de Validaciones
```gherkin
DADO que complete una validacion
CUANDO el sistema guarda mi respuesta
ENTONCES se registra como ground truth
Y contribuye al entrenamiento del modelo
```

---

## 4. Tareas Tecnicas

| ID | Tarea | Estimacion | Estado |
|----|-------|------------|--------|
| T-001 | Implementar motor de reglas de activacion | 2 SP | Completado |
| T-002 | Crear algoritmo de seleccion de items | 1 SP | Completado |
| T-003 | Implementar pantalla de micro-auditoria | 2 SP | Completado |
| T-004 | Crear endpoints de validacion | 1 SP | Completado |
| T-005 | Integrar con ground truth | 1 SP | Completado |
| T-006 | Implementar metricas y dashboard | 1 SP | Completado |

---

## 5. Motor de Reglas

### Reglas de Activacion

| Regla | Peso | Descripcion |
|-------|------|-------------|
| BASE_RATE | 10% | Probabilidad base |
| LOW_QUALITY | +20% | Si calidad video < 70% |
| LOW_CONFIDENCE | +15% | Si confianza promedio < 80% |
| NEW_USER | +15% | Si usuario tiene < 5 sesiones |
| MANY_UNKNOWNS | +10% | Si > 20% items desconocidos |
| OFF_PEAK | +5% | Si es horario de bajo trafico |
| RECENT_SKIP | -20% | Si skipeo auditoria reciente |

### Calculo de Probabilidad

```
P(auditoria) = min(BASE_RATE + sum(weights), 60%)
```

### Ejemplo

```
Usuario nuevo (15%) + Baja confianza (15%) + Base (10%) = 40%
```

---

## 6. Algoritmo de Seleccion

```python
def select_items_for_validation(session_items, count=3):
    # 1. Filtrar items elegibles
    eligible = [i for i in session_items if i.status != 'UNKNOWN']

    # 2. Calcular score de prioridad
    for item in eligible:
        item.priority_score = calculate_priority(item)

    # 3. Ordenar por prioridad
    sorted_items = sorted(eligible, key=lambda x: x.priority_score, reverse=True)

    # 4. Seleccionar top N con algo de aleatoriedad
    top_pool = sorted_items[:count * 2]
    selected = random.sample(top_pool, min(count, len(top_pool)))

    return selected

def calculate_priority(item):
    score = 0

    # Items con confianza media son mas valiosos
    if 0.60 <= item.confidence < 0.85:
        score += 30

    # Productos poco vistos
    if item.product.validation_count < 10:
        score += 20

    # Productos de alto valor
    if item.product.is_high_value:
        score += 10

    # Agregar ruido aleatorio
    score += random.randint(0, 15)

    return score
```

---

## 7. Endpoints API

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| GET | /validations/check/:sessionId | Verificar si hay auditoria | JWT |
| GET | /validations/:sessionId/items | Obtener items a validar | JWT |
| POST | /validations/:sessionId/submit | Enviar respuestas | JWT |
| POST | /validations/:sessionId/skip | Saltar auditoria | JWT |

---

## 8. Pantallas Mobile

| Pantalla | Componentes |
|----------|-------------|
| **ValidationPromptModal** | Mensaje invitacion, botones aceptar/saltar |
| **ValidationScreen** | Card item, imagen, botones correcto/incorrecto |
| **ValidationCompleteScreen** | Agradecimiento, resumen |

---

## 9. UI de Validacion

```
┌─────────────────────────────────────────┐
│        Ayudanos a mejorar               │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │                                 │   │
│  │     [Imagen del producto]       │   │
│  │                                 │   │
│  └─────────────────────────────────┘   │
│                                         │
│  Detectamos:                            │
│  Coca-Cola 600ml                        │
│  Cantidad: 24                           │
│                                         │
│  ¿Es correcto?                          │
│                                         │
│  ┌─────────┐    ┌─────────────────┐    │
│  │   Si    │    │ No, corregir    │    │
│  └─────────┘    └─────────────────┘    │
│                                         │
│  [2 de 3]              [Saltar todo]   │
└─────────────────────────────────────────┘
```

---

## 10. Metricas

| Metrica | Objetivo |
|---------|----------|
| Tasa de respuesta | > 70% |
| Tiempo promedio | < 30 segundos |
| Tasa de confirmacion | > 80% |
| Validaciones por dia | > 100 |

---

## 11. Modelo de Datos

### Tabla: validation_requests
```sql
CREATE TABLE validation_requests (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  session_id UUID REFERENCES inventory_sessions(id),
  user_id UUID REFERENCES users(id),
  triggered_by VARCHAR(50), -- 'AUTO', 'MANUAL', 'ADMIN'
  rules_matched JSONB,
  probability_score DECIMAL(5,2),
  status VARCHAR(20) DEFAULT 'PENDING', -- 'PENDING', 'COMPLETED', 'SKIPPED', 'EXPIRED'
  items_count INT,
  completed_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW()
);
```

### Tabla: validation_responses
```sql
CREATE TABLE validation_responses (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  request_id UUID REFERENCES validation_requests(id),
  item_id UUID REFERENCES inventory_items(id),
  is_correct BOOLEAN,
  corrected_value JSONB,
  response_time_ms INT,
  created_at TIMESTAMP DEFAULT NOW()
);
```

---

## 12. Dependencias

### Entrada (Requiere)
- MII-005: Procesamiento IA
- MII-006: Reportes de Inventario

### Salida (Bloquea)
- Pipeline de reentrenamiento (futuro)

---

## 13. Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Usuario fatigue | Media | Medio | Limitar frecuencia, gamificacion |
| Respuestas apresuradas | Media | Medio | Timeout, confirmacion |
| Skip excesivo | Media | Bajo | Cooldown despues de skip |

---

## 14. Notas de Implementacion

- No mostrar auditoria si usuario skipeo en ultimas 24h
- Guardar tiempo de respuesta para detectar spam
- Considerar gamificacion (badges, leaderboard)
- A/B test diferentes frecuencias de auditoria

---

## 15. Referencias

- [REQUERIMIENTOS-FUNCIONALES.md](../00-vision-general/REQUERIMIENTOS-FUNCIONALES.md) - Seccion 5.8
- [MII-007](./MII-007-retroalimentacion.md) - Sistema de correcciones

---

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