FT-CAT-02 · Publicación de categorías a la tienda

En 30 segundos

El árbol de categorías tiene que llegar a la tienda tal como lo espera hoy, pero sin el broker de P360. Esta épica hace que el publicador de categorías mande cada categoría aprobada con el mismo mensaje de 14 campos, sólo lo que cambió y los desligues como link=false, sin perder ni duplicar nada, y que el corte empiece con un lote pequeño y con forma de regresar.

• Módulo dueño: MS-09 Publicador de categorías. También participan: MS-01 Catálogo, MS-05 Auditoría, MS-14 Avisos y ayuda.
• Etapa 8 · Publicación. Recibe «PE-C · Catálogo vigente» y entrega «PE-9 · Publicado por canal».
• APIs: construye 4 y usa 0 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 Si el bus de eventos falla o la tienda no confirma

3.2 Cambio sólo de nombre, movimiento, desligue o campo vaciado

3.3 Primer corte con lote pequeño y regreso

4. Si algo sale mal

• Llega el mismo evento dos veces o una versión vieja. MS-09 lo omite por su eventId y por categoría y versión, y lo cuenta como duplicado en el detalle de envío; la tienda no recibe nada repetido.
• el bus de eventos falla o no confirma. Reintenta cada 30 s × 2ⁿ, con tope de 15 minutos; al agotar los intentos marca Error con el motivo, devuelve FAILED, MS-01 marca Error en la categoría y MS-14 avisa a Category, que republica con API-01-044.
• La categoría no tiene sitio o su padre no ha llegado a la tienda. No se manda: queda Pendiente mientras espera al padre, o Error «sin sitio»; Category lo ve en su árbol.
• La tienda conserva el valor de un campo vaciado. Se prueba en QA antes del corte (DUD-20); si la tienda no lo borra con texto vacío, se pide el cambio a su equipo antes de encender.
• El primer lote sale mal en la tienda. Se pone el publicador en apagado (los eventos quedan Pendientes y no se pierden) y se vuelve a encender el productor de P360 mientras se corrige (DUD-07).

5. APIs

Las que construye esta épica (4)

{
  "categoryIds": [
    "catst10045"
  ],
  "includeAncestors": true,
  "includeDescendants": false,
  "reason": "La tienda no muestra la categoría"
}

{
  "success": true,
  "data": {
    "requestId": "req-c4e19a",
    "status": "ACCEPTED",
    "categories": 3,
    "receiptUrl": "/api/v2/catalog-receipts/req-c4e19a"
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "categoryId": "catst10045",
        "destination": "TIENDA",
        "status": "PUBLICADO",
        "approvedVersion": 8,
        "sentVersion": 8,
        "messageId": "16234567890123",
        "sentAt": "2026-10-18T15:04:06Z",
        "acknowledgedAt": "2026-10-18T15:04:06Z",
        "attempts": 1,
        "duplicatesSkipped": 1,
        "lastError": null,
        "waitingFor": null
      },
      {
        "categoryId": "catst10046",
        "destination": "TIENDA",
        "status": "PENDIENTE",
        "approvedVersion": 2,
        "sentVersion": null,
        "messageId": null,
        "sentAt": null,
        "acknowledgedAt": null,
        "attempts": 0,
        "duplicatesSkipped": 0,
        "lastError": null,
        "waitingFor": "catst10045"
      }
    ],
    "page": 1,
    "size": 50,
    "total": 2
  }
}

null

{
  "success": true,
  "data": {
    "categoryId": "catst10045",
    "version": 8,
    "messageId": "16234567890123",
    "attributes": {
      "source": "STIBO",
      "application": "catalog-category-publisher",
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "objectId": "catst10045",
      "publishTime": "2026-10-18 09:04:06"
    },
    "body": [
      {
        "id": "catst10045",
        "name": "Camisas de vestir",
        "parent": "catst10040",
        "googleCategory": "Apparel & Accessories > Clothing > Shirts",
        "categoryImage": "",
        "megaMenuContent": null,
        "startDate": "2026-01-01 00:00:00",
        "endDate": "2027-01-31 00:00:00",
        "sentToFA": true,
        "imageUrl": "",
        "link": true,
        "properties": {}
      }
    ],
    "omitted": [
      "brandSite",
      "groupType"
    ],
    "omittedBecause": "No cambiaron en esta versión"
  }
}

