FT-INT-07 · Repoblamiento masivo de productos hacia la tienda

En 30 segundos

A veces hay que volver a mandar a la tienda productos que ya están publicados, para corregir el título, la clasificación web o el sitio, sin regresarlos al flujo. Esta épica hace el repoblamiento en masa con vista previa, resultado por producto con la evidencia de lo enviado y la posibilidad de revertir una corrida que salió mal. También atiende la tarea de Repoblamiento: mandar el producto a Compras, al proveedor o aprobarlo.

• Módulo dueño: MS-02 Producto. También participan: MS-05 Auditoría, MS-08 Adaptadores de salida.
• Etapa 9 · Modificación. Recibe «PE-9 · Publicado por canal» y entrega «PE-9 · Publicado por canal», «PE-10 · Cambio aprobado».
• APIs: construye 3 y usa 9 que construyen otras épicas.
• Eventos: publica 6 y consume 3.

1. Dónde encaja

Recibe

Entrega

Cambios de estado que hace

Tareas que abre o cierra: Repoblamiento, Revisión del cambio, Corrección.

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 La tarea de Repoblamiento

3.2 Archivo de repoblamiento: SKU, título y clasificación web

3.3 Revertir una corrida

4. Si algo sale mal

• Un producto cambió entre la vista previa y la confirmación. Queda BLOCKED en el trabajo con el motivo y no se manda; los demás siguen. Repoblamiento pide otra vista previa para ese producto.
• A un producto le falta nombre, plantilla, imagen principal congelada o SKU. No se envía y su motivo queda en la vista previa y en el CSV de resultado; la categoría web no se exige para repoblar.
• La tienda no contesta o contesta algo que no se reconoce. El producto queda REVIEW en el trabajo y su canal en Error; no se reenvía solo y se republica con un trabajo nuevo. «Aceptado» sólo quiere decir que el destino leyó el mensaje.
• La corrida baja los productos visibles. Se revierte con API-02-403: vuelven los valores anteriores de los campos planchados y se republica; lo que cambió después de la corrida no se toca y queda como conflicto para revisar a mano.
• El universo es muy grande (cientos de miles de productos). La lista va en un archivo, el trabajo se parte en lotes de 1,000 productos por XML con un ritmo por destino configurable, y la vista previa dice cuántos lotes son y cuánto tardaría.

5. APIs

Las que construye esta épica (3)

{
  "operation": "REPOPULATE",
  "selection": {
    "productIds": [
      "PRD-0004812",
      "PRD-0004890"
    ]
  },
  "channels": [
    "TIENDA"
  ],
  "reason": "Corregir el título sin marca en la tienda"
}

{
  "success": true,
  "data": {
    "planId": "pln-r3p001",
    "expiresAt": "2026-10-18T16:40:00Z",
    "operation": "REPOPULATE",
    "channels": [
      "TIENDA"
    ],
    "includeCatIds": false,
    "includesOms": false,
    "includesMarketplace": false,
    "changesProductStatus": false,
    "summary": {
      "requested": 2,
      "eligible": 1,
      "notEligible": 1,
      "notFound": 0,
      "batches": 1
    },
    "items": [
      {
        "productId": "PRD-0004812",
        "sku": "1000004812",
        "business": "MER",
        "version": 9,
        "contentHash": "sha256:4f1d9a0c",
        "channels": [
          {
            "channel": "TIENDA",
            "sites": [
              "LIVERPOOL"
            ],
            "eligible": true
          }
        ]
      },
      {
        "productId": "PRD-0004890",
        "sku": "1000004890",
        "business": "MER",
        "version": 4,
        "channels": [
          {
            "channel": "TIENDA",
            "eligible": false,
            "reasons": [
              {
                "code": "MAIN_IMAGE_NOT_FROZEN",
                "message": "La variante VAR-0004890-01 no tiene imagen principal congelada"
              }
            ]
          }
        ]
      }
    ],
    "businessFingerprint": "MER:2",
    "applyUrl": "/api/v2/product-plans/pln-r3p001/apply"
  }
}

null

{
  "success": true,
  "data": {
    "jobId": "job-9c1e",
    "operation": "REPOPULATE",
    "status": "DONE_WITH_ERRORS",
    "createdAt": "2026-10-18T16:12:00Z",
    "finishedAt": "2026-10-18T16:19:40Z",
    "requestedBy": {
      "userId": "usr-20931",
      "role": "Repoblamiento"
    },
    "reason": "Corregir el título sin marca en la tienda",
    "universe": {
      "source": "productIds",
      "count": 2
    },
    "channels": [
      "TIENDA"
    ],
    "progress": {
      "total": 2,
      "accepted": 1,
      "queued": 0,
      "failed": 0,
      "review": 0,
      "blocked": 1
    },
    "items": [
      {
        "productId": "PRD-0004812",
        "sku": "1000004812",
        "channel": "TIENDA",
        "version": 9,
        "result": "ACCEPTED",
        "attempt": 1,
        "destinationResponse": "Se procesó correctamente",
        "evidence": {
          "xmlRef": "evidencias/publicaciones/2026/10/18/job-9c1e-lote-001.xml",
          "sha256": "9f2c7e11a04b"
        }
      },
      {
        "productId": "PRD-0004890",
        "sku": "1000004890",
        "channel": "TIENDA",
        "version": 5,
        "result": "BLOCKED",
        "reason": "Cambió desde la vista previa (versión 4 a 5); no se envió"
      }
    ],
    "resultCsvRef": "evidencias/publicaciones/2026/10/18/job-9c1e-resultado.csv",
    "page": 1,
    "size": 50,
    "total": 2
  }
}

