FT-USR-02 · Matriz de roles y permisos por módulo, acción, negocio y…

En 30 segundos

Hoy cada sistema decide los permisos a su manera: el portal los tiene escritos en su código y casi ningún servicio los revisa. Esta épica carga como configuración la matriz de roles firmada por Seguridad y Gobierno de Producto. MS-13 guarda los roles, sus pantallas y quién tiene cada uno, con su negocio y sus secciones; cada módulo guarda qué puede hacer cada rol sobre sus datos y decide él mismo; el BFF arma el menú, y cada intento negado queda en la bitácora.

• Módulo dueño: MS-13 Identidad y acceso. También participan: MS-01 Catálogo, MS-02 Producto, MS-14 Avisos y ayuda, MS-05 Auditoría.
• Etapa T · Transversal. Recibe «PE-C · Catálogo vigente» y entrega «PE-T · Usuario con permisos y bitácora».
• APIs: construye 6 y usa 15 que construyen otras épicas.
• Eventos: publica 2 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 Asignar personas, secciones y pasos

3.2 Cada quien ve sólo lo suyo

3.3 Sólo perfiles autorizados cambian el catálogo

4. Si algo sale mal

• La hoja de roles cita una pantalla que no existe o retira un rol con miembros vigentes. El plan responde 422 con el renglón y el motivo; no se escribe nada hasta corregir la hoja o mover a los miembros.
• Una hoja de dominio cita un rol que no existe en el directorio. Su dueño (el motor de MS-02 o MS-01) rechaza ese renglón en la vista previa; Administración de accesos da de alta el rol primero.
• Alguien sin permiso intenta una acción. Recibe 403 AUTHORIZATION_ERROR, o 404 si el objeto es de otro proveedor o seller; el intento queda en MS-05 con la acción y el motivo, y Administración de accesos lo ve en el historial.
• Se pierde o se atrasa el aviso ROLE_CHANGED. La caché vence sola a los 5 minutos; cada respuesta de roles lleva su versión, así se sabe con cuál se decidió.
• La matriz firmada no llega antes de la UAT. Se arranca con el catálogo inicial traducido de los perfiles de hoy, marcado como provisional; lo que no conceda queda negado y Gobierno de Producto ve la lista de lo pendiente.

5. APIs

Las que construye esta épica (6)

{
  "file": "(hoja ROLES de la matriz, XLSX en multipart)",
  "matrixVersion": 8,
  "signedBy": [
    "SEGURIDAD",
    "GOBIERNO_PRODUCTO"
  ],
  "signedOn": "2026-11-20",
  "effectiveFrom": "2026-12-01T06:00:00Z"
}

{
  "success": true,
  "data": {
    "planId": "pln-c71d03",
    "expiresAt": "2026-11-20T18:30:00Z",
    "summary": {
      "roles": 41,
      "new": 3,
      "changed": 12,
      "retired": 2,
      "usersAffected": 46
    },
    "items": [
      {
        "roleId": "EJECUTIVO_CATALOGACION",
        "change": "NEW",
        "screens": [
          "PROPUESTAS",
          "LOOKS"
        ]
      },
      {
        "roleId": "PIM_CATALOG_ADMIN",
        "change": "RETIRED",
        "membersToMove": 0
      }
    ],
    "rejectedRows": [],
    "domainSheets": [
      {
        "sheet": "MOTOR",
        "owner": "MS-02",
        "loadWith": "API-02-031 (ROLE_MATRIX y FIELD_OWNERS)"
      },
      {
        "sheet": "CATALOGO",
        "owner": "MS-01",
        "loadWith": "permisos del catálogo de MS-01"
      }
    ],
    "applyUrl": "/api/v2/identity-plans/pln-c71d03/apply"
  }
}

null

{
  "success": true,
  "data": {
    "matrixVersion": 7,
    "effectiveFrom": "2026-10-01T06:00:00Z",
    "signedBy": [
      "SEGURIDAD",
      "GOBIERNO_PRODUCTO"
    ],
    "rows": [
      {
        "roleId": "COMPRAS",
        "kind": "ROLE",
        "name": "Compras",
        "screens": [
          "BANDEJA_VISTO_BUENO",
          "PROPUESTAS",
          "TABLEROS"
        ],
        "scopeTypes": [
          "businesses",
          "sections",
          "areas"
        ],
        "members": 214
      },
      {
        "roleId": "COMPRAS-HOGAR",
        "kind": "AREA",
        "name": "Compras Hogar",
        "screens": [],
        "scopeTypes": [],
        "members": 31
      }
    ]
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "roleId": "QA",
        "kind": "ROLE",
        "name": "QA de contenido",
        "status": "ACTIVE",
        "members": 23,
        "matrixVersion": 7,
        "screens": [
          "BANDEJA_QA",
          "TABLEROS",
          "MIS_EXPORTES"
        ],
        "scopeTypes": [
          "businesses",
          "sections"
        ]
      }
    ],
    "page": 1,
    "size": 50,
    "total": 1
  }
}

{
  "operation": "CREATE",
  "roleId": "EJECUTIVO_CATALOGACION",
  "name": "Ejecutivo de catalogación",
  "screens": [
    "PROPUESTAS",
    "LOOKS"
  ],
  "scopeTypes": [
    "businesses"
  ],
  "reason": "La matriz firmada crea el rol que lleva un Conjunto Look a Publicación"
}

{
  "success": true,
  "data": {
    "planId": "pln-0e7b52",
    "expiresAt": "2026-10-18T15:14:05Z",
    "impact": {
      "users": 0,
      "screensAdded": [
        "LOOKS"
      ],
      "screensRemoved": []
    },
    "applyUrl": "/api/v2/identity-plans/pln-0e7b52/apply"
  }
}

null

