miinventario-v2/docs/01-epicas/MII-007-retroalimentacion.md

# MII-007: Retroalimentacion

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

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | MII-007 |
| **Nombre** | Retroalimentacion |
| **Fase** | 2 - Retroalimentacion |
| **Prioridad** | P1 |
| **Story Points** | 13 |
| **Estado** | Completado |

---

## 1. Descripcion

Implementar el sistema de retroalimentacion que permite a los usuarios corregir errores de deteccion, etiquetar productos desconocidos, y contribuir a la mejora del modelo de IA.

### Objetivo

Permitir a los usuarios mejorar la precision del sistema corrigiendo errores y etiquetando productos, creando un ciclo de mejora continua.

---

## 2. Requerimientos Relacionados

| RF | Descripcion | Prioridad |
|----|-------------|-----------|
| FR-060 | Correccion de SKU (cambiar producto identificado) | P1 |
| FR-061 | Correccion de cantidad (ajuste manual) | P1 |
| FR-062 | Etiquetado de desconocidos (foto, marca, presentacion) | P1 |
| FR-063 | Registro de Ground Truth (correcciones trazables) | P0 |

---

## 3. Criterios de Aceptacion

### AC-001: Corregir SKU
```gherkin
DADO que veo un item mal identificado
CUANDO selecciono "Corregir"
ENTONCES puedo buscar el producto correcto
Y al seleccionarlo, se actualiza el item
Y la correccion queda registrada como ground truth
```

### AC-002: Corregir Cantidad
```gherkin
DADO que veo una cantidad incorrecta
CUANDO ajusto el numero manualmente
ENTONCES la cantidad se actualiza
Y el cambio queda registrado
Y se muestra la cantidad original vs corregida
```

### AC-003: Etiquetar Desconocido
```gherkin
DADO que hay un producto "Desconocido"
CUANDO selecciono "Etiquetar"
ENTONCES puedo:
  - Tomar foto close-up
  - Seleccionar marca de una lista
  - Escribir presentacion
Y el producto se crea/asocia
Y contribuye al entrenamiento del modelo
```

### AC-004: Confirmar Item Correcto
```gherkin
DADO que veo un item con duda
CUANDO confirmo que es correcto
ENTONCES su status cambia a CONFIRMED
Y se registra como ground truth positivo
```

### AC-005: Trazabilidad
```gherkin
DADO que hice correcciones
CUANDO reviso el historial de un item
ENTONCES puedo ver:
  - Valor original detectado
  - Valor corregido
  - Quien corrigio
  - Cuando se corrigio
```

---

## 4. Tareas Tecnicas

| ID | Tarea | Estimacion | Estado |
|----|-------|------------|--------|
| T-001 | Crear modal de correccion de SKU | 2 SP | Completado |
| T-002 | Implementar busqueda de productos | 2 SP | Completado |
| T-003 | Crear input de correccion de cantidad | 1 SP | Completado |
| T-004 | Implementar flujo de etiquetado | 3 SP | Completado |
| T-005 | Crear formulario nuevo producto | 2 SP | Completado |
| T-006 | Implementar registro ground truth | 2 SP | Completado |
| T-007 | Crear endpoints de correcciones | 1 SP | Completado |

---

## 5. Modelo de Datos

### Tabla: corrections
```sql
CREATE TABLE corrections (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  item_id UUID REFERENCES inventory_items(id),
  session_id UUID REFERENCES inventory_sessions(id),
  user_id UUID REFERENCES users(id),
  correction_type VARCHAR(20), -- 'SKU', 'QUANTITY', 'LABEL'
  original_value JSONB,
  corrected_value JSONB,
  confidence_before DECIMAL(5,2),
  evidence_url VARCHAR(500),
  created_at TIMESTAMP DEFAULT NOW()
);
```

### Tabla: ground_truth
```sql
CREATE TABLE ground_truth (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  product_id UUID REFERENCES products(id),
  image_url VARCHAR(500),
  bounding_box JSONB,
  source_type VARCHAR(20), -- 'CORRECTION', 'VALIDATION', 'UPLOAD'
  source_id UUID,
  user_id UUID REFERENCES users(id),
  status VARCHAR(20) DEFAULT 'PENDING', -- 'PENDING', 'APPROVED', 'REJECTED'
  reviewed_by UUID REFERENCES users(id),
  reviewed_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW()
);
```