null

{
  "success": true,
  "data": {
    "mode": "ALLOWLIST",
    "allowlistSize": 25,
    "pending": 3,
    "inFlight": 0,
    "errors": 0,
    "lastSentAt": "2026-10-18T15:04:06Z",
    "configVersion": "publicador-2026-10-18-01"
  }
}

Las que usa y construye otra épica (0)

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

Ninguna.

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-CAT-02-1. MS-09 se entera sólo por catalog.governance.changed y es el único que escribe al tópico de categorías de la tienda; nadie lo llama por HTTP para publicar. Sus 6 rutas de hoy (API-09-001) no se conservan: se apagan con tráfico cero al encender el suscriptor, en R1. Por qué: Hoy el servicio de categorías llama al publicador sin outbox y, si la llamada falla, la categoría queda guardada pero no llega. Con el evento desde el outbox, guardar y avisar es una sola operación. Se apoya en PD-07, DEC-ARQ-10, ADR-12.
• D-CAT-02-2. Cada quien guarda lo suyo: MS-09 guarda el detalle de cada envío (category_delivery_status: Pendiente, Enviado al publicar, Publicado con la confirmación de el bus de eventos, Error al agotar intentos y Retirado con link=false, más intentos, mensaje y duplicados); MS-01 guarda en la categoría sólo su indicador de publicada (estado y versión), que toma del acuse. Como la confirmación de el bus de eventos no prueba que la tienda lo aplicó, el corte se verifica leyendo el lote en la tienda. Por qué: Hoy dos servicios escriben «publicada» en el mismo documento y uno pisa al otro. Así nadie escribe lo del otro y quien necesita «hoja publicada» pregunta sólo a MS-01, como fija contratos-api §3.1. Se apoya en PD-07, DUD-07.
• D-CAT-02-3. Paridad exacta del mensaje: 14 campos, source=STIBO, sin kioskId en subcategorías, fechas en texto de Ciudad de México y los defectos del broker, que MS-09 reproduce al armar el mensaje (MS-01 guarda valores limpios). La única diferencia a propósito: un campo vaciado viaja vacío para que la tienda lo borre. Por qué: La tienda y su indexador no cambian; el vaciado es lo que la ERF pide y hoy no ocurre. Se apoya en DEC-ARQ-10, DEC-ARQ-11, DUD-20.
• D-CAT-02-4. Sólo lo que cambió, como el broker: department (el sitio) y groupType sólo si cambiaron; un desligue es link=false. El sitio viaja como hoy (LIVERPOOL) y su ID de catálogo (ICatalog1000) va en properties para commercetools, sin cambiar el contrato con la tienda. Por qué: Cumple la petición de mandar el ID de catálogo sin romper a quien hoy filtra por sitio; PEN-148 confirma campo y grafía. Se apoya en PEN-148, RF-CAT-13.
• D-CAT-02-5. Sin pérdidas ni duplicados: descarta por eventId y por categoría más versión ya enviada (y lo cuenta), reintenta cada 30 s × 2ⁿ hasta 15 minutos, y manda a una hija sólo cuando su padre ya está Publicado. La republicación (CATEGORY_REPUBLISH_REQUESTED) sí vuelve a mandar la misma versión. Por qué: La entrega de eventos es al menos una vez; la tienda descarta una categoría cuyo padre no conoce. Se apoya en DUD-07, ADR-12.
• D-CAT-02-6. El corte: el publicador arranca apagado y su modo (apagado, lista permitida, encendido) se fija en la configuración del despliegue, no por API. Apagado no pierde nada: guarda Pendiente y al encender manda la última versión de cada categoría. El productor de P360 se apaga en la misma ventana en que se enciende la lista permitida; regresar es apagar el publicador y volver a encender el de P360. Por qué: Nunca hay dos productores a la vez, como fija DEC-ARQ-10, y un lote pequeño se puede verificar y pausar sin perder cambios. Se apoya en DUD-07, DEC-ARQ-10.

Qué falta decidir

También siguen abiertos: PEN-148, Confirmar con el equipo de la tienda el campo y la grafía del ID de catálogo.

Fuentes

1. [D] trazabilidad/features/FT-CAT-02-publicacion-categorias-product-data-service.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.