FT-PLT-01 · Fundamentos de gobierno de plantillas

En 30 segundos

Plantillas, atributos y listas las usan todos los portales y SAP, así que un cambio mal hecho afecta a miles de productos. Esta épica pone las reglas comunes de toda escritura del catálogo: cada objeto conserva su identificador para siempre, todo cambio queda como solicitud pendiente hasta que otra persona autorizada lo aprueba, y cada campo cambiado deja su antes y su después en la bitácora. Así nada llega a la captura sin control y siempre se sabe quién cambió qué.

• Módulo dueño: MS-01 Catálogo. También participan: MS-13 Identidad y acceso, MS-14 Avisos y ayuda, MS-05 Auditoría, MS-02 Producto, MS-03 Migración y convivencia, 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 8 y usa 7 que construyen otras épicas.
• Eventos: publica 1 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 Si el aprobador rechaza

3.2 Cambios que llegan por carga masiva o por la IA

3.3 Migración con los ID de P360 y su historia

4. Si algo sale mal

• El aprobador rechaza. La solicitud se cierra como rechazada, el catálogo no cambia y MS-14 avisa al solicitante con el motivo; puede abrir otra solicitud corregida.
• Alguien cambió el objeto mientras la solicitud esperaba. Al aprobar, MS-01 vuelve a comparar las versiones: si alguna cambió, la solicitud queda en conflicto sin aplicar nada (409 VERSION_CONFLICT) y el solicitante recibe el aviso para pedirla otra vez sobre la versión vigente.
• Nadie decide la solicitud. A los 23 días MS-14 le recuerda al solicitante y a los aprobadores; a los 30 la solicitud vence sola sin tocar el catálogo y queda en su recibo como vencida.
• Quien pidió el cambio intenta aprobarlo. La decisión responde 403 AUTHORIZATION_ERROR: nadie aprueba lo que pidió, y la bandeja no le muestra el botón (canDecide en falso).
• Alguien captura un ID sin permiso o intenta cambiar uno existente. El plan responde 403 AUTHORIZATION_ERROR o 409 IMMUTABLE_ID y no se abre ninguna solicitud; si el ID ya es de otro objeto, 409 ID_ALREADY_EXISTS.

5. APIs

Las que construye esta épica (8)

{
  "comment": "Atributo pedido para las licuadoras de alta potencia"
}

{
  "success": true,
  "data": {
    "requestId": "req-8e41a0",
    "status": "PENDING_APPROVAL",
    "changeRequestId": "chg-2a71c4",
    "receiptUrl": "/api/v2/catalog-receipts/req-8e41a0"
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "changeRequestId": "chg-2a71c4",
        "status": "PENDING",
        "channel": "PORTAL",
        "objectType": "TEMPLATE_NODE",
        "operation": "CREATE",
        "summary": "Alta de la plantilla «Licuadoras de inmersión» bajo EU3-0398",
        "objectCount": 1,
        "requestedBy": {
          "userId": "usr-1042",
          "area": "GOBIERNO-PRODUCTO"
        },
        "requestedAt": "2027-01-12T15:05:00Z",
        "expiresAt": "2027-02-11T15:05:00Z",
        "canDecide": true
      }
    ],
    "page": 1,
    "size": 50,
    "total": 1
  }
}

null

{
  "success": true,
  "data": {
    "changeRequestId": "chg-2a71c4",
    "status": "PENDING",
    "channel": "PORTAL",
    "operation": "CREATE",
    "version": 1,
    "comment": "Familia nueva pedida por Compras Hogar",
    "requestedBy": {
      "userId": "usr-1042",
      "area": "GOBIERNO-PRODUCTO"
    },
    "requestedAt": "2027-01-12T15:05:00Z",
    "expiresAt": "2027-02-11T15:05:00Z",
    "objects": [
      {
        "objectType": "TEMPLATE_NODE",
        "objectId": null,
        "idAssignedOn": "APPROVAL",
        "idPattern": "EU4-{número}",
        "baseVersion": null,
        "diff": [
          {
            "path": "name.es",
            "before": null,
            "after": "Licuadoras de inmersión"
          },
          {
            "path": "parentId",
            "before": null,
            "after": "EU3-0398"
          },
          {
            "path": "keywords",
            "before": null,
            "after": [
              "licuadora de mano",
              "batidora de inmersión"
            ]
          }
        ]
      }
    ],
    "impact": {
      "templates": 1,
      "views": 3,
      "products": 0
    },
    "decision": null
  }
}

