FT-RAC-07 · Reportes, exportes, importes y búsquedas por atributos

En 30 segundos

Los reportes del portal hoy piden los datos a P360 y se rompen al apagarlo; Gobierno de Producto lleva su lista de exportes en una hoja aparte, y contar productos por categoría tarda casi tres minutos por nivel. Esta épica hace de Reportes (MS-04) la salida de archivos del PIM: exportes de productos y categorías que se pueden reimportar, los reportes del portal, las herramientas de P360 y búsquedas con listas grandes, sin cargar la base que opera.

• Módulo dueño: MS-04 Reportes. También participan: MS-02 Producto, MS-01 Catálogo, MS-14 Avisos y ayuda.
• Etapa T · Transversal. Recibe «PE-C · Catálogo vigente», «PE-T · Usuario con permisos y bitácora» y entrega «PE-T · Usuario con permisos y bitácora».
• APIs: construye 7 y usa 6 que construyen otras épicas.
• Eventos: publica 0 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 Exportar el árbol y reimportarlo

3.2 Buscar con listas grandes y contar por categoría

3.3 Los reportes del portal y las herramientas de P360

4. Si algo sale mal

• El exporte pasa del límite de Excel. MS-04 responde 413 LIMIT_EXCEEDED y sugiere CSV; nunca entrega un archivo truncado.
• MS-02 o MS-01 dejan de responder a media lectura. El trabajo se pausa y sigue desde el último cursor; si no se recupera, queda FAILED con lo leído y el motivo, y el usuario recibe el aviso en pantalla.
• El archivo reimportado trae el ID de otro objeto o un ID que no existe. La carga de MS-01 rechaza ese renglón con su código y no confirma nada hasta corregirlo; ningún ID cambia.
• Una categoría del producto está desligada o vencida. El exporte la conserva y la marca en su columna como desligada o vencida, para que Category la corrija.
• El archivo ya venció (7 días). La descarga responde 404; el trabajo sigue en «mis exportes» y se pide otra vez.

5. APIs

Las que construye esta épica (7)

{
  "type": "PRODUCTS_FILTER",
  "filter": {
    "business": "MER",
    "status": "APROBADO",
    "templateId": "EU4-0412"
  },
  "idListRef": null,
  "columns": [
    "SKU",
    "EAN",
    "NOMBRE",
    "MARCA",
    "SECCION",
    "GRUPO_ARTICULOS",
    "COLOR",
    "CoordinadoIDSAP",
    "CATEGORIAS_WEB"
  ],
  "labels": "BOTH",
  "format": "XLSX"
}

{
  "success": true,
  "data": {
    "jobId": "job-rep-7c21",
    "status": "ACCEPTED",
    "links": {
      "self": "/api/v2/exports/job-rep-7c21"
    }
  }
}

null

{
  "success": true,
  "data": {
    "jobId": "job-rep-7c21",
    "type": "PRODUCTS_FILTER",
    "state": "COMPLETED",
    "progress": {
      "completed": 18354,
      "total": 18354
    },
    "counts": {
      "ok": 18342,
      "missing": 12,
      "failed": 0
    },
    "artifacts": [
      {
        "artifactId": "art-01",
        "name": "exporte-productos-20261018.xlsx",
        "rows": 18342,
        "sha256": "9f2c41d0e7…",
        "bytes": 4823110,
        "download": "(enlace firmado de 10 minutos)"
      }
    ],
    "expiresAt": "2026-10-25T15:20:00Z"
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "toolId": "SKU_VALUES",
        "name": "Exportar características por SKU",
        "input": "Lista de SKU; nivel producto, artículo o ambos",
        "requires": "ENT-L"
      },
      {
        "toolId": "CHECK_SENDABLE",
        "name": "Validar productos enviables",
        "input": "Productos seleccionados",
        "requires": "PUB-L"
      },
      {
        "toolId": "EXCEPTIONS",
        "name": "Calcular excepciones",
        "input": "Productos seleccionados",
        "requires": "GOBIERNO"
      }
    ]
  }
}

{
  "ids": [
    "PRD-0004812",
    "PRD-0004813"
  ],
  "idListRef": null,
  "level": "BOTH",
  "frozenImages": true
}

{
  "success": true,
  "data": {
    "jobId": "job-rep-7c35",
    "status": "ACCEPTED",
    "links": {
      "self": "/api/v2/exports/job-rep-7c35"
    }
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "jobId": "job-rep-7c21",
        "type": "PRODUCTS_FILTER",
        "state": "COMPLETED",
        "createdAt": "2026-10-18T15:12:00Z",
        "finishedAt": "2026-10-18T15:20:00Z",
        "artifacts": 1,
        "expiresAt": "2026-10-25T15:20:00Z"
      },
      {
        "jobId": "job-card-5521",
        "type": "DASHBOARD_CARD",
        "state": "COMPLETED",
        "createdAt": "2026-10-18T15:21:00Z",
        "finishedAt": "2026-10-18T15:21:40Z",
        "artifacts": 0,
        "expiresAt": null
      }
    ],
    "page": 1,
    "size": 50,
    "total": 2
  }
}

{
  "filter": {
    "business": "MER",
    "status": [
      "APROBADO"
    ],
    "templateId": "EU4-0412",
    "webCategoryId": null,
    "ownerId": null
  },
  "idListRef": null,
  "level": "VARIANT",
  "cursor": null,
  "pageSize": 1000,
  "columns": [
    "SKU",
    "EAN",
    "NOMBRE",
    "MARCA",
    "SECCION",
    "GRUPO_ARTICULOS",
    "COLOR",
    "CoordinadoIDSAP",
    "webCategoryIds",
    "deliveryStatus",
    "ENRIQUECIDO"
  ]
}

