FT-CAT-01 · Administración del árbol de categorías web

En 30 segundos

El árbol de categorías web es el menú de la tienda: los productos cuelgan de sus hojas. Hoy mover o dar de baja una rama exige exportar, borrar y recargar archivos. Esta épica deja a Category administrarlo en el portal: crear con un asistente que valida nivel y mínimos, aprobar antes de que viaje, mover ramas, desligar sin borrar ni dejar productos huérfanos, cargar en masa con revisión previa y traer el árbol vivo de P360.

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

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 Mover una rama o desligarla sin dejar huérfanos

3.2 Carga masiva con revisión previa

3.3 Carga inicial del árbol desde P360

4. Si algo sale mal

• Se cuelga un nivel 3 de un nivel 1, se pasa del nivel 5 o un nivel 1 no trae isBrand, rootIndex o fechas. La validación responde con el campo que falla y nada se guarda; el asistente lo marca en la pantalla mientras se captura.
• El ID manual ya existe, aunque sólo cambien mayúsculas. Responde 409 con CATEGORY_ID_ALREADY_EXISTS; un ID nunca se cambia ni se reutiliza, porque para la tienda sería otra categoría.
• Desligar o mover a «unlinked» dejaría productos sin ninguna categoría web activa. La confirmación se bloquea y la vista previa lista esos productos; Category los reasigna (o Repoblamiento con FT-CAT-06) y vuelve a confirmar.
• MS-02 no responde la revisión de productos. El movimiento o el desligue responde 503 y no se hace a ciegas; Category lo reintenta más tarde y nada queda a medias.
• Otra persona cambió la rama entre la vista previa y la confirmación. La confirmación responde 409 VERSION_CONFLICT; la pantalla recarga la rama y se vuelve a revisar.

5. APIs

Las que construye esta épica (11)

null

{
  "success": true,
  "data": {
    "category": {
      "id": "catst10045",
      "name": "Camisas de vestir",
      "level": 3,
      "brandSite": "LIVERPOOL",
      "status": "APROBADA",
      "version": 8,
      "modifications": 7
    },
    "history": [
      {
        "at": "2026-10-18T15:04:05Z",
        "actor": "Category (usuario interno)",
        "version": 8,
        "changes": [
          {
            "field": "name.es",
            "before": "Camisas",
            "after": "Camisas de vestir"
          }
        ]
      }
    ],
    "store": {
      "status": "PUBLICADO",
      "sentVersion": 8,
      "acknowledgedAt": "2026-10-18T15:04:06Z",
      "attempts": 1,
      "lastError": null
    }
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "catst10045",
        "name": {
          "es": "Camisas de vestir"
        },
        "parentId": "catst10040",
        "ancestorIds": [
          "catst10001",
          "catst10040"
        ],
        "level": 3,
        "brandSite": "LIVERPOOL",
        "status": "APROBADA",
        "isLeaf": true,
        "restricted": false,
        "version": 8,
        "modifications": 7,
        "publication": {
          "status": "PUBLICADO",
          "version": 8,
          "at": "2026-10-18T15:04:06Z"
        },
        "startDate": "2026-01-01T06:00:00Z",
        "endDate": "2099-12-31T06:00:00Z"
      }
    ],
    "page": 1,
    "size": 50,
    "total": 1
  }
}

null