{
  "reason": "La corrida bajó los productos visibles del seller",
  "scope": "FIELDS_CHANGED_BY_JOB"
}

{
  "success": true,
  "data": {
    "planId": "pln-rv0207",
    "expiresAt": "2026-10-18T17:00:00Z",
    "sourceJobId": "job-77aa",
    "summary": {
      "products": 1354,
      "revertible": 1340,
      "conflicts": 14
    },
    "sample": [
      {
        "productId": "PRD-0004812",
        "fields": [
          {
            "attribute": "CATEGORIA_WEB",
            "before": "catst000120",
            "after": "catst000123"
          }
        ],
        "conflict": false
      }
    ],
    "conflicts": [
      {
        "productId": "PRD-0004890",
        "reason": "Cambió después de la corrida (versión 6); se revisa a mano"
      }
    ],
    "thenRepublish": {
      "operation": "REPUBLISH",
      "channels": [
        "TIENDA"
      ],
      "includeCatIds": true
    },
    "applyUrl": "/api/v2/product-plans/pln-rv0207/apply"
  }
}

Las que usa y construye otra épica (9)

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-INT-07-1. Repoblar no mueve el estado ni cambia datos: reenvía a la tienda la versión aprobada vigente, sin categorías, sin OMS y sin Marketplace. Por qué: Es lo que hace Omega y lo que pide la operación de hoy; la duda de OMS (P360 repuebla con OMS, Omega no) se cierra sin OMS, porque OMS ya recibe los cambios aprobados por la publicación normal. Se apoya en PD-09, DUD-24.
• D-INT-07-2. Repoblar y mandar categorías son dos operaciones: REPOPULATE (el producto sin categorías) y SEND_CATIDS (sólo categorías de Sitios Web, hasta 1,000 por XML y nunca vacío). El archivo de SKU, título y clasificación web plancha esos campos con la carga masiva y después lanza las dos. Por qué: Las fuentes chocan sobre qué viaja con el archivo; separarlas cumple las dos lecturas y evita mandar lo que no toca. Se apoya en DUD-24, RF-CAT-15.
• D-INT-07-3. Una corrida es un trabajo de MS-02 (product_jobs) con universo, autor, fecha, motivo y la versión fijada de cada producto; cada envío queda en la bitácora con su XML y su SHA-256 en el almacén. Si un producto cambia después de la vista previa, queda bloqueado. Por qué: Saber qué cambió cada corrida y con qué datos es lo que faltó en la reversa de 3 días. Se apoya en RF-CAL-13, DMS-66.
• D-INT-07-4. Revertir es regresar a su valor anterior los campos que la corrida planchó (tomados de las versiones del producto) y republicar; no se republica completa una versión vieja. Lo que cambió después de la corrida queda como conflicto para revisar a mano. Por qué: Republicar la versión previa entera borraría cambios buenos hechos después; regresar sólo lo planchado es preciso y se puede revisar. Se apoya en DUD-24, RF-CAL-13.
• D-INT-07-5. Volumen: hasta 10,000 IDs en la petición o una lista en archivo de hasta 2 millones; lotes de 1,000 productos por XML y ritmo por destino configurable. Por qué: Omega limita a 100 productos por trabajo y el negocio necesita repoblar universos de 23 mil a 700 mil. Se apoya en DUD-24.
• D-INT-07-6. La tarea de Repoblamiento la abre la acción REQUEST_REPOPULATION del motor (QA, Gobierno de Datos o Category) y pone En modificación un producto aprobado (T09). Mandar a Compras abre Revisión del cambio; mandar al proveedor abre Corrección con los rechazos por atributo juntos; aprobar regresa a Aprobado sólo con datos base y obligatorios (T10) y republica los canales afectados (C06). La tienda conserva lo publicado mientras tanto. Por qué: Es el 1031 de hoy, con sus tres salidas, en el modelo de tres capas. Se apoya en PD-29.
• D-INT-07-7. La foto que lee el adaptador es siempre la de la versión fijada por el trabajo, que es la aprobada vigente al confirmar: un título recalculado y aprobado antes de confirmar viaja en esa corrida. Por qué: Repoblamiento necesita que el título corregido salga en la carga y aprobación de una hora después. Se apoya en DEC-86, RF-PLA-16.

Qué falta decidir

Fuentes

1. [D] trazabilidad/features/FT-INT-07-repoblamiento-masivo-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.