{
  "decision": "APPROVE",
  "comment": "Revisado contra la guía de familias de cocina"
}

{
  "success": true,
  "data": {
    "requestId": "req-c90d17",
    "status": "ACCEPTED",
    "changeRequestId": "chg-2a71c4",
    "receiptUrl": "/api/v2/catalog-receipts/req-c90d17"
  }
}

null

{
  "success": true,
  "data": {
    "requestId": "req-8e41a0",
    "status": "DONE",
    "changeRequestId": "chg-2a71c4",
    "finishedAt": "2027-01-12T18:02:11Z",
    "items": [
      {
        "objectType": "ATTRIBUTE",
        "objectId": "ATR-0003001",
        "result": "APPLIED",
        "version": 1
      }
    ]
  }
}

{
  "runId": "mig-run-0007",
  "batch": 12,
  "documents": [
    {
      "_id": "EU4-0412",
      "taxonomy": "PRODUCT",
      "level": 4,
      "parentId": "EU3-0398",
      "name": {
        "es": "Licuadoras"
      },
      "keywords": [
        "licuadora",
        "blender"
      ],
      "status": "ACTIVE",
      "attributeBindings": [],
      "legacy": {
        "owner": "P360"
      }
    }
  ]
}

{
  "success": true,
  "data": {
    "runId": "mig-run-0007",
    "batch": 12,
    "upserted": 1,
    "rejected": 0,
    "items": [
      {
        "_id": "EU4-0412",
        "result": "CREATED"
      }
    ],
    "sequenceAfterLoad": {
      "TEMPLATE_NODE:EU4": "EU4-4087"
    }
  }
}

null

{
  "success": true,
  "data": {
    "matrixVersion": 8,
    "version": 3,
    "updatedAt": "2027-01-08T16:00:00Z",
    "rows": [
      {
        "roleId": "GOBIERNO_PRODUCTO",
        "object": "ATTRIBUTE",
        "actions": [
          "READ",
          "PROPOSE",
          "APPROVE",
          "CAPTURE_ID"
        ],
        "businesses": [
          "MER",
          "SUB",
          "MKP"
        ]
      }
    ]
  }
}

{
  "version": 3,
  "matrixVersion": 9,
  "rows": [
    {
      "roleId": "CATEGORY",
      "object": "CATEGORY",
      "actions": [
        "CREATE",
        "UPDATE",
        "MOVE",
        "UNLINK",
        "APPROVE"
      ],
      "businesses": [
        "MER",
        "MKP",
        "SUB"
      ]
    },
    {
      "roleId": "GOBIERNO_PRODUCTO",
      "object": "ATTRIBUTE",
      "actions": [
        "READ",
        "PROPOSE",
        "APPROVE",
        "CAPTURE_ID"
      ],
      "businesses": [
        "MER",
        "SUB",
        "MKP"
      ]
    }
  ]
}

{
  "success": true,
  "data": {
    "planId": "pln-61f2c8",
    "expiresAt": "2027-01-08T16:10:00Z",
    "requiresApproval": true,
    "summary": {
      "rowsAdded": 0,
      "rowsChanged": 1,
      "rowsRemoved": 0
    },
    "unknownRoles": [],
    "changes": [
      {
        "roleId": "CATEGORY",
        "object": "CATEGORY",
        "before": [
          "CREATE",
          "UPDATE",
          "MOVE",
          "UNLINK"
        ],
        "after": [
          "CREATE",
          "UPDATE",
          "MOVE",
          "UNLINK",
          "APPROVE"
        ]
      }
    ],
    "applyUrl": "/api/v2/catalog-plans/pln-61f2c8/apply"
  }
}

