FT-CAT-03 · Categorización de productos

En 30 segundos

Un producto sin categoría web no se ve en la tienda, y hoy todas las categorías se asignan a mano, exportando y recargando archivos. Esta épica asigna la categoría: el seller o el proveedor la elige buscando en el árbol o, al enviar la captura, un agente la calcula con el mapeo de su plantilla o con la IA. Antes de aprobar, la categoría se confirma sola si la confianza alcanza; si no, la revisa Category desde su bandeja.

• Módulo dueño: MS-02 Producto. También participan: MS-01 Catálogo, MS-06 Evaluación, MS-15 IA y enriquecimiento.
• Etapa 7 · Calidad y categoría. Recibe «PE-C · Catálogo vigente», «PE-6 · SKU asignado» y entrega «PE-8 · Aprobado».
• APIs: construye 3 y usa 13 que construyen otras épicas.
• Eventos: publica 4 y consume 1.

1. Dónde encaja

Recibe

Entrega

Cambios de estado que hace

Tareas que abre o cierra: Category.

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 Al enviar, el agente calcula la categoría

3.2 El seller elige la categoría en el árbol

3.3 Mantener el mapeo plantilla ↔ categoría

4. Si algo sale mal

• La plantilla no tiene mapeo y la IA no alcanza el umbral. Se guarda la mejor sugerencia marcada como automática con su confianza; al aprobar QA se abre Category con las sugerencias y no se aprueba hasta que Category confirme.
• La categoría se desligó o dejó de estar publicada después de asignarla. La revisión del paso 2 lo detecta y abre Category con el motivo «la categoría ya no está publicada»; el producto no se aprueba con una categoría que la tienda no tiene.
• La IA (MS-15) no responde. Se usa sólo el mapeo; si tampoco hay mapeo, el producto sigue sin categoría y Category recibe la tarea con el motivo «sin sugerencia».
• El seller elige una categoría restringida sin sus documentos. El plan le muestra los requisitos; según lo que diga Catálogo, bloquea o avisa, y el candado de publicación (FT-RAC-01) no deja aprobar sin cumplirlos.
• Category no atiende la tarea a tiempo. El reloj de plazos de MS-02 le recuerda y, al vencer, la pasa a la cola del líder de Category; el seller ve «En revisión de categoría» con su fecha.

5. APIs

Las que construye esta épica (3)

{
  "siteIds": [
    "LIVERPOOL"
  ],
  "max": 3
}

{
  "success": true,
  "data": {
    "productId": "PRD-0004812",
    "templateId": "EU4-0412",
    "suggestions": [
      {
        "categoryId": "catst0012345",
        "site": "LIVERPOOL",
        "path": "Ropa > Hombre > Playeras",
        "source": "MAPPING",
        "confidence": 1.0,
        "meetsThreshold": true,
        "restricted": false
      },
      {
        "categoryId": "catst0012390",
        "site": "LIVERPOOL",
        "path": "Deportes > Ropa deportiva > Playeras",
        "source": "AI",
        "confidence": 0.71,
        "meetsThreshold": false,
        "restricted": false
      }
    ]
  }
}

{
  "items": [
    {
      "productId": "PRD-0004812",
      "version": 9
    }
  ],
  "structure": "WEB_CATEGORIES",
  "op": "ASSIGN",
  "nodeIds": [
    "catst0012345"
  ],
  "source": "MANUAL"
}

{
  "success": true,
  "data": {
    "planId": "pln-c73a10",
    "expiresAt": "2026-10-18T17:05:00Z",
    "summary": {
      "ok": 1,
      "blocked": 0,
      "withWarnings": 1
    },
    "items": [
      {
        "productId": "PRD-0004812",
        "result": "OK",
        "before": [],
        "after": [
          "catst0012345"
        ],
        "site": "LIVERPOOL",
        "path": "Ropa > Hombre > Playeras",
        "restriction": null,
        "warnings": [
          {
            "code": "OUTSIDE_MAPPING",
            "message": "No es la categoría del mapeo de la plantilla; Category la revisará"
          }
        ]
      }
    ],
    "applyUrl": "/api/v2/product-plans/pln-c73a10/apply"
  }
}

{
  "templateId": "EU4-0412",
  "business": "MKP",
  "siteIds": [
    "LIVERPOOL"
  ]
}

