FT-REF-04 · Matching por imagen y por URL del seller

En 30 segundos

Los sellers evaden la revisión con EAN inventados o atributos alterados, y la foto es lo más difícil de falsear. Esta épica deja que el seller entre por una imagen o por la URL de su página de producto: la IA lee la página (EAN, marca, atributos, fotos) o mira la imagen, busca productos parecidos en el catálogo y le entrega todo a Evaluación para la lista negra y la decisión por negocio. Lo extraído se guarda para prellenar sin volver a pagar el modelo.

• Módulo dueño: MS-15 IA y enriquecimiento. También participan: MS-01 Catálogo, MS-02 Producto, MS-06 Evaluación, MS-11 Activos digitales.
• Etapa 1 · ¿Ya existe?. Recibe «PE-1 · Propuesta en Borrador» y entrega «PE-2 · Sin duplicado».
• APIs: construye 1 y usa 10 que construyen otras épicas.
• Eventos: publica 0 y consume 0.

1. Dónde encaja

Recibe

Entrega

2. Diagrama de contexto

Quién participa y cómo se conecta. Las pantallas llegan por el BFF del portal, que valida el token y compone; cada módulo vuelve a validar el token y decide sus permisos con los roles de MS-13.

🟩 Verde: nuevo, se construye · 🟦 Azul: ya existe y se queda, se reutiliza su código · 🟧 Naranja: temporal o se retira (se apaga en R3) · ⬜ Gris: sistema externo · ★ módulo dueño

3. Diagrama de flujo

El camino principal, paso por paso. Cuando una pantalla llama a un módulo se ven dos flechas: la pantalla al BFF y el BFF al módulo. Los eventos salen del outbox del módulo después de guardar; quien los consume ignora los repetidos.

3.1 Camino imagen

3.2 Ver referencias para precargar

3.3 Posible duplicado por imagen en Mercaderías

4. Si algo sale mal

• La página no se puede leer o no trae datos de producto. MS-15 responde que no pudo leerla; el seller ve «no pudimos leer tu página» y puede seguir por imagen o por características. Nada se da por identificado sin evaluación.
• La IA no termina en 15 segundos. La evaluación responde RUNNING y el seller ve «seguimos revisando tu producto»; no puede elegir plantilla hasta que llegue EVALUATION_DONE. Si el modelo está caído, puede seguir por características con la marca y el EAN.
• La foto delata un producto que ya existe con otro EAN. El candidato visual pasa la banda alta y entra a la decisión por negocio: multioferta, stock out o bloqueo, con explicación. El intento queda en la evaluación.
• La marca leída de la página no está en el catálogo de marcas. No se da por buena: la evaluación queda en revisión de Gobierno de Datos, porque sin código de marca no se puede revisar la lista negra.

5. APIs

Las que construye esta épica (1)

{
  "evaluationId": "evl-0000733",
  "business": "MKP",
  "source": {
    "type": "URL",
    "pdpUrl": "<URL pública del PDP del seller>",
    "imageAssetId": null
  },
  "want": [
    "EXTRACTION",
    "VISUAL_CANDIDATES"
  ]
}

{
  "success": true,
  "data": {
    "jobId": "job-0003311",
    "status": "DONE",
    "partial": false,
    "extraction": {
      "from": "PDP",
      "ean": "7501234567893",
      "brandText": "Marca Uno",
      "brandCode": "MARCA01",
      "model": "PF-100",
      "title": "Perfume floral para mujer 100 ml",
      "attributes": [
        {
          "code": "CONTENIDO_ML",
          "value": 100,
          "unit": "ML",
          "confidence": 0.95
        },
        {
          "code": "GENERO",
          "value": "MUJER",
          "confidence": 0.9
        }
      ],
      "imagesFound": 4
    },
    "visualCandidates": [
      {
        "productId": "PRD-0001190",
        "business": "MER",
        "sku": "1000001190",
        "similarity": 0.93
      }
    ]
  }
}