{
  "success": true,
  "data": {
    "asOf": "2026-10-18T15:12:03Z",
    "items": [
      {
        "productId": "PRD-0004812",
        "variantId": "VAR-0004812-01",
        "sku": "1000004812",
        "ean": "7501234567893",
        "ownerId": "PROV-0001",
        "values": {
          "NOMBRE": "Licuadora de 10 velocidades",
          "MARCA": "MARCA01",
          "SECCION": "2001",
          "GRUPO_ARTICULOS": "200105",
          "COLOR": "ROJO",
          "CoordinadoIDSAP": "CO-88120",
          "ENRIQUECIDO": true
        },
        "webCategoryIds": [
          "catst-000812"
        ],
        "deliveryStatus": {
          "TIENDA": "Publicado",
          "OMS": "Publicado"
        }
      }
    ],
    "nextCursor": "cur-7a01",
    "total": 18354
  }
}

{
  "kind": "SKU",
  "source": "PASTE",
  "count": 2000000
}

{
  "success": true,
  "data": {
    "idListRef": "idl-55a1",
    "upload": "(enlace firmado de carga, vence en 15 minutos)",
    "maxIds": 2000000,
    "expiresAt": "2026-10-19T15:12:00Z"
  }
}

Las que usa y construye otra épica (6)

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

6. Eventos

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-RAC-07-1. Reportes no lee colecciones ajenas: los productos los lee por la lectura masiva interna de MS-02, que pagina desde la réplica de sólo lectura (nodo de analítica de la base), y el catálogo, las listas y las categorías por la API de MS-01, con una caché que vacían sus eventos. Así un reporte pesado no carga la base que opera. Por qué: Cada dato tiene un dueño y la historia H10 pide no afectar la operación; el dueño decide desde dónde lee. Se apoya en ADR-12, PD-05, PD-09.
• D-RAC-07-2. GetReportFieldValues (API-04-013) no se construye. En R2 los tres reportes del portal (Familia con variantes, Estatus MKP y Estatus de propuestas) son tipos de exporte de MS-04 con el mismo conteo de éxito, faltante y falla de hoy. La historia de los 29,259 reportes generados en Entrada Única no se migra. Por qué: Sin capa de compatibilidad, la pantalla de reportes se cambia una sola vez al BFF y deja de depender de P360; los reportes viejos son fotos que se pueden volver a pedir. Se apoya en PD-30, ADR-06, DUD-31.
• D-RAC-07-3. El exporte del árbol y el de categorías salen con las columnas del perfil de carga de categorías de MS-01 y el ID como llave, para reimportarlos por esa carga sin tocar ningún ID; si un renglón trae el ID de otro objeto, lo rechaza MS-01. Por qué: Así exportar y reimportar es un solo camino y el rechazo lo da quien es dueño de las categorías. Se apoya en PD-07, FT-CAT-01.
• D-RAC-07-4. Una lista de hasta 2 millones de SKU o EAN se registra en MS-02, dueño de la búsqueda, y se cita por idListRef; Reportes la pasa tal cual a la búsqueda y a la lectura masiva. Por qué: Un solo dueño para las listas evita que la búsqueda y el exporte las lean distinto. Se apoya en DUD-31.
• D-RAC-07-5. API-04-012 se queda con los trabajos de Reportes (exportes, herramientas y cálculos); su ruta base, /api/v2/receipts, debería llamarse /api/v2/report-jobs. Los comprobantes de todos los módulos se ven en la pantalla del BFF (API-BFF-508), que junta la bitácora y el recibo de cada dueño. Por qué: Reportes no puede leer los recibos de otros módulos sin duplicarlos. Se apoya en ADR-12.
• D-RAC-07-6. El KAM es un rol de MS-13 cuyo alcance son sus sellers; ve el avance de sus sellers con la búsqueda de MS-02 por estado y dueño. Qué más ve y con qué jerarquía comercial queda abierto. Por qué: Con el rol y el alcance basta para arrancar sin construir una jerarquía comercial que nadie ha definido. Se apoya en P-28.
• D-RAC-07-7. Los archivos no mienten: SKU, EAN e IDs como texto, fórmulas neutralizadas, Excel con su límite de renglones (si se pasa, 413 y se pide CSV), nunca se trunca, cada archivo lleva huella SHA-256 y se baja con un enlace firmado de 10 minutos; vence a los 7 días. Las listas salen por código, por etiqueta o ambas. Por qué: Un archivo truncado en silencio o con códigos convertidos a número es un dato falso con formato de dato. Se apoya en DUD-31, DEC-PRD-03.
• D-RAC-07-8. La búsqueda por atributos, la búsqueda con listas y el conteo por nivel de categoría son de MS-02 (API-02-001 con sus conteos por valor); Reportes no tiene un índice propio de productos. La prueba del análisis por atributos se hace con la plantilla de vestidos. Por qué: Un segundo índice sería una copia del producto que nadie concilia. Se apoya en DEC-41, PD-09.

Qué falta decidir

También siguen abiertos: PEN-44, Category define las reglas del reporte de categorías por niveles.

Fuentes

1. [D] trazabilidad/features/FT-RAC-07-reportes-exportes-busquedas-atributos.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.