🔐 PermissionsDirective – Guía de uso

La directiva PermissionsDirective es un controlador de acceso a nivel de plantilla que permite mostrar u ocultar elementos del DOM de forma dinámica, basándose en los roles y permisos del usuario actual. Su lógica se integra directamente con el sistema de autenticación y autorización de la aplicación.

---

📁 Importaciones necesarias

Para utilizar PermissionsDirective, asegúrate de que el módulo que la declara y exporta (por ejemplo, SharedModule) esté importado en el módulo del componente donde la vayas a usar.

// En tu componente.ts
import { AlpuraPermissionsDirective } from "@alpura/commons";

@NgModule({
  declarations: [MiComponente],
  imports: [
    // ... otros imports
    AlpuraPermissionsDirective,
  ],
})
export class MiVistaDeDatosComponent {}

---

🧠 Lógica de Validación

La directiva evalúa los permisos del usuario con las siguientes reglas:

1. Permiso Global ALL: Si el usuario tiene el permiso ALL en cualquiera de sus roles, se le concederá acceso a cualquier elemento protegido por esta directiva, sin importar los Inputs proporcionados.
2. Validación por Permiso: Si solo se proporciona el Input [permissions], el elemento se mostrará si el usuario tiene alguno de los permisos listados.
3. Validación por Rol: Si solo se proporciona el Input [roles], el elemento se mostrará si el usuario pertenece a alguno de los roles listados.
4. Validación Combinada (AND): Si se proporcionan ambos Inputs ([permissions] y [roles]), el elemento solo se mostrará si el usuario tiene una asignación donde el permiso y el rol coincidan con los requeridos. Por ejemplo, tener el permiso CREATE específicamente dentro del rol Administrator.

---

⚙️ Configuración en el Componente (TypeScript)

Para usar la directiva de manera dinámica y segura, primero debes obtener los roles y permisos desde una fuente centralizada, como AlpuraStorageViewModel. Esto evita el uso de strings "mágicos" en las plantillas y centraliza la gestión de permisos.

Ejemplo en tu component.ts:

import { Component, inject } from "@angular/core";
import { AlpuraStorageViewModel } from "@alpura/commons"; // Ajusta la ruta si es necesario

@Component({
  selector: "app-mi-vista",
  templateUrl: "./mi-vista.component.html",
})
export class MiVistaComponent {
  /**
   * ViewModel para gestionar el almacenamiento de datos.
   * @private
   */
  private storage = inject(AlpuraStorageViewModel);

  /**
   * Objeto que contiene los permisos globales de la aplicación, recuperados del storage.
   * Se utiliza para obtener los valores reales de los permisos (e.g., 'Create', 'Read').
   */
  public globalPermissions = this.storage.getStorageMap(
    "APP_GLOBAL_PERMISSIONS",
  ) as Record<string, string>;

  /**
   * Objeto que contiene los roles globales de la aplicación, recuperados del storage.
   * Se utiliza para obtener los valores reales de los roles (e.g., 'ADMINISTRATOR').
   */
  public globalRoles = this.storage.getStorageMap("APP_GLOBAL_ROLES") as Record<
    string,
    string
  >;

  /**
   * Array de permisos específicos requeridos para la visualización de ciertos elementos en la plantilla.
   * Utiliza los valores de `globalPermissions`.
   */
  public permissionsView = [this.globalPermissions["Create"]];

  /**
   * Array de roles de administrador o supervisor requeridos para la visualización de ciertos elementos.
   * Utiliza los valores de `globalRoles`.
   */
  public rolesView = [
    this.globalRoles["ADMINISTRATOR"],
    this.globalRoles["SUPERVISOR"],
  ];
}

---

🚀 Casos de Uso

Aplica la directiva alpuraPermissions a cualquier elemento HTML.

Ejemplo 1: Mostrar un botón solo a usuarios con permiso de creación

<!-- El botón es visible si el usuario tiene el permiso 'Create' obtenido desde el storage -->
<button alpuraPermissions [permissions]="permissionsView">
  Crear Nuevo Registro
</button>

Ejemplo 2: Mostrar un panel de administración solo para ciertos roles

<!-- El panel es visible para usuarios con rol 'ADMINISTRATOR' o 'SUPERVISOR' -->
<div alpuraPermissions [roles]="rolesView">
  <h3>Panel de Administración</h3>
  <p>Contenido exclusivo para administradores.</p>
</div>

Ejemplo 3: Validación combinada para una acción específica

<!-- El botón "Eliminar" solo aparece si el usuario tiene el permiso 'Delete' y el rol 'ADMINISTRATOR' -->
<button
  alpuraPermissions
  [permissions]="permissionsView"
  [roles]="rolesView"
  class="btn btn-danger"
>
  Eliminar permanentemente
</button>

---

🧩 Inputs

Nombre	Tipo	Descripción
permissions	string[]	Un arreglo de strings con los nombres de los permisos requeridos.
roles	string[]	Un arreglo de strings con los nombres de los roles requeridos.

---

📤 Outputs

Esta directiva no emite ningún evento. Su única función es manipular la visibilidad del elemento anfitrión.

---

📬 Soporte

Para dudas o mantenimiento de la directiva PermissionsDirective, contactar al equipo de arquitectura o al responsable del módulo de seguridad.