FT-PLT-03 · Listas de valores y modelo canónico con equivalencias por…

En 30 segundos

Muchos atributos se llenan eligiendo de una lista (colores, materiales, marcas). Esta épica gobierna esas listas: cada valor tiene un código único que es lo que guarda el producto, una etiqueta que se puede corregir sin tocar productos y la forma en que lo recibe cada sistema (la tienda, SAP, Marketplace). También resuelve qué pasa cuando el proveedor no encuentra su valor, cómo se retira un valor sin perder lo histórico y cómo se fusionan dos valores moviendo los productos.

• Módulo dueño: MS-01 Catálogo. También participan: MS-02 Producto, MS-07 Ingesta de archivos, MS-14 Avisos y ayuda.
• Etapa C · Configura el catálogo. Recibe «PE-T · Usuario con permisos y bitácora» y entrega «PE-C · Catálogo vigente».
• APIs: construye 9 y usa 10 que construyen otras épicas.
• Eventos: publica 2 y consume 4.

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 El proveedor pide un valor que no está en la lista

3.2 Fusionar valores y mover los productos

3.3 Listas que manda SAP

4. Si algo sale mal

• Se da de alta un código que ya existe en la misma lista. El plan responde 409 ID_ALREADY_EXISTS; el mismo código en otra lista sí se admite, porque la llave es lista más código.
• La lista no acepta valores nuevos (es de SAP o su política es rechazar). La solicitud responde 422 BUSINESS_ERROR con el motivo y los valores parecidos; el proveedor elige uno de ellos o pide el alta del valor a SAP por su área.
• Gobierno de Producto rechaza el valor que pidió el proveedor. MS-14 avisa al proveedor con el motivo y MS-02 deja el campo vacío para que elija otro valor; la propuesta no se pierde.
• Se pide borrar o fusionar un valor que usan productos. El plan muestra cuántos productos y cuántos publicados lo usan y exige confirmar el impacto; si Producto no responde el conteo, el plan no se arma (503 DEPENDENCY_UNAVAILABLE).
• El trabajo de reescritura falla con algunos productos. El recibo de MS-02 dice cuáles quedaron con el código viejo y por qué; el valor fusionado sigue inactivo y apunta al nuevo, así que se reintenta sólo lo pendiente.

5. APIs

Las que construye esta épica (9)

null

{
  "success": true,
  "data": {
    "items": [
      {
        "lovId": "COLORES_LOV",
        "name": {
          "es": "Colores"
        },
        "valueType": "TEXT",
        "masterSystem": "PIM",
        "newValuePolicy": "REQUEST",
        "usedByAttributes": [
          "COLOR_PRINCIPAL"
        ],
        "valueCount": 412,
        "status": "ACTIVE",
        "version": 7
      }
    ],
    "page": 1,
    "size": 50,
    "total": 1
  }
}

null

{
  "success": true,
  "data": {
    "lovId": "COLORES_LOV",
    "name": {
      "es": "Colores",
      "en": "Colors"
    },
    "valueType": "TEXT",
    "masterSystem": "PIM",
    "newValuePolicy": "REQUEST",
    "outputsDeclared": [
      "TIENDA",
      "SAP",
      "MARKETPLACE"
    ],
    "parallelByBusiness": {
      "SUB": "COLORES_LOV"
    },
    "transformedByDictionary": [],
    "status": "ACTIVE",
    "version": 7
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "code": "0700",
        "label": {
          "es": "Azul",
          "en": "Blue"
        },
        "order": 70,
        "synonyms": [
          "azul rey"
        ],
        "status": "ACTIVE",
        "outputs": {
          "TIENDA": "AZUL",
          "SAP": "AZUL",
          "MARKETPLACE": "Azul"
        },
        "externalIds": {
          "ECC": "0700"
        },
        "version": 3
      },
      {
        "code": "0705",
        "label": {
          "es": "Azul marino",
          "en": "Navy blue"
        },
        "order": 71,
        "synonyms": [
          "marino"
        ],
        "status": "ACTIVE",
        "outputs": {
          "TIENDA": "AZUL",
          "SAP": "AZUL MARINO"
        },
        "externalIds": {
          "ECC": "0705"
        },
        "version": 1
      }
    ],
    "page": 1,
    "size": 20,
    "total": 2
  }
}

