FT-REF-01 · Datos de referencia administrables

En 30 segundos

Las reglas de alta, el archivo a SAP y la publicación consultan tablas que no son productos ni plantillas: tallas normalizadas, impuestos y márgenes, excepciones de publicación, proveedores exentos de EAN, la secuencia de variantes. Hoy se cargan con programas de un solo uso y se editan a mano. Esta épica las vuelve diccionarios administrables, cada uno con su llave, su área dueña y su bitácora, cargados tal cual desde P360, y deja los catálogos de SAP como copia de consulta que sólo escribe SAP.

• Módulo dueño: MS-01 Catálogo. También participan: MS-13 Identidad y acceso, MS-02 Producto, MS-03 Migración y convivencia, MS-05 Auditoría, MS-06 Evaluación, MS-07 Ingesta de archivos.
• Etapa C · Configura el catálogo. Recibe «PE-T · Usuario con permisos y bitácora» y entrega «PE-C · Catálogo vigente».
• APIs: construye 8 y usa 11 que construyen otras épicas.
• Eventos: publica 2 y consume 5.

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 Catálogos de SAP y sitios

3.2 Carga tal cual desde P360

3.3 Lo que consulta la captura

4. Si algo sale mal

• La llave no sigue el esquema declarado de la tabla. El plan responde 422 VALIDATION_ERROR con la parte de la llave que falta o sobra; no se guarda nada.
• Alguien intenta editar en el PIM un catálogo de SAP. El plan responde 422 BUSINESS_ERROR: esas listas sólo las escribe la ingesta de MS-07; el cambio se pide a SAP por el área de SAP.
• Llega otra vez el mismo archivo de SAP. La carga es idempotente por archivo y por registro y no duplica nada; si trae otro contenido, responde 409 IDEMPOTENCY_MISMATCH y MS-07 lo deja para revisión.
• La migración trae un diccionario dudoso, vacío o de operación interna. No entra (diccionario 17, Dos, vacíos y de operación) o entra inactivo; ninguna regla lo lee hasta que Gobierno de Producto lo active, y queda en la lista de DUD-34.
• Un módulo no alcanzó a refrescar su copia en memoria. Cada aviso lleva versión: el consumidor aplica en orden y descarta lo viejo; al arrancar vuelve a leer las tablas completas. Ninguna regla lee la base de P360 ni archivos en disco.

5. APIs

Las que construye esta épica (8)

null

{
  "success": true,
  "data": {
    "items": [
      {
        "table": "TALLA_NORMALIZADA",
        "name": {
          "es": "Talla normalizada por marca"
        },
        "keySchema": [
          "marca",
          "talla"
        ],
        "keySeparator": "<::>",
        "valueSchema": [
          {
            "name": "tallaNormalizada",
            "type": "STRING"
          }
        ],
        "ownerArea": "GOBIERNO-PRODUCTO",
        "changesRequireApproval": false,
        "consumers": [
          "MS-02"
        ],
        "entries": 30,
        "activeEntries": 30,
        "status": "ACTIVE",
        "version": 4
      }
    ],
    "page": 1,
    "size": 50,
    "total": 1
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "key": "MARCA01<::>CH",
        "keyParts": {
          "marca": "MARCA01",
          "talla": "CH"
        },
        "values": {
          "tallaNormalizada": "S"
        },
        "active": true,
        "version": 2,
        "updatedAt": "2027-01-10T14:00:00Z",
        "updatedBy": {
          "area": "GOBIERNO-PRODUCTO"
        }
      }
    ],
    "page": 1,
    "size": 100,
    "total": 1
  }
}

{
  "operation": "CREATE",
  "items": [
    {
      "key": "MARCA01<::>XCH",
      "values": {
        "tallaNormalizada": "XS"
      },
      "active": true
    }
  ]
}

{
  "success": true,
  "data": {
    "planId": "pln-0c8a5e",
    "expiresAt": "2027-01-12T17:10:00Z",
    "requiresApproval": false,
    "summary": {
      "create": 1,
      "update": 0,
      "deactivate": 0
    },
    "items": [
      {
        "key": "MARCA01<::>XCH",
        "action": "CREATE"
      }
    ],
    "applyUrl": "/api/v2/catalog-plans/pln-0c8a5e/apply"
  }
}

{
  "fileId": "prov-ecc-20270112-01",
  "system": "ECC",
  "records": [
    {
      "recordNo": 1,
      "supplierId": "PROV-0001",
      "name": "Proveedor uno",
      "supplierType": "NACIONAL",
      "active": true
    }
  ]
}

{
  "success": true,
  "data": {
    "fileId": "prov-ecc-20270112-01",
    "applied": 1,
    "rejected": 0,
    "items": [
      {
        "recordNo": 1,
        "supplierId": "PROV-0001",
        "result": "UPDATED"
      }
    ]
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "code": "LIVERPOOL",
        "departmentCode": "NA",
        "name": "Liverpool",
        "slug": "liverpool",
        "catalogId": "ICatalog1000",
        "status": "ACTIVE",
        "reserved": false,
        "version": 2
      },
      {
        "code": "SUBURBIA",
        "departmentCode": "SB",
        "name": "Suburbia",
        "slug": "suburbia",
        "catalogId": "catalogSB",
        "status": "ACTIVE",
        "reserved": false,
        "version": 1
      },
      {
        "code": "UNLINKED",
        "departmentCode": null,
        "name": "Categorías desligadas",
        "slug": "unlinked",
        "catalogId": null,
        "status": "ACTIVE",
        "reserved": true,
        "version": 1
      }
    ],
    "page": 1,
    "size": 50,
    "total": 15
  }
}