{
  "success": true,
  "data": {
    "id": "catst10045",
    "name": {
      "es": "Camisas de vestir",
      "en": "Dress shirts"
    },
    "parentId": "catst10040",
    "ancestorIds": [
      "catst10001",
      "catst10040"
    ],
    "level": 3,
    "brandSite": "LIVERPOOL",
    "catalogId": "ICatalog1000",
    "status": "APROBADA",
    "isLeaf": true,
    "startDate": "2026-01-01T06:00:00Z",
    "endDate": "2099-12-31T06:00:00Z",
    "groupType": "NOT_SPECIFIED",
    "sentToFA": true,
    "categoryImage": "/imagenes/categorias/catst10045.jpg",
    "imageUrl": "",
    "googleCategory": "Apparel & Accessories > Clothing > Shirts",
    "megaMenuContent": null,
    "properties": {
      "kioskId": null
    },
    "restriction": null,
    "publication": {
      "status": "PUBLICADO",
      "version": 8,
      "at": "2026-10-18T15:04:06Z"
    },
    "version": 8,
    "modifications": 7,
    "approvedAt": "2026-10-17T18:20:00Z",
    "updatedAt": "2026-10-18T15:04:05Z"
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "catst10045",
        "name": {
          "es": "Camisas de vestir"
        },
        "level": 3,
        "status": "APROBADA",
        "isLeaf": true,
        "children": 0,
        "publication": {
          "status": "PUBLICADO",
          "version": 8
        }
      },
      {
        "id": "catst10046",
        "name": {
          "es": "Camisas de lino"
        },
        "level": 3,
        "status": "CREADA",
        "isLeaf": true,
        "children": 0,
        "publication": null
      }
    ],
    "page": 1,
    "size": 100,
    "total": 2
  }
}

null

{
  "success": true,
  "data": {
    "id": "catst10040",
    "name": {
      "es": "Camisas"
    },
    "level": 2,
    "status": "APROBADA",
    "publication": {
      "status": "PUBLICADO",
      "version": 5
    },
    "children": [
      {
        "id": "catst10045",
        "name": {
          "es": "Camisas de vestir"
        },
        "level": 3,
        "status": "APROBADA",
        "publication": {
          "status": "PUBLICADO",
          "version": 8
        },
        "children": []
      },
      {
        "id": "catst10046",
        "name": {
          "es": "Camisas de lino"
        },
        "level": 3,
        "status": "CREADA",
        "publication": null,
        "children": []
      }
    ]
  }
}

null

{
  "success": true,
  "data": {
    "brandSite": "LIVERPOOL",
    "catalogId": "ICatalog1000",
    "items": [
      {
        "id": "catst10001",
        "name": {
          "es": "Ropa"
        },
        "level": 1,
        "status": "APROBADA",
        "children": 14,
        "publication": {
          "status": "PUBLICADO",
          "version": 12
        }
      },
      {
        "id": "catst10002",
        "name": {
          "es": "Hogar"
        },
        "level": 1,
        "status": "APROBADA",
        "children": 22,
        "publication": {
          "status": "ERROR",
          "version": 9
        }
      }
    ]
  }
}

{
  "parentId": "catst10040",
  "name": {
    "es": "Camisas de lino"
  },
  "startDate": "2026-11-01T06:00:00Z",
  "endDate": "2099-12-31T06:00:00Z",
  "groupType": "NOT_SPECIFIED",
  "sentToFA": true,
  "categoryImage": "/imagenes/categorias/camisas-lino.jpg"
}

{
  "success": true,
  "data": {
    "id": "catst10046",
    "parentId": "catst10040",
    "level": 3,
    "brandSite": "LIVERPOOL",
    "status": "CREADA",
    "isLeaf": true,
    "version": 1,
    "modifications": 0,
    "createdAt": "2026-10-18T15:04:05Z"
  }
}

{
  "name": {
    "es": "Camisas de vestir"
  },
  "categoryImage": "",
  "endDate": "2027-01-31T06:00:00Z"
}

{
  "success": true,
  "data": {
    "id": "catst10045",
    "status": "APROBADA",
    "version": 8,
    "modifications": 7,
    "travelsToStore": true,
    "changes": [
      {
        "field": "name.es",
        "before": "Camisas",
        "after": "Camisas de vestir"
      },
      {
        "field": "categoryImage",
        "before": "/imagenes/categorias/catst10045.jpg",
        "after": ""
      },
      {
        "field": "endDate",
        "before": "2099-12-31T06:00:00Z",
        "after": "2027-01-31T06:00:00Z"
      }
    ]
  }
}