Las que usa y construye otra épica (7)

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-01-1. Toda escritura de lo que define la plantilla (atributos, listas, grupos, árbol, metadatos y configuración), venga de pantalla, carga masiva, API o IA, queda como solicitud en una colección propia de MS-01 y surte efecto sólo cuando otra persona con permiso la aprueba. Nadie aprueba lo que pidió. Por qué: La ERF 1.1 §3.4 pide que nada surta efecto sin aprobación y DEC-ARQ-12 lo metió al alcance. El plan dura minutos y no sirve para esperar una aprobación de días; guardar la solicitud aparte del objeto evita versiones a medias en el catálogo vigente. Se apoya en DEC-ARQ-12, DEC-PLT-05, PD-01.
• D-PLT-01-2. Qué pide aprobación lo fija una política de MS-01 por tipo de objeto. Lo que el PIM no gobierna no la pide: los catálogos que manda SAP (API-01-050 a 052) y la carga de la migración (API-01-053) se aplican directo con su recibo. Cada diccionario y cada tipo de regla dicen en su definición si la piden (FT-REF-01 y FT-PLT-07). Por qué: SAP es el dueño de sus catálogos: aprobar en el PIM lo que SAP ya decidió sólo crea desfases. Una sola política evita que cada pantalla invente su regla. Se apoya en DUD-21, DUD-23, DEC-ARQ-12.
• D-PLT-01-3. Los ID de P360 se conservan y ningún ID de plantilla, atributo o lista se modifica. Los nuevos salen de id_sequences con el formato de hoy (EU{nivel+1}-{número} en plantillas) y se asignan al aprobar; capturar un ID al crear exige un permiso propio. Si una carga trae un ID existente, actualiza cuando es el mismo tipo de objeto y falla con ID_ALREADY_EXISTS si es otro. Por qué: Entrada Única, Foro, SAP y la tienda resuelven sus referencias con esos ID; cambiarlos exigiría equivalencias en cada consumidor. Se apoya en PD-16, DEC-PLT-06, DUD-18.
• D-PLT-01-4. La historia por campo la guarda sólo MS-05, a partir de los eventos de catalog.governance.changed, que llevan el antes y el después, el actor, el canal y la solicitud. MS-01 no lleva bitácora propia. Lo migrado empieza su historia en la carga: la de P360 no se migra. Por qué: Un dueño para la bitácora. P360 no guarda el valor anterior ni el nuevo, así que no hay historia que traer. Se apoya en DEC-ARQ-09, PD-05, ADR-12.
• D-PLT-01-5. Los permisos de dominio del catálogo los decide MS-01: cruza los roles del usuario que da el directorio (API-13-001, con caché) con su matriz del catálogo (rol, tipo de objeto, acción y negocio), que Seguridad carga de la hoja firmada (API-01-110) y que se guarda como un diccionario de MS-01. El BFF sólo decide los de pantalla. Sin matriz firmada no se concede ningún permiso por suposición: la operación se niega. Por qué: Decisión 19 del backend compartido que adopta ADR-12: los permisos de dominio viven en el servicio dueño con los roles del directorio. La matriz no se inventa; la trae FT-USR-02. Se apoya en ADR-12, DEC-PLT-09, DUD-22.
• D-PLT-01-6. Hasta el corte del catálogo en R1, P360 es la fuente: MS-01 sólo recibe la carga de MS-03 y responde WRITE_DISABLED a toda escritura de pantalla. Desde el corte, P360 congela sus plantillas y el PIM es la única fuente. Por qué: Escribir en los dos lados es una doble escritura que sólo cubre una parte del catálogo; congelar cuesta poco y es lo que recomienda el diseño (opción A). Se apoya en PD-12, DEC-PLT-13.
• D-PLT-01-7. Una solicitud pendiente vence a los 30 días sin decisión, con recordatorio a los 23. Al aprobar, MS-01 vuelve a validar contra la versión de cada objeto y, si alguno cambió, la deja en conflicto sin aplicar nada. Por qué: Nunca se aplica un cambio sobre una base distinta de la que vio el aprobador, y las solicitudes olvidadas no se acumulan. Se apoya en DEC-PLT-05.

Qué falta decidir

Fuentes

1. [D] trazabilidad/features/FT-PLT-01-fundamentos-de-gobierno-de-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.