FT-PLT-09 · Carga masiva de configuración de plantillas con…

En 30 segundos

Configurar miles de plantillas una por una es imposible, y hoy se hace con programas de un solo uso que no validan nada. Esta épica deja cargar la configuración del catálogo por archivo CSV o por API: el archivo se valida completo, renglón por renglón, sin tocar la base; si todo está bien, se aplica con la misma aprobación que la pantalla y con los mismos avisos. Sirve para cargar el nivel de cada atributo por negocio en muchas plantillas y para preparar un ambiente vacío.

• Módulo dueño: MS-01 Catálogo. También participan: MS-02 Producto, MS-04 Reportes, MS-14 Avisos y ayuda, MS-15 IA y enriquecimiento.
• Etapa C · Configura el catálogo. Recibe «PE-T · Usuario con permisos y bitácora» y entrega «PE-C · Catálogo vigente».
• APIs: construye 7 y usa 5 que construyen otras épicas.
• Eventos: publica 5 y consume 1.

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 Archivo con errores

3.2 Inicializar un ambiente vacío

3.3 Validación por API y centro de archivos

4. Si algo sale mal

• El archivo trae una columna que no es de su perfil. Se rechaza completo con 400 UNKNOWN_COLUMN antes de leer una sola fila; nada cambia.
• Algún renglón tiene errores (código repetido, nivel o negocio que no existe). La carga queda VALIDATED_WITH_ERRORS con fila, columna, código y mensaje de cada error y ningún dato cambia; no se puede aplicar a medias.
• El archivo pasa el límite de su perfil. Se rechaza completo con 413 LIMIT_EXCEEDED; nunca se trunca.
• Algo que toca la carga cambió entre la validación y la aprobación. La aprobación deja la solicitud en conflicto sin aplicar nada (409 VERSION_CONFLICT) y se valida otra vez el archivo; una carga lista vale 24 horas.
• Un registro falla al aplicarse aunque pasó la validación. Cada registro va en su propia transacción: los demás se aplican y el recibo dice cuál falló y por qué, para reintentar sólo ése.

5. APIs

Las que construye esta épica (7)

null

{
  "success": true,
  "data": {
    "items": [
      {
        "profile": "LOOKUP_VALUES_V1",
        "name": "Valores de lista",
        "objectType": "LOV_VALUE",
        "dependencyOrder": 2,
        "maxRows": 50000
      },
      {
        "profile": "ATTRIBUTES_V1",
        "name": "Atributos",
        "objectType": "ATTRIBUTE",
        "dependencyOrder": 3,
        "maxRows": 5000
      },
      {
        "profile": "STRUCTURE_GROUP_CREATE_V1",
        "name": "Alta de nodos",
        "objectType": "TEMPLATE_NODE",
        "dependencyOrder": 5,
        "maxRows": 5000
      },
      {
        "profile": "TEMPLATE_BINDINGS_V1",
        "name": "Configuración por plantilla y negocio",
        "objectType": "BINDING",
        "dependencyOrder": 7,
        "maxRows": 50000
      }
    ],
    "page": 1,
    "size": 50,
    "total": 12
  }
}

null

{
  "success": true,
  "data": {
    "profile": "TEMPLATE_BINDINGS_V1",
    "format": "CSV",
    "encoding": "UTF-8",
    "separator": ",",
    "columns": [
      {
        "name": "TEMPLATE_ID",
        "required": true,
        "example": "EU4-0412"
      },
      {
        "name": "ATTRIBUTE_ID",
        "required": true,
        "example": "MATERIAL_VASO"
      },
      {
        "name": "BUSINESS",
        "required": true,
        "allowed": [
          "MER",
          "SUB",
          "MKP"
        ]
      },
      {
        "name": "LEVEL",
        "required": true,
        "allowed": [
          "REQUIRED",
          "RECOMMENDED",
          "OPTIONAL"
        ]
      },
      {
        "name": "LAYER",
        "required": false,
        "allowed": [
          "1",
          "2",
          "3",
          "4",
          "5"
        ]
      },
      {
        "name": "SECTION",
        "required": false,
        "example": "CARACTERISTICAS"
      },
      {
        "name": "VALUE_FILTER",
        "required": false,
        "example": "VID|PLA"
      }
    ],
    "downloadUrl": "/api/v2/catalog-imports/profiles/TEMPLATE_BINDINGS_V1/template?format=csv"
  }
}

{
  "profile": "TEMPLATE_BINDINGS_V1",
  "channel": "IMPORT",
  "file": "configuracion-licuadoras.csv (multipart/form-data, campo file)",
  "rows": "sólo por API: los mismos renglones del CSV en JSON, sin archivo"
}

{
  "success": true,
  "data": {
    "importId": "imp-7c21",
    "status": "VALIDATING",
    "rows": 1240,
    "sha256": "9f2c41e0b7d3a8c5",
    "links": {
      "self": "/api/v2/catalog-imports/imp-7c21"
    }
  }
}

{
  "comment": "Niveles por negocio que entregó Mercaderías para cocina"
}

{
  "success": true,
  "data": {
    "requestId": "req-3e9a71",
    "status": "PENDING_APPROVAL",
    "changeRequestId": "chg-7f0a33",
    "receiptUrl": "/api/v2/catalog-receipts/req-3e9a71"
  }
}