{
  "parentId": "catst10002"
}

{
  "success": true,
  "data": {
    "dryRun": true,
    "categoryId": "catst10040",
    "from": {
      "parentId": "catst10001",
      "level": 2,
      "brandSite": "LIVERPOOL"
    },
    "to": {
      "parentId": "catst10002",
      "level": 2,
      "brandSite": "LIVERPOOL"
    },
    "descendants": 37,
    "levelsRecalculated": 0,
    "products": 4210,
    "productsWithoutOtherActiveCategory": 0,
    "travelsToStore": true,
    "canConfirm": true
  }
}

null

{
  "success": true,
  "data": {
    "dryRun": true,
    "categoryId": "catst10045",
    "subtree": 3,
    "products": 128,
    "orphans": {
      "total": 2,
      "items": [
        {
          "productId": "PRD-0004812",
          "name": "Camisa de lino manga larga",
          "business": "MER"
        },
        {
          "productId": "PRD-0004813",
          "name": "Camisa de lino manga corta",
          "business": "MER"
        }
      ]
    },
    "canConfirm": false
  }
}

{
  "categoryIds": [
    "catst10045",
    "catst10046"
  ],
  "comment": "Rama de camisas para primavera"
}

{
  "success": true,
  "data": {
    "approved": 2,
    "blocked": 0,
    "items": [
      {
        "categoryId": "catst10045",
        "result": "APPROVED",
        "status": "APROBADA",
        "version": 2,
        "travels": "FULL"
      },
      {
        "categoryId": "catst10046",
        "result": "APPROVED",
        "status": "APROBADA",
        "version": 2,
        "travels": "FULL"
      }
    ]
  }
}