Las que usa y construye otra épica (10)

Su request y su response están en la página de la épica que la construye.

6. Eventos

Esta épica no publica ni consume eventos.

7. Datos

Cada colección tiene un solo dueño, el único que escribe en ella.

8. Historias que cubre

9. Decisiones de esta épica

Las tomó el TL como arquitecto; quedan como [Propuesta] hasta que el equipo de la épica las revise.

• D-REF-04-1. MS-15 es el único que lee páginas de sellers y habla con los modelos. MS-06 le pide la extracción y los parecidos (API-15-006) y decide con su tabla; ni MS-02 ni la pantalla llaman a la IA para identificar. Por qué: Un solo motor de IA y una sola decisión: si cada quien llamara a los modelos habría reglas y costos repartidos. Se apoya en ADR-12, DUD-35, RN-MAT-10.
• D-REF-04-2. La imagen de consulta se sube a Activos con propósito MATCHING: no se le exige ficha técnica ni se liga al producto, y si nadie la usa se borra a los 30 días. Las fotos encontradas en la página del seller no se guardan: se ofrecen como sugerencia y, si el seller las quiere, se registran por URL en Activos con su validación técnica (FT-ACT-03). Por qué: Imagen para consultar no es imagen para cargar; cada archivo vive una sola vez en MS-11. Se apoya en RF-IMG-05, PEN-53.
• D-REF-04-3. Lo extraído se guarda una vez en ai_jobs y lo reusan el prellenado (FT-IA-01) y la sugerencia de plantilla (FT-IA-02) con su jobId: un solo pago del modelo por propuesta. Por qué: Leer la página tres veces triplicaría el costo y podría dar respuestas distintas. Se apoya en RF-ENR-05, RF-MAT-05.
• D-REF-04-4. Con URL, la lista negra se evalúa con la marca leída de la página, traducida al código del catálogo de marcas; si no se puede traducir, la evaluación queda en revisión. Una publicación sin EAN se busca con marca, modelo e imagen, y nunca da coincidencia directa: sólo por confianza. Por qué: El camino URL no puede saltarse la lista negra y las publicaciones viejas suelen no traer EAN. Se apoya en DEC-29, PEN-21, RN-MAT-08.
• D-REF-04-5. La identificación por imagen o URL tiene 15 segundos; si la IA no termina, la evaluación queda RUNNING y avisa con EVALUATION_DONE. Si el modelo no está disponible, el seller sigue por características. Por qué: Lo que tarda es asíncrono con recibo, y una caída de la IA no puede detener el alta. Se apoya en DUD-35, ADR-12.
• D-REF-04-6. En Mercaderías la imagen sólo avisa: si la propuesta trae foto, al enviarla se compara y Compras ve el posible duplicado en su visto bueno; no bloquea. Por qué: Mercaderías pidió la detección a futuro y no definió si bloquea; avisar no frena al proveedor y deja decidir a Compras. Se apoya en PEN-25, RF-MAT-04.

Qué falta decidir

También siguen abiertos: PEN-46, Confirmar si la IA puede validar existencia y buscar fuera con certeza; PEN-53, Confirmar si, sin coincidencia, se usan las imágenes de la página como imágenes del producto.

Fuentes

1. [D] trazabilidad/features/FT-REF-04-matching-por-imagen-y-url.md: la ficha de la épica, con sus historias, reglas y bloqueos.
2. [D] ADR-12 · Un solo sistema: backend compartido y una sola base (sección 3.4).
3. [D] docs/arquitectura/por-epica/base/: piezas, colecciones, eventos y el hilo de punta a punta.
4. [D] docs/arquitectura/omega-a-pim-headless/contratos-api.md: convenciones y endpoints de partida.
5. [D] docs/arquitectura/maquina-de-estados-to-be/propuesta-maquina-de-estados.md §7: estados, tareas y canales.
6. [I] Las decisiones de la sección 9 son del TL sobre esas fuentes.