FT-PRD-03 · EAN

En 30 segundos

Un EAN (el código de barras) no puede repetirse dentro de un negocio, y hoy el proveedor se entera tarde y libera un EAN ocupado con tickets y formularios. Esta épica revisa el EAN en cuanto se captura (formato, dígito verificador, tipo y si ya existe), dice qué hacer si ya está en otro negocio, lleva la liberación dentro del PIM con su estado a la vista y deja cambiar de negocio a un producto sin perder su historia.

• Módulo dueño: MS-02 Producto. También participan: MS-01 Catálogo, MS-06 Evaluación, MS-14 Avisos y ayuda.
• Etapa 3 · Captura. Recibe «PE-3 · Plantilla asignada» y entrega a otras épicas.
• APIs: construye 4 y usa 10 que construyen otras épicas.
• Eventos: publica 5 y consume 1.

1. Dónde encaja

Recibe

Entrega

Cambios de estado que hace

Tareas que abre o cierra: Gobierno de Datos.

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 Liberar un EAN en uso

3.2 Cambiar de negocio sin perder la historia

3.3 Mientras P360 viva, P360 quita un EAN

4. Si algo sale mal

• Dos propuestas guardan el mismo EAN en el mismo negocio al mismo tiempo. El índice único del registro deja pasar sólo la primera confirmación; la segunda recibe 422 con «El código EAN ya existe en catalogación para este negocio» y la opción de pedir su liberación.
• Evaluación (MS-06) no responde cuando el EAN existe en otro negocio. La revisión no bloquea la captura: responde que el EAN existe en el otro negocio y que la decisión se confirma al enviar; la Validación automática (FT-RAC-01) vuelve a preguntar antes del visto bueno.
• Compras no decide la liberación. La solicitud sigue «solicitada» y la propuesta sigue en Borrador; MS-14 le recuerda a Compras cada semana. Si vence el plazo de la propuesta (FT-PRD-04), la propuesta se cancela y la solicitud se cancela con ella, como hoy al eliminar la propuesta.
• El producto que tenía el EAN ya tiene SKU en SAP. Al autorizar, el EAN pasa a la propuesta en el PIM y se abre una tarea de Gobierno de Datos para dar de baja o descontinuar ese EAN en SAP. Si después llega de SAP un archivo que intenta devolver ese EAN al producto anterior, no se aplica en silencio: queda en el recibo y en la misma tarea.
• El negocio nuevo ya tiene uno de los EAN del producto. El plan del cambio de negocio sale bloqueado con el EAN que choca; no se mueve nada hasta resolverlo con una liberación.

5. APIs

Las que construye esta épica (4)

{
  "business": "MER",
  "ownerId": "PROV-0001",
  "productId": "PRD-0004812",
  "eans": [
    "7501234567923",
    "7501234567894",
    "7509876543213",
    "7501112223330"
  ]
}

{
  "success": true,
  "data": {
    "items": [
      {
        "ean": "7501234567923",
        "valid": true,
        "type": "HE",
        "freeInBusiness": true
      },
      {
        "ean": "7501234567894",
        "valid": false,
        "code": "CHECK_DIGIT",
        "message": "El dígito verificador no corresponde"
      },
      {
        "ean": "7509876543213",
        "valid": true,
        "type": "HE",
        "freeInBusiness": false,
        "conflict": {
          "business": "MER",
          "sameBusiness": true
        },
        "nextStep": "PEDIR_LIBERACION",
        "message": "El código EAN ya existe en catalogación para este negocio; puedes pedir su liberación"
      },
      {
        "ean": "7501112223330",
        "valid": true,
        "type": "HE",
        "freeInBusiness": true,
        "conflict": {
          "business": "MKP",
          "sameBusiness": false
        },
        "nextStep": "PEDIR_LIBERACION",
        "decisionFrom": "MS-06",
        "message": "EAN ocupado por Marketplace: valida su liberación con tu comprador"
      }
    ]
  }
}

{
  "action": "REQUEST",
  "ean": "7509876543213",
  "business": "MER",
  "forProductId": "PRD-0004812",
  "forVariantId": "VAR-0004812-02",
  "comment": "El producto anterior se descontinuó"
}

{
  "success": true,
  "data": {
    "planId": "pln-e0a118",
    "expiresAt": "2026-10-18T17:15:00Z",
    "release": {
      "ean": "7509876543213",
      "business": "MER",
      "heldBy": {
        "productId": "PRD-0001907",
        "status": "APROBADO",
        "hasSku": true
      },
      "approver": {
        "area": "COMPRAS-HOGAR"
      },
      "directRule": null,
      "willBe": "SOLICITADA"
    },
    "applyUrl": "/api/v2/product-plans/pln-e0a118/apply"
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "releaseId": "rel-3301",
        "ean": "7509876543213",
        "business": "MER",
        "status": "SOLICITADA",
        "requestedBy": {
          "ownerId": "PROV-0001"
        },
        "forProductId": "PRD-0004812",
        "heldBy": {
          "productId": "PRD-0001907",
          "hasSku": true
        },
        "approverArea": "COMPRAS-HOGAR",
        "requestedAt": "2026-10-18T16:47:00Z",
        "decidedAt": null,
        "rule": null
      }
    ],
    "page": 1,
    "size": 50,
    "total": 1
  }
}

{
  "targetBusiness": "MER",
  "newOwnerId": "PROV-0001",
  "reason": "Mercaderías empieza a comprar el producto"
}

