FT-CAT-06 · Agrupadores y corrección masiva de categorías con…

En 30 segundos

Cuando miles de productos se quedan sin categoría, o con un agrupador distinto al de la tienda, dejan de verse. Esta épica corrige en masa sólo la categoría, sobre el universo completo y sin tocar otros campos; republica lo corregido para que la tienda lo vuelva a indexar; deja el rastro de cada corrida para revertirla, y avisa cuando la tienda descarta una actualización en lugar de perderla en silencio.

• Módulo dueño: MS-02 Producto. También participan: MS-01 Catálogo, MS-04 Reportes, MS-08 Adaptadores de salida, MS-14 Avisos y ayuda.
• Etapa C · Configura el catálogo. Recibe «PE-9 · Publicado por canal», «PE-C · Catálogo vigente» y entrega «PE-10 · Cambio aprobado».
• APIs: construye 3 y usa 8 que construyen otras épicas.
• Eventos: publica 3 y consume 4.

1. Dónde encaja

Recibe

Entrega

Cambios de estado que hace

Tareas que abre o cierra: Category, Gobierno de Datos.

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 Repoblar o reimportar categorías por archivo

3.2 Revertir una corrida

3.3 La tienda descarta por agrupador distinto

4. Si algo sale mal

• El filtro de la corrida trae fechas. El plan avisa que un filtro de fechas deja casos fuera, como pasó en la primera corrección, y muestra junto el universo sin fecha para comparar; Gobierno de Datos decide antes de confirmar.
• Un producto no se puede resolver. Queda sin cambio y se abre Category con el motivo (sin mapeo o categoría no publicada); la corrida termina con los demás y el resultado lo cuenta aparte.
• Alguien cambió un producto entre la vista previa y la ejecución. Ese producto queda bloqueado en la corrida, porque su versión ya no es la fijada; no se toca y aparece en el resultado para corregirlo a mano.
• La tienda no confirma o rechaza la publicación. El canal queda Enviado y, si no llega señal de la tienda o llega un rechazo, pasa a Error con el motivo; se republica desde el resultado de la corrida y FT-RAC-08 vigila que los visibles regresen.
• La corrida bajó los productos visibles. Se revierte con la reversa común de corridas: regresa la categoría anterior de cada producto, deja como conflicto lo que cambió después y republica.

5. APIs

Las que construye esta épica (3)

{
  "universe": {
    "filters": [
      {
        "field": "classification.webCategoryIds",
        "op": "IS_EMPTY"
      },
      {
        "field": "status",
        "op": "IN",
        "values": [
          "APROBADO"
        ]
      }
    ]
  },
  "sources": [
    "LAST_PUBLISHED",
    "MAPPING"
  ],
  "republish": true,
  "comment": "Productos sin categoría tras la caída de visibles"
}

{
  "success": true,
  "data": {
    "planId": "pln-4f0d27",
    "expiresAt": "2026-10-18T17:35:00Z",
    "universe": {
      "total": 23104,
      "dateFilters": false
    },
    "summary": {
      "resolved": 21876,
      "bySource": {
        "LAST_PUBLISHED": 19410,
        "MAPPING": 2466
      },
      "unresolved": 1228,
      "unresolvedReasons": {
        "NO_MAPPING": 1011,
        "CATEGORY_NOT_PUBLISHED": 217
      }
    },
    "onlyField": "classification.webCategoryIds",
    "republish": {
      "channel": "TIENDA",
      "scope": "CATEGORIES"
    },
    "applyUrl": "/api/v2/product-plans/pln-4f0d27/apply",
    "warnings": []
  }
}

null

{
  "success": true,
  "data": {
    "jobId": "job-8d21",
    "status": "DONE",
    "launchedBy": {
      "area": "GOBIERNO-DATOS"
    },
    "launchedAt": "2026-10-18T17:02:00Z",
    "finishedAt": "2026-10-18T17:21:00Z",
    "universe": 23104,
    "corrected": 21876,
    "unresolved": 1228,
    "categoryTasksOpened": 1228,
    "publication": {
      "sent": 21876,
      "published": 21490,
      "error": 386
    },
    "revertible": true,
    "links": {
      "items": "/api/v2/products/category-corrections/job-8d21?view=items",
      "revert": "/api/v2/publications/job-8d21/revert/plans"
    }
  }
}

{
  "structure": "WEB_CATEGORIES",
  "removeCategoryIds": [
    "catst10045",
    "catst10046",
    "catst10047"
  ],
  "page": 1,
  "size": 50
}