{
  "success": true,
  "data": {
    "code": "QA",
    "kind": "ROLE",
    "business": "MER",
    "section": "2001",
    "members": [
      {
        "userId": "USR-000318",
        "displayName": "Analista QA 07",
        "contact": "(correo del directorio)",
        "validTo": "2027-10-31T23:59:59Z"
      }
    ],
    "total": 1
  }
}

{
  "source": "MS-02",
  "events": [
    {
      "type": "ACCESS_DENIED",
      "at": "2026-10-17T22:31:40Z",
      "subject": "idp|8b30fe21aa",
      "userId": "USR-000318",
      "action": "FLU-ACCEPT",
      "resource": {
        "type": "PRODUCT",
        "id": "PRD-0004812"
      },
      "reason": "SIN_CAPACIDAD",
      "requestId": "req-77ab10"
    }
  ]
}

{
  "success": true,
  "data": {
    "accepted": 1
  }
}

Las que usa y construye otra épica (15)

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-USR-02-1. Cada parte de la matriz tiene un dueño y nada se repite. MS-13 guarda los roles y áreas, las pantallas de cada rol y las membresías con su alcance (negocio, sección, proveedor o seller, área) y su vigencia. El motor de MS-02 guarda rol × acción × tarea × negocio (ROLE_MATRIX) y el dueño de cada grupo de campos (FIELD_OWNERS); MS-01, rol × acción sobre el catálogo; MS-04 y MS-05, qué rol usa cada reporte y cada consulta de la bitácora. MS-13 no guarda permisos de dominio. Por qué: La decisión 18 pone el rol en el directorio y la matriz en el servicio dueño, y el motor ya la tomó así; si MS-13 guardara también acciones, habría dos tablas que reconciliar. Se apoya en DUD-22, DMS-71, DEC-PLT-09, FT-FLU-01.
• D-USR-02-2. La matriz firmada es un documento con una hoja por dueño: ROLES (MS-13), MOTOR (MS-02) y CATALOGO (MS-01). Cada hoja se carga con vista previa en su dueño, que valida contra MS-13 que los roles existan. Un perfil nuevo es una fila en ROLES y en las hojas que toque: no se despliega nada; sólo una pantalla o una acción nueva piden código. Por qué: Se aplican permisos sin cambiar código (H1) y cada dueño sigue siendo el único que escribe su tabla. Se apoya en DUD-22, DEC-PLT-09.
• D-USR-02-3. Falla cerrada: lo que una hoja no conceda está negado. Cada negación responde 403 AUTHORIZATION_ERROR (404 si revelaría que existe un objeto de otro proveedor o seller) y el módulo la manda a MS-05 por lotes (API-05-007) con la acción, el objeto y el motivo. Por qué: Sin matriz no se supone ningún permiso, y el intento negado tiene que quedar registrado, como piden H1 y H7. Se apoya en ADR-05, DUD-22.
• D-USR-02-4. Arranque: un catálogo inicial de roles traducido de los 15 perfiles de Entrada Única, los 15 perfiles y 19 roles de Foro, los grupos de workflow de P360 (sólo cuentan las membresías de tipo 2700) y los 8 roles que nombran las ERF. Las 26 autorizaciones concedidas de P360 son insumo y no se migran. Queda marcado como provisional hasta la firma. Por qué: El taller de la matriz necesita un punto de partida medido, y P360 es insumo, no fuente. Se apoya en DEC-PLT-09, DUD-22.
• D-USR-02-5. El aislamiento se hace en el servidor: MS-02 filtra búsquedas, fichas, exportes y la API de terceros por el proveedor o seller que da API-13-001; un producto ajeno responde 404. Los sellers entran en la fase que fije PD-02. Por qué: Hoy el portal marca a todo usuario como autorizado; filtrar en el navegador no protege nada. Se apoya en PD-02, RSG-36.
• D-USR-02-6. Las secciones van en el alcance de cada membresía. Las pantallas sólo ofrecen esas secciones y los grupos de artículo de cada una (MS-01), y MS-02 rechaza crear o aprobar fuera de ellas, también por API, con 403 y registro. Por qué: Así el filtro por sección vale igual en la pantalla, en la carga masiva y en la API. Se apoya en DUD-22.
• D-USR-02-7. El motor asigna cada tarea a un rol o un área (configuración de MS-02) y MS-13 dice quién lo integra hoy (API-13-015), para la cola y para los avisos. Asignar a alguien a un paso es cambiar su membresía, no el código. Por qué: Cada workflow de P360 tenía su grupo; aquí el grupo es un rol del directorio y la regla del paso vive en el motor. Se apoya en PEN-60, PD-29.
• D-USR-02-8. Cambiar un EAN fuera del flujo de liberación queda en la tabla del motor sólo para Gobierno de Datos, y llevar un Conjunto Look a Publicación sólo para el rol nuevo Ejecutivo de catalogación, que se crea en la hoja de roles porque hoy no existe en código. Por qué: Lo piden las ERF y ningún sistema lo controla hoy. Se apoya en DUD-22.
• D-USR-02-9. Cada rol lleva sus pantallas en el directorio y el BFF las aplica en el menú y en cada ruta /bff; se quitan las guardas escritas en el front. Por qué: El BFF no tiene base; si las pantallas fueran código del BFF, un perfil nuevo pediría un despliegue. Se apoya en PD-30, DUD-22.

Qué falta decidir

También siguen abiertos: PEN-60, Negocio define en qué casos se abre la tarea de Gobierno de Datos tras crear el SKU y para quién (propuesta en D-RAC-04-4); PEN-55, Negocio confirma cómo se identifica el negocio de cada alta de un proveedor híbrido.

Fuentes

1. [D] trazabilidad/features/FT-USR-02-matriz-de-roles-y-permisos.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.