{
  "code": "SITIO15",
  "departmentCode": "S15",
  "name": "Sitio de ejemplo",
  "slug": "sitio-ejemplo",
  "catalogId": "catalogS15"
}

{
  "success": true,
  "data": {
    "code": "SITIO15",
    "status": "ACTIVE",
    "version": 1
  }
}

null

{
  "success": true,
  "data": {
    "code": "LIVERPOOL",
    "departmentCode": "NA",
    "name": "Liverpool",
    "slug": "liverpool",
    "catalogId": "ICatalog1000",
    "status": "ACTIVE",
    "reserved": false,
    "version": 2
  }
}

{
  "name": "Sitio de ejemplo 2",
  "catalogId": "catalogS15",
  "status": "INACTIVE"
}

{
  "success": true,
  "data": {
    "code": "SITIO15",
    "status": "INACTIVE",
    "version": 2
  }
}

Las que usa y construye otra épica (11)

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-REF-01-1. Un solo modelo de diccionario: una definición con llave compuesta declarada (sus partes y el separador), columnas con tipo, área dueña, si sus cambios piden aprobación (por omisión no) y quién lo consume; las entradas tienen baja lógica y las reglas sólo reciben las activas. Por qué: Reemplaza los programas de un solo uso por una tabla que administra su área, con bitácora, y deja la aprobación donde el área la pida (por ejemplo, excepciones). Se apoya en DEC-PLT-08, DUD-34.
• D-REF-01-2. Paridad desde el día uno: se carga tal cual, desde la base de P360 productivo del mismo día, sólo lo que el inventario marca para conservar. No entran el diccionario 17, Dos, los vacíos ni los de operación interna; lo dudoso de DUD-34 entra inactivo hasta que Gobierno de Producto lo active. Por qué: Si una tabla que usa una regla no se migra, el producto se crea mal y nadie ve el error; si se migra una copia vencida, se contradicen dos fuentes. Se apoya en DUD-34, DEC-ARQ-06, PD-19.
• D-REF-01-3. Los catálogos de SAP (marcas, grupos de artículo, impuestos y proveedores) son listas con dueño SAP: sólo las escribe la ingesta de MS-07 (API-01-050 y API-01-052) y el PIM guarda la copia de consulta, sin administrarlas. Suburbia usa los de S4H y Liverpool y Marketplace los de ECC; la lista se elige por negocio en el atributo. Por qué: SAP sigue siendo el maestro de marcas y de proveedores; el PIM sólo los consulta, como propone DUD-21. Se apoya en DUD-21, DUD-23.
• D-REF-01-4. Impuesto y margen viven en diccionarios del PIM por negocio: en Marketplace el indicador es siempre E2 y el multiplicador por indicador es una tabla de P360 que se conserva (G5 = 1.2528). En R1 la pantalla pide los factores por el BFF (API-BFF-105, que junta este diccionario con la lista de impuestos de SAP); desde R2 el margen lo devuelve calculado el plan de valores de MS-02. Por qué: Un solo lugar para la tabla y un cálculo en el servidor con el valor vigente, igual para la pantalla, la carga masiva y la API. Se apoya en RF-PLA-13, RN-PLA-14, DUD-23.
• D-REF-01-5. Las seis tablas de excepciones se conservan separadas para Liverpool y para Suburbia, con sus llaves de P360. MS-01 sólo las guarda; las evalúa FT-FLU-07 en MS-02, con la cascada de hoy y la anulación. Por qué: Un dueño para el dato (MS-01) y otro para la regla que lo usa (MS-02), sin cambiar la cascada en el corte. Se apoya en DUD-34, DEC-PLT-08.
• D-REF-01-6. Lo que hoy el portal pide a P360 por /public/rt (marcas y grupos permitidos, sellers sin EAN, margen por indicador) no se construye: desde R1 la pantalla lo pide por el BFF a la API v2 de MS-01, y lo que es de producto (sellers sin EAN) se lee en MS-02 desde este diccionario. Por qué: Decisión 20 del backend compartido que adopta ADR-12: sin capa de compatibilidad para los fronts; cada pantalla se cambia una sola vez. Se apoya en ADR-12, PD-06.
• D-REF-01-7. MS-02, MS-06, MS-07 y MS-08 consultan los diccionarios desde su copia en memoria: la cargan al arrancar y la refrescan con REFERENCE_TABLE_CHANGED. La secuencia de variantes por plantilla es uno más de estos diccionarios. Por qué: Hoy las reglas leen copias en disco que nadie refresca; con el aviso, todos usan el valor vigente sin consultar la base en cada regla. Se apoya en RSG-52, DEC-PLT-08.
• D-REF-01-8. Los sitios (los 14 banners y el reservado UNLINKED) son datos de referencia del catálogo en la colección brands: los administra Category con API-01-046 a API-01-049, con versión y sin borrado (un sitio que se deja de usar queda inactivo). Esta épica los construye; categorías y regla de sitios sólo los leen. Las marcas comerciales no son sitios: son la lista de SAP. Por qué: La lista oficial de sitios necesita un solo dueño y una sola tabla con sus tres códigos, como propone DUD-21, y no debe confundirse con las 40,910 marcas. Se apoya en DUD-21.

Qué falta decidir

Fuentes

1. [D] trazabilidad/features/FT-REF-01-datos-de-referencia-administrables.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.