{
  "success": true,
  "data": {
    "productsInCategories": 128,
    "wouldLoseAllWebCategories": 2,
    "items": [
      {
        "productId": "PRD-0004812",
        "name": "Camisa de lino manga larga",
        "business": "MER",
        "status": "APROBADO",
        "activeWebCategories": [
          "catst10045"
        ]
      },
      {
        "productId": "PRD-0004813",
        "name": "Camisa de lino manga corta",
        "business": "MER",
        "status": "APROBADO",
        "activeWebCategories": [
          "catst10046"
        ]
      }
    ],
    "page": 1,
    "size": 50,
    "total": 2
  }
}

Las que usa y construye otra épica (8)

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-06-1. La corrección masiva es una corrida de MS-02 con plan: el plan cuenta el universo con un filtro sin fechas y dice cuántos se resuelven, con qué fuente y cuántos no; al confirmar corre como trabajo asíncrono y responde con el recibo. Por qué: La primera corrección falló por un filtro de fechas y dejó casos fuera; quitarlo devolvió a un seller a sus 1,355 visibles. Se apoya en DEC-93, RF-CAT-15.
• D-CAT-06-2. Actualización parcial: la corrida sólo toca las categorías web del producto, con la versión fijada al confirmar; guarda el antes y el después de cada producto, y a la tienda sólo viaja la categoría. Por qué: Se pidió revisar que una corrección no sobrescriba otro campo; un trabajo que sólo puede escribir un campo lo garantiza. Se apoya en RF-CAT-15, DEC-92.
• D-CAT-06-3. Fuentes de la categoría, en orden: la última categoría que la tienda tenía publicada y, si no hay, el mapeo de la plantilla (el mismo de FT-CAT-03). Lo que no se resuelve abre Category con su motivo. La corrida masiva no usa IA. Por qué: Lo no resuelto pasa a la category manager, y la masiva categoriza sin IA, como se acordó. Se apoya en DEC-92, DEC-61.
• D-CAT-06-4. Cada producto corregido se republica solo, con una publicación de sólo categorías (como SEND_CATIDS de FT-INT-07) que manda la lista completa de categorías y retira las que ya no tiene. Enviado es cuando el adaptador confirma la entrega; Publicado, cuando hay señal del lado de la tienda. FT-RAC-08 vigila que los visibles regresen. Por qué: Insertar la categoría en la base dejó productos apagados hasta republicar; además la tienda conserva el valor anterior si sólo se vacía un campo. Se apoya en RF-PUB-07, RN-PUB-02, DUD-20.
• D-CAT-06-5. La corrección la lanza el dueño del dato (Gobierno de Datos o Category): no pasa por Revisión del cambio ni por En modificación. El producto sigue Aprobado y sólo su canal de tienda pasa de Publicado a Enviado. Por qué: La revisión del cambio existe para cambios de otros sobre datos ajenos; aquí el cambio es del dueño y sólo de la categoría. Se apoya en FT-PRD-05, RF-PUB-07.
• D-CAT-06-6. Una sola mecánica de corridas en MS-02, la de FT-INT-07: la corrección se revierte con la reversa común (API-02-403), que regresa el antes guardado, deja como conflicto lo que cambió después y republica. Por qué: Dos reversas para dos tipos de corrida duplicarían la misma capacidad; en el Remaster se revirtieron 3 días de repoblamiento. Se apoya en FT-INT-07, RF-CAL-13.
• D-CAT-06-7. Repoblar categorías por archivo (SKU, título y categoría web) y exportar, editar e importar por SKU van por la carga masiva con su perfil y la publicación de sólo categorías, como el archivo de repoblamiento de FT-INT-07. Un renglón con una categoría no publicada o vacía se rechaza solo, sin depender de la completitud. Por qué: Un solo camino de archivo para el producto; un segundo importador sólo para categorías duplicaría reglas. Se apoya en FT-INT-07, DEC-93.
• D-CAT-06-8. Agrupador es la familia (el genérico con sus variantes) con la que la tienda agrupa. Si el acuse dice que la tienda descartó la actualización por agrupador distinto, el canal queda en Error con el motivo y se abre Gobierno de Datos con el tipo de caso; la acción por omisión es republicar la familia completa. Nunca se descarta en silencio. Por qué: Hoy unos 700 mil productos de Marketplace conservan el agrupador antiguo sin aviso, y nadie ha definido qué es el agrupador. Se apoya en PEN-112, RN-CAT-03, DEC-74, RF-CAT-14.

Qué falta decidir

También siguen abiertos: PEN-112, Gobierno de Datos define qué es el agrupador y la acción por tipo de caso (aquí arranca como la familia y republicarla completa); PEN-123, Confirmar si el universo de los 23 mil sin categoría es el mismo que el de los no indexados.

Fuentes

1. [D] trazabilidad/features/FT-CAT-06-agrupadores-y-correccion-masiva.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.