null

{
  "success": true,
  "data": {
    "lovId": "GENERO_LOV",
    "code": "0031",
    "label": "Infantiles",
    "templates": {
      "count": 12,
      "sample": [
        "EU4-0512",
        "EU4-0518"
      ]
    },
    "rules": {
      "count": 3,
      "types": [
        "ALLOWED_VALUES_BY_ITEM_GROUP"
      ]
    },
    "attributeDefaults": [
      "GENERO"
    ]
  }
}

{
  "operation": "UPDATE",
  "items": [
    {
      "lovId": "COLORES_LOV",
      "version": 7,
      "newValuePolicy": "REQUEST",
      "outputsDeclared": [
        "TIENDA",
        "SAP",
        "MARKETPLACE"
      ]
    }
  ]
}

{
  "success": true,
  "data": {
    "planId": "pln-3b7e22",
    "expiresAt": "2027-01-12T16:20:00Z",
    "requiresApproval": true,
    "items": [
      {
        "lovId": "COLORES_LOV",
        "action": "UPDATE",
        "changes": [
          {
            "path": "outputsDeclared",
            "before": [
              "TIENDA",
              "SAP"
            ],
            "after": [
              "TIENDA",
              "SAP",
              "MARKETPLACE"
            ]
          }
        ]
      }
    ],
    "applyUrl": "/api/v2/catalog-plans/pln-3b7e22/apply"
  }
}

{
  "operation": "UPDATE",
  "items": [
    {
      "code": "0700",
      "version": 3,
      "label": {
        "es": "AZUL"
      },
      "outputs": {
        "TIENDA": "AZUL"
      }
    }
  ]
}

{
  "success": true,
  "data": {
    "planId": "pln-61d0f8",
    "expiresAt": "2027-01-12T16:31:00Z",
    "requiresApproval": true,
    "items": [
      {
        "code": "0700",
        "action": "UPDATE",
        "changes": [
          {
            "path": "label.es",
            "before": "Azul",
            "after": "AZUL"
          }
        ],
        "impact": {
          "products": 1840,
          "publishedProducts": 1210,
          "productsRewritten": 0,
          "republish": true
        }
      }
    ],
    "applyUrl": "/api/v2/catalog-plans/pln-61d0f8/apply"
  }
}

{
  "label": "Azul petróleo",
  "attributeId": "COLOR_PRINCIPAL",
  "productId": "PRD-0004812",
  "templateId": "EU4-0412",
  "business": "MER",
  "comment": "Color del catálogo de la marca"
}

{
  "success": true,
  "data": {
    "requestId": "req-71ab35",
    "status": "PENDING_APPROVAL",
    "changeRequestId": "chg-5d10e2",
    "similarValues": [
      {
        "code": "0705",
        "label": "Azul marino"
      }
    ],
    "receiptUrl": "/api/v2/catalog-receipts/req-71ab35"
  }
}

{
  "fileId": "lov-ecc-20270112-01",
  "system": "ECC",
  "lovId": "MARCAS_ECC_LOV",
  "records": [
    {
      "recordNo": 1,
      "code": "MARCA01",
      "label": "Marca uno",
      "active": true
    },
    {
      "recordNo": 2,
      "code": "MARCA02",
      "label": "Marca dos",
      "active": false
    }
  ]
}

{
  "success": true,
  "data": {
    "fileId": "lov-ecc-20270112-01",
    "applied": 2,
    "rejected": 0,
    "items": [
      {
        "recordNo": 1,
        "result": "CREATED"
      },
      {
        "recordNo": 2,
        "result": "DEACTIVATED"
      }
    ]
  }
}

{
  "changeRequestId": "chg-91b3e0",
  "remaps": [
    {
      "attributeId": "GENERO",
      "fromCode": "GENERO_LOV::0031",
      "toCode": "GENERO_LOV::0030"
    }
  ]
}