### Tabla: product_submissions
```sql
CREATE TABLE product_submissions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  submitted_by UUID REFERENCES users(id),
  name VARCHAR(200),
  brand VARCHAR(100),
  category VARCHAR(100),
  presentation VARCHAR(100),
  image_url VARCHAR(500),
  status VARCHAR(20) DEFAULT 'PENDING', -- 'PENDING', 'APPROVED', 'REJECTED', 'MERGED'
  merged_to UUID REFERENCES products(id),
  reviewed_by UUID REFERENCES users(id),
  reviewed_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW()
);
```

---

## 6. Endpoints API

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| PATCH | /inventory/items/:id/correct-sku | Corregir SKU | JWT |
| PATCH | /inventory/items/:id/correct-quantity | Corregir cantidad | JWT |
| POST | /inventory/items/:id/confirm | Confirmar correcto | JWT |
| POST | /products/submit | Enviar nuevo producto | JWT |
| GET | /products/search | Buscar productos | JWT |
| POST | /ground-truth | Registrar ground truth | JWT |
| GET | /inventory/items/:id/history | Historial correcciones | JWT |

---

## 7. Pantallas Mobile

| Pantalla | Componentes |
|----------|-------------|
| **CorrectSKUModal** | Buscador, lista resultados, confirmar |
| **CorrectQuantityModal** | Input numerico, original vs nuevo |
| **LabelProductScreen** | Camara, form producto, submit |
| **ProductSearchScreen** | Buscador, filtros, resultados |
| **ConfirmItemModal** | Vista item, boton confirmar |

---

## 8. Flujo de Etiquetado

```
┌─────────────────────────────────────────────────────────────────┐
│                    FLUJO DE ETIQUETADO                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐     │
│  │ Producto │──▶│  Tomar   │──▶│ Llenar   │──▶│  Enviar  │     │
│  │Desconocido│   │  Foto    │   │  Form    │   │ Producto │     │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘     │
│                                                    │             │
│                                                    ▼             │
│                                             ┌──────────┐         │
│                                             │ Moderador│         │
│                                             │  Revisa  │         │
│                                             └────┬─────┘         │
│                                  ┌───────────────┼───────────┐   │
│                                  ▼               ▼           ▼   │
│                            ┌─────────┐    ┌─────────┐ ┌─────────┐│
│                            │Aprobado │    │Rechazado│ │ Merged  ││
│                            │(nuevo)  │    │         │ │(existia)││
│                            └─────────┘    └─────────┘ └─────────┘│
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## 9. Metricas de Mejora

| Metrica | Descripcion |
|---------|-------------|
| Correction Rate | % de items corregidos por sesion |
| Product Submissions | Nuevos productos enviados |
| Approval Rate | % de submissions aprobados |
| Model Improvement | Cambio en precision tras reentrenamiento |

---

## 10. Dependencias

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

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

---

## 11. Incentivos (Opcional)

| Accion | Recompensa |
|--------|------------|
| Corregir 10 items | Badge "Contribuidor" |
| Producto aprobado | +0.1 creditos |
| 100 correcciones | Badge "Experto" |

---

## 12. Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Correcciones falsas | Media | Alto | Moderacion, reputation |
| Spam de productos | Media | Medio | Rate limit, moderacion |
| Confusion UX | Media | Medio | Tutorial, tooltips |

---

## 13. Notas de Implementacion

- Guardar siempre el valor original antes de corregir
- Implementar busqueda fuzzy para productos
- Considerar autocompletado de marcas/categorias
- La foto de etiquetado debe tener buena resolucion
- Validar consentimiento para usar datos en entrenamiento

---

## 14. Referencias

- [REQUERIMIENTOS-FUNCIONALES.md](../00-vision-general/REQUERIMIENTOS-FUNCIONALES.md) - Seccion 5.7
- [ARQUITECTURA-TECNICA.md](../00-vision-general/ARQUITECTURA-TECNICA.md)

---

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