{
  "success": true,
  "data": {
    "planId": "pln-9a7c42",
    "expiresAt": "2026-10-18T17:20:00Z",
    "productId": "PRD-0004812",
    "from": "MKP",
    "to": "MER",
    "keeps": [
      "productId",
      "webCategoryIds",
      "history",
      "storeKey"
    ],
    "eans": [
      {
        "ean": "7501234567893",
        "from": "MKP",
        "to": "MER",
        "conflict": null
      }
    ],
    "missingForTarget": [
      {
        "attributeId": "NUM_PROVEEDOR",
        "section": "DATOS_BASICOS"
      },
      {
        "attributeId": "GRUPO_ARTICULOS",
        "section": "DATOS_BASICOS"
      }
    ],
    "status": {
      "from": "APROBADO",
      "to": "EN_MODIFICACION"
    },
    "opensTasks": [
      "GOBIERNO_DE_DATOS"
    ],
    "applyUrl": "/api/v2/product-plans/pln-9a7c42/apply"
  }
}

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

Publica

Consume

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-PRD-03-1. La revisión del EAN es de MS-02 y es una sola: formato, dígito verificador, tipo de código (IC, EE, HE…) y unicidad por negocio. La usan la captura, la carga masiva y la API de terceros con el mismo código. Por qué: Hoy la validación llega tarde y en cascada de tres chequeos con un índice en archivo plano que falla en silencio; ADR-12 deja la validación en el dueño del dato. Se apoya en DEC-PRD-08, RF-ALT-04, ADR-12.
• D-PRD-03-2. La unicidad por negocio la garantiza el índice único de identifier_registry, escrito en la misma transacción que el producto: de dos altas simultáneas con el mismo EAN y negocio, sólo una gana. La revisión en línea no reserva; reserva el guardado. Por qué: Reservar al teclear dejaría EAN bloqueados por capturas abandonadas; el índice único cierra la carrera sin bloqueos largos. Se apoya en DEC-PRD-04.
• D-PRD-03-3. El mensaje de convivencia entre negocios (multioferta, stockout o liberar) sale de la decisión por negocio de Evaluación (MS-06), la misma que usa la identificación previa al alta; MS-02 no copia esa tabla. Por qué: Una regla, un dueño: la decisión ante una coincidencia es de MS-06 (FT-FLU-03). Se apoya en RN-MAT-11, FT-FLU-03.
• D-PRD-03-4. La liberación vive en el PIM como una solicitud con estado (solicitada, realizada, rechazada o cancelada) guardada en el registro del EAN. Autoriza Compras del área del producto que ocupa el EAN; en Marketplace, Gobierno de Datos. Liberar marca el EAN anterior como liberado; nunca lo borra. Por qué: Elimina el ticket y el formulario, deja el rastro de quién liberó qué y le da al proveedor y al seller el estado sin preguntar. Se apoya en RF-ALT-04, RN-ALT-06, S29-RF-06, DUD-22.
• D-PRD-03-5. Las reglas de liberación directa se configuran en el motor de MS-02 (tabla EAN_RELEASE_RULES). La de arranque: el EAN lo ocupa otra propuesta del mismo dueño que todavía no tiene SKU. Pasar un artículo a descontinuado no libera su EAN por sí solo. Por qué: Libera sin esperar lo que no tiene riesgo y respeta lo que pidió el taller: antes de liberar un descontinuado se valida, por ejemplo, el inventario. Se apoya en RN-ALT-06, RN-ALT-08.
• D-PRD-03-6. En Suburbia la unicidad aplica igual y la liberación también, con Compras de Suburbia, hasta que se decida otra cosa. Por qué: Un solo flujo para los tres negocios; excluir a Suburbia obligaría a mantener el ticket sólo para ella. Se apoya en PEN-10, DEC-03.
• D-PRD-03-7. Sólo Gobierno de Datos, por permiso sobre el grupo de atributos del EAN, o el flujo de liberación cambian un EAN; el proveedor o seller lo captura mientras la propuesta está en Borrador y sin SKU. Por qué: Protege la llave sin frenar la captura; la matriz por rol vive en el motor de MS-02 con los roles del directorio. Se apoya en DUD-22, ADR-12.
• D-PRD-03-8. El cambio de negocio es un comando propio: conserva identificador, catalogación, historial y la llave de la tienda; mueve los EAN al registro del negocio nuevo (si alguno choca no se aplica) y pide lo que falta con una tarea de Gobierno de Datos, sin borrar nada. Si estaba aprobado, pasa a En modificación y la tienda conserva lo publicado hasta terminar. Por qué: Liberar y volver a catalogar pierde la relevancia que el producto ganó en la página; un comando explícito deja rastro y no se confunde con una edición. Se apoya en S29-RF-07, PD-29.
• D-PRD-03-9. Mientras P360 viva, su middleware quita EAN con el adaptador upc-eans (API-02-074, de FT-PRD-09) y MS-02 lo aplica como liberación en el registro; se borra con P360 en R3. Por qué: Es el único adaptador que queda por la decisión 20 que adopta ADR-12; sin él, una baja en P360 dejaría el EAN ocupado en el PIM. Se apoya en ADR-12.

Qué falta decidir

También siguen abiertos: PEN-10, Confirmar si la liberación en la herramienta aplica a Suburbia (aquí arranca igual que en Mercaderías).

Fuentes

1. [D] trazabilidad/features/FT-PRD-03-ean-unicidad-validacion-liberacion.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.