Las que usa y construye otra épica (14)

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-CAT-01-1. MS-01 es el único dueño del árbol (categories) y de los sitios, incluido el indicador de publicada de cada categoría, que actualiza con el acuse de MS-09; MS-09 no guarda categorías, sólo el detalle de cada envío. Las pantallas de hoy que llaman al servicio de categorías y a M4 pasan una sola vez al BFF en R1 y esas rutas se apagan con tráfico cero; las de /api/v1 no se conservan. Por qué: Hoy dos servicios escriben el mismo documento y se pisan el estado de publicación. Con un dueño, quien necesita «hoja publicada» (FT-CAT-03, FT-CAT-06, FT-INT-07) pregunta en un solo lugar, como ya fijaba contratos-api §3.1. Se apoya en ADR-12, PD-07, DUD-07.
• D-CAT-01-2. Dos estatus, como acordó el taller: Creada (guardada, no viaja) y Aprobada (viaja); Desligada es un estado de vida aparte. Aprobar es una acción explícita, en lotes de hasta 500, con la capacidad de aprobar de MS-13; puede hacerla quien creó. Una categoría ya aprobada viaja con cada cambio que confirma un perfil autorizado: la vista previa de esa confirmación es su revisión. Por qué: Cumple «mientras no se aprueba no viaja» sin un segundo aprobador que nadie ha definido; pedir aprobación de cada cambio duplicaría trabajo y obligaría a guardar dos versiones de cada categoría. Se apoya en RF-CAT-19, DUD-01, DUD-22.
• D-CAT-01-3. El ID lo genera MS-01 como catst y un consecutivo, con una secuencia que arranca arriba del mayor migrado; no cambia, no se reutiliza y se compara sin mayúsculas. El nivel se calcula del padre (1 a 5, sin saltos) y no se captura. Por qué: Un ID distinto es otra categoría para la tienda y uno reutilizado cuelga productos donde no van; el nivel capturado es la deuda de hoy (0 de 7,733 documentos con nivel). Se apoya en PD-20, RF-CAT-19.
• D-CAT-01-4. Desligar, o mover a «unlinked», vale con hijas, con productos y desde el nivel 1: todo el subárbol pasa a Desligada, la tienda recibe link=false y los productos sólo pierden esa relación; nada se borra. Se bloquea sólo si algún producto se quedaría sin ninguna categoría web activa, hasta reasignarlo. Las fechas sólo controlan la visibilidad: una categoría vencida no se desliga sola ni pierde productos. Por qué: El negocio quiere proteger al producto, no al nodo. Desligar por fecha borraría las relaciones de las categorías de temporada que regresan cada año. Se apoya en PD-28, DMS-60.
• D-CAT-01-5. Las categorías conservan la forma de comando directo con ?dryRun=true e If-Match que fija contratos-api §2.1, en vez de plan y confirmación: cada comando toca una categoría o una rama y su vista previa no se guarda. Lo masivo va por la carga de catálogo (API-01-031), que revisa todo antes de escribir y rechaza el lote si un renglón falla. API-01-045 no se construye: la historia la sirve MS-05 y la compone el BFF (API-BFF-111). Por qué: Respeta la ruta base sin duplicar caminos: un solo mecanismo de carga masiva para todo el catálogo y un solo dueño de la bitácora. Se apoya en ADR-12, DMS-61.
• D-CAT-01-6. Carga inicial: se migra el árbol vivo de la revisión 1 con sus ID tal cual, incluidas las cat que tienen productos o están en árboles activos; no se migra lo que cuelga de Unlinked; los nodos de nivel 6, los pares que sólo difieren en mayúsculas y los huérfanos entran a la cuarentena de MS-03 para que Category decida antes del corte. La carga no publica: la tienda ya tiene esas categorías. Por qué:* Cambiar un ID rompería la tienda; la cuarentena deja visible la deuda sin frenar la carga. PD-20 sigue abierta y aquí se propone cómo cerrarla. Se apoya en PD-20, DEC-ARQ-07, RN-MIG-05.
• D-CAT-01-7. Dentro del PIM las fechas son nativas y en UTC; el texto yyyy-MM-dd HH:mm:ss en hora de Ciudad de México sólo existe en el mensaje a la tienda, que arma MS-09. Por qué: El texto en la base es lo que hoy rompe los filtros por fecha de governance; el contrato con la tienda no cambia. Se apoya en DEC-ARQ-11, DUD-20.
• D-CAT-01-8. El evento de categoría lleva el objeto completo (los campos que viajan, sitio e ID de catálogo ya resueltos) y la lista de cambios, como excepción a la regla de eventos sólo con identificadores. Por qué: Así MS-09 arma el mensaje sin leer la base de Catálogo, y una categoría pesa poco. Se apoya en ADR-12, PD-07.
• D-CAT-01-9. La restricción es un dato de la categoría: documentos, requisitos y si bloquea o avisa. La administra Category con API-01-041 y MS-02 la aplica al ligar productos y al aprobarlos (FT-CAT-03). Por qué: Quien liga un producto necesita ver los requisitos en el momento; guardarlos en otro lado obligaría a reconciliar dos listas. Se apoya en FT-CAT-03, ADR-12.
• D-CAT-01-10. La carga masiva de categorías usa la revisión y la confirmación de la carga de catálogo, pero no abre una solicitud de cambio: aplica como los comandos directos (las nuevas quedan Creadas) y Category las aprueba en lote con API-01-201. Por qué: Las categorías ya tienen su aprobación propia (D-CAT-01-2); una segunda aprobación por la solicitud del catálogo sería doble trabajo para lo mismo. Se apoya en RF-CAT-19, DEC-ARQ-12.

Qué falta decidir

También siguen abiertos: PEN-40, Registrar que las rutas viven en el PIM: MS-01 es su dueño (ADR-12).

Fuentes

1. [D] trazabilidad/features/FT-CAT-01-administracion-arbol-categorias-web.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.