{
  "success": true,
  "data": {
    "templateId": "EU4-0412",
    "business": "MKP",
    "categories": [
      {
        "categoryId": "catst10045",
        "siteId": "LIVERPOOL",
        "path": "Ropa > Caballero > Camisas de vestir",
        "isLeaf": true,
        "publication": {
          "status": "PUBLICADO",
          "version": 8
        },
        "restricted": false
      }
    ],
    "rule": {
      "ruleId": "rul-088120",
      "type": "TEMPLATE_WEB_CATEGORY",
      "version": 3
    }
  }
}

Las que usa y construye otra épica (13)

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-03-1. La categoría no es un estado. El agente la calcula al enviar la captura, antes del score y del SKU: primero con el mapeo de la plantilla en Catálogo y, si no hay mapeo, con la sugerencia de la IA de MS-15. Queda marcada como automática, con su fuente y su confianza. Por qué: Es lo que acordó el taller: categoría calculada por mapeo tras capturar todo, sin estado propio. Se apoya en DEC-25, RN-CAT-07, RN-CAT-08.
• D-CAT-03-2. Un producto no se aprueba sin al menos una categoría web que sea hoja y esté publicada. Por qué: Sin categoría no se ve: 23 mil productos sin categoría tumbaron los visibles de un seller. Conserva lo que hoy exige la etapa Category de P360. Se apoya en PD-22, RF-PUB-06, RN-PUB-01.
• D-CAT-03-3. Se conserva la tarea Category, pero sólo se abre al aprobar QA cuando hace falta: confianza bajo el umbral, plantilla sin mapeo, categoría elegida fuera del mapeo, categoría restringida o producto en la muestra de revisión (por negocio; arranca en 5 %). Mientras está abierta, bloquea el Aprobado. Por qué: Revisar todo repetiría el cuello de botella de hoy; no revisar nada deja pasar errores de la IA. La muestra cumple «revisar un porcentaje». Se apoya en P-37, PEN-40.
• D-CAT-03-4. El mapeo plantilla ↔ categoría web es una regla de clasificación de Catálogo (tipo nuevo en governance_rules), con carga inicial para todas las categorías base; MS-02 la consulta con caché y no la copia. Por qué: Plantillas, categorías y reglas de clasificación ya son de Catálogo; el mapeo hoy no existe y nace vacío. Se apoya en RF-CAT-05, ADR-12.
• D-CAT-03-5. Sólo hojas y sólo en el padre: la variante hereda la categoría. Un producto puede tener una categoría por sitio (por ejemplo, Liverpool y Suburbia); una segunda en el mismo sitio sólo con permiso de Category. Desligar borra sólo la relación. Por qué: Paridad con P360 y control central de la doble categoría que pidió el taller. Se apoya en PEN-43, DMS-36.
• D-CAT-03-6. Si ninguna categoría sirve, el seller no se detiene: deja su propuesta en texto y se abre Category, que asigna una existente o pide la nueva en Catálogo (FT-CAT-01). Sin tickets. Por qué: Hoy se levanta un ticket y el producto espera; la tarea deja rastro y no frena la captura. Se apoya en PEN-15, DEC-27.
• D-CAT-03-7. Una categoría restringida trae en Catálogo sus documentos, sus requisitos y si bloquea o avisa; al elegirla, el plan los muestra y el candado de publicación no deja aprobar sin cumplirlos. Por qué: Evita publicar y retirar después productos como medicamentos con receta. Se apoya en FT-CAT-01, RF-CAL-05.
• D-CAT-03-8. El umbral de confianza de la categoría vive en la configuración de MS-15 y el porcentaje de la muestra, en la configuración del motor de MS-02 (SWITCHES). Por qué: Cada modelo de IA califica su resultado con el umbral de su tarea; la muestra es una regla de flujo, no de IA. Se apoya en PEN-40, DUD-35.

Qué falta decidir

También siguen abiertos: PEN-40, Confirmar quién revisa y qué porcentaje de lo asignado por proveedor o IA (aquí arranca en 5 %); PEN-15, Definir cómo se crea una categoría nueva cuando ninguna sirve; PEN-43, Fijar la regla de homologación de la doble categoría; PEN-41, Medir el parecido entre la taxonomía de plantillas y el árbol web, que sostiene el mapeo; PEN-130, Confirmar si la «categoría» que se elige para la carga masiva es la del árbol web.

Fuentes

1. [D] trazabilidad/features/FT-CAT-03-categorizacion-de-productos.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.