{
  "success": true,
  "data": {
    "requestId": "req-6d22f1",
    "status": "ACCEPTED",
    "productsToChange": 2311,
    "receiptUrl": "/api/v2/product-receipts/req-6d22f1"
  }
}

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-PLT-03-1. El producto guarda el código, nunca la etiqueta. Renombrar cambia sólo el valor en MS-01 y avisa LOV_VALUE_CHANGED; MS-02 muestra la etiqueta nueva sin reescribir el producto. Los publicados se republican de forma explícita, con la vista previa de Producto (API-02-039), que la misma pantalla ofrece al aplicarse el cambio. Por qué: Corregir «Azul» a «AZUL» no debe tocar 1,840 productos ni sus versiones. Republicar con vista previa evita mandar miles de productos a los canales sin que nadie lo vea, como ya se decidió para los demás cambios del catálogo (FT-CAT-05). Se apoya en DEC-PLT-03, DMS-04.
• D-PLT-03-2. Las equivalencias por destino viven en el valor: cada valor declara su forma para la tienda, SAP, Marketplace y los demás (con valor y unidad cuando hace falta). MS-02 las resuelve al armar la foto de publicación y ningún adaptador guarda tablas propias. Los diccionarios de talla que ya transforman se migran tal cual y nunca hay dos fuentes para el mismo par lista y destino. Por qué: Capturar una vez y entregar a cada sistema su forma, sin romper SAP, con una sola fuente por transformación. Se apoya en RF-PLA-10, RN-PLA-13, DEC-PLT-08, DUD-34.
• D-PLT-03-3. Cada lista declara su política de valores nuevos. Las listas de SAP nunca aceptan valores del PIM (los crea SAP); las del PIM aceptan solicitudes que aprueba Gobierno de Producto. Nunca se acepta texto libre en un atributo de lista: mientras se decide, el campo queda como «valor solicitado» en el producto y MS-02 lo llena al aprobarse. Por qué: Equilibra no detener el alta con la meta de capturar en listas y no romper SAP con valores sin normalizar. Se apoya en PEN-31, RF-PLA-09.
• D-PLT-03-4. Fuera de alcance quita un valor de toda captura nueva y los productos que ya lo tienen lo conservan; lo inactivo de P360 migra así. El filtro de valores por plantilla vive en la configuración de la plantilla (FT-PLT-06), no en la lista. Por qué: Retirar un valor no debe reescribir lo histórico, y un solo lugar decide qué valores ve cada plantilla. Se apoya en DEC-ARQ-12, DEC-PLT-03.
• D-PLT-03-5. Fusionar valores o moverlos a otro atributo es una solicitud con impacto. Al aprobarse, MS-01 deja el valor fusionado inactivo y apuntando al que lo sustituye, y le pide a MS-02 reescribir los productos en un trabajo asíncrono con recibo (PEDIDA-PLT-03-1). Por qué: El dueño de los productos es MS-02: el catálogo decide la fusión y Producto cambia sus datos, con un reporte de lo que quedó. Se apoya en DEC-ARQ-12, ADR-12.
• D-PLT-03-6. El conteo de productos que usan un valor lo da el plan de borrado o de fusión, que lo pide a MS-02. La consulta de uso de MS-01 (API-01-008) sólo responde lo que está en el catálogo: plantillas, reglas y atributos. Por qué: Un endpoint de MS-01 no compone datos de otro módulo para una pantalla (decisión 19); el conteo sí es necesario para la regla de confirmar el impacto. Se apoya en ADR-12.

Qué falta decidir

También siguen abiertos: PEN-31, Gobierno de Producto confirma la libertad del proveedor: aquí se propone solicitud con aprobación, nunca texto libre; PEN-88, Sesión de detalle del modelo canónico: cómo viaja a SAP un valor con unidad («22 centímetros»).

Fuentes

1. [D] trazabilidad/features/FT-PLT-03-listas-de-valores-y-modelo-canonico.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.