null

{
  "success": true,
  "data": {
    "importId": "imp-5a02",
    "profile": "LOOKUP_VALUES_V1",
    "status": "VALIDATED_WITH_ERRORS",
    "progress": 100,
    "stats": {
      "rows": 500,
      "valid": 498,
      "errors": 2
    },
    "summary": {
      "create": 412,
      "update": 86
    },
    "impact": {
      "templates": 37,
      "products": 5120,
      "views": 111
    },
    "errors": [
      {
        "row": 14,
        "column": "CODE",
        "code": "CONFLICTING_ROWS",
        "message": "El código 0712 se repite en la fila 233"
      },
      {
        "row": 233,
        "column": "CODE",
        "code": "CONFLICTING_ROWS",
        "message": "El código 0712 se repite en la fila 14"
      }
    ],
    "changeRequestId": null,
    "receiptUrl": null
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "importId": "imp-7c21",
        "profile": "TEMPLATE_BINDINGS_V1",
        "channel": "IMPORT",
        "status": "APPLIED",
        "rows": 1240,
        "createdAt": "2027-01-15T15:00:00Z",
        "appliedAt": "2027-01-16T10:12:00Z",
        "changeRequestId": "chg-7f0a33"
      }
    ],
    "page": 1,
    "size": 50,
    "total": 1
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "kind": "IMPORT",
        "id": "imp-7c21",
        "profile": "TEMPLATE_BINDINGS_V1",
        "status": "APPLIED",
        "createdAt": "2027-01-15T15:00:00Z",
        "link": "/api/v2/catalog-imports/imp-7c21"
      },
      {
        "kind": "EXPORT",
        "id": "job-40e8",
        "type": "CATALOG_FILTER",
        "status": "DONE",
        "createdAt": "2027-01-14T18:20:00Z",
        "link": "/api/v2/exports/job-40e8"
      }
    ],
    "page": 1,
    "size": 50,
    "total": 2
  }
}

Las que usa y construye otra épica (5)

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-PLT-09-1. Se valida todo antes de tocar la base, con las mismas reglas que la pantalla: una columna ajena rechaza el archivo antes de leer filas y un solo error deja la carga en VALIDATED_WITH_ERRORS, con fila, columna, código y mensaje, sin aplicar nada. Por qué: La ERF pide validación previa por fila y celda, y la plantilla masiva de hoy tenía un «Validar» que no validaba. Se apoya en DEC-ARQ-12, DEC-PLT-05.
• D-PLT-09-2. Aplicar una carga lista abre una sola solicitud de cambio con su canal (IMPORT, API o IA), que se aprueba completa. Al aprobarse, se aplica registro por registro, cada uno en su transacción con sus idiomas, y el recibo dice qué pasó con cada uno. Por qué: Mismo control que la pantalla sin pedirle al aprobador miles de decisiones, y sin que un registro malo deshaga todo el archivo. Se apoya en DEC-PLT-05, DEC-ARQ-12.
• D-PLT-09-3. Formatos: CSV en UTF-8 con los perfiles y columnas de hoy, y la API con los mismos renglones en JSON y el mismo reporte. Excel queda fuera del primer corte. Por qué: Excel reformatea identificadores y códigos (notación científica, ceros a la izquierda); el CSV del perfil se abre en Excel de todos modos. Se apoya en DUD-02.
• D-PLT-09-4. Toda validación corre aparte: subir responde de inmediato con el identificador de la carga, el avance se consulta y MS-14 avisa al terminar. Una carga lista vale 24 horas. Por qué: Lo que tarda es asíncrono con recibo; la meta de tiempo no tiene fuente y la fija el plan. Se apoya en ADR-12.
• D-PLT-09-5. Un paquete de varios perfiles se procesa en orden de dependencia (listas, valores, atributos, grupos, nodos, metadatos y configuración) y los nodos sin ID reciben el siguiente EU{nivel+1}-{número}. Reemplaza los programas de un solo uso y el copiado de diccionarios entre ambientes con credenciales en claro. Por qué: Preparar un ambiente vacío sin programas sueltos y sin credenciales en archivos. Se apoya en RSG-40, PD-16.
• D-PLT-09-6. La IA que crea plantillas usa la misma API de carga con canal IA y pasa por la misma aprobación; ya no escribe directo como hoy. Por qué: Hoy la IA de plantillas escribe nodos, atributos y configuración sin validación previa; así queda con el mismo control que todos. Se apoya en P-19, DEC-PLT-05.
• D-PLT-09-7. El centro de importaciones y exportaciones es una pantalla del BFF que junta las cargas de MS-01 y las exportaciones de MS-04 (PEDIDA-PLT-09-1); ni MS-01 ni MS-04 componen la lista del otro. Por qué: Decisión 19 del backend compartido que adopta ADR-12: lo que junta datos de varios módulos para una pantalla va al BFF. Se apoya en ADR-12.

Qué falta decidir

También siguen abiertos: RSG-40, Confirmar el retiro del script que copia diccionarios entre ambientes con credenciales en claro.

Fuentes

1. [D] trazabilidad/features/FT-PLT-09-carga-masiva-configuracion-plantillas.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.