Saltar a contenido

Roles y permisos

Los roles son el corazón de la seguridad de Consul Rest: agrupan lo que un conjunto de usuarios puede hacer (autorizaciones de negocio), lo que puede ver (restricciones de alcance) y sus permisos finos por módulo. Cada usuario tiene exactamente un rol; cambiar el rol cambia de inmediato lo que ese usuario puede hacer.

Ruta: /seguridad/roles · Quién la usa: administrador (requiere la autorización "Gestionar Roles").

Listado de roles

Listado de roles

  • Botón Nuevo Rol.
  • Filtros: búsqueda por texto, filtro por Tipo de Rol (SuperAdmin, Administrador, Gerente, Supervisor, Capitán, Operativo, Consulta, Externo) y botón Limpiar.
  • Tabla con columnas:
    • Rol: nombre con su punto de color, un candado gris si es rol de sistema y la leyenda "Hereda de: {rol padre}" cuando aplica.
    • Clave: identificador único (ej. ADMIN).
    • Tipo: badge del tipo de rol.
    • Nivel: jerarquía (1 = más alto).
    • Usuarios: cuántos usuarios lo tienen asignado.
    • Permisos: cuántos permisos tiene configurados.
    • Estado: badge "Acceso Total" (rojo), "Activo" (verde) o "Inactivo" (gris).
    • Acciones: editar (lápiz), Gestionar Permisos (llave azul, abre la matriz de permisos) y eliminar (solo disponible si NO es rol de sistema).

Roles que no se pueden eliminar

Los roles de sistema (marcados con candado) no se pueden eliminar. Tampoco se puede eliminar un rol que tenga usuarios asignados — el sistema lo bloquea con el aviso "Puede que tenga usuarios asignados". Reasigna primero a esos usuarios a otro rol.

Crear o editar un rol

Rutas: /seguridad/roles/nuevo y /seguridad/roles/editar/{id} — el formulario tiene tres pestañas.

Pestaña General

Campo Qué es Obligatorio
Clave Identificador único en mayúsculas (ej. ADMIN, GERENTE); no editable después de crear Sí
Nombre Nombre visible del rol Sí
Tipo de Rol Clasificación (SuperAdmin, Administrador, Gerente, Supervisor, Capitán, Operativo, Consulta, Externo); no editable después de crear Sí
Descripción Texto libre No
Color Color identificador que se muestra en los listados No
Nivel Jerarquía 1 = más alto, 100 = más bajo; algunos permisos exigen un nivel mínimo No
Rol Padre Rol del que hereda No
Hereda permisos del padre Casilla que activa la herencia de permisos No
Rol activo Solo al editar; activa/desactiva el rol No

Pestaña Autorizaciones

Cada switch controla una capacidad de negocio del rol:

Autorización Qué permite
Acceso Total (Super Admin) Ignora toda la matriz de permisos: el rol puede hacer absolutamente todo.
Autorizar Descuentos Aprobar descuentos en cuentas. Se acompaña de dos topes: Límite % Descuento y Límite Monto Descuento.
Autorizar Cancelaciones Aprobar la cancelación de órdenes o productos (por ejemplo, las solicitudes de cancelación que envían los meseros).
Autorizar Cortesías Aprobar consumos de cortesía (sin cobro).
Hacer Cortes de Caja Ejecutar el corte/cierre de caja del turno operativo.
Ver Reportes Acceso a reportes.
Exportar Datos Exportar información del sistema.
Acceder Configuración Entrar a las pantallas de configuración.
Gestionar Usuarios Administrar usuarios.
Gestionar Roles Administrar esta misma sección.

Acceso Total: usar con extrema cautela

Un rol con Acceso Total aparece con badge rojo en el listado y su matriz de permisos se deshabilita con el aviso "Todos los permisos están habilitados automáticamente". Resérvalo para el superadministrador; para todos los demás, configura autorizaciones y permisos específicos.

Descuentos con tope por rol

Los límites de descuento permiten políticas escalonadas: por ejemplo, capitán hasta 10 %, gerente hasta 25 % y administrador sin tope práctico. Si un usuario intenta un descuento por encima de su límite, necesitará que alguien con un rol superior lo autorice.

Pestaña Restricciones

Las restricciones limitan lo que el rol ve, sin importar sus permisos:

Restricción Efecto
Solo puede ver su sucursal No ve datos de otras sucursales.
Solo puede ver sus mesas Típico de meseros: solo ve las mesas que le fueron asignadas.
Solo puede ver sus órdenes Solo ve las órdenes que él mismo creó o atiende.

Matriz de permisos del rol

Ruta: /seguridad/roles/{id}/permisos — se abre con la llave azul del listado.

Aquí defines con precisión qué puede hacer el rol en cada módulo del sistema:

  • Encabezado con el nombre del rol, botón Guardar Cambios y botón "Volver a Roles".
  • Acordeón por módulo (el primero abierto): cada módulo muestra su icono, nombre y el contador "asignados / totales", más dos botones rápidos:
    • Todos: marca la casilla Ver en todos los permisos del módulo.
    • Ninguno: desmarca todo el módulo.
  • Dentro de cada módulo, una tabla de permisos con nombre y clave, y ocho casillas por permiso: Ver, Crear, Editar, Eliminar, Autorizar, Cancelar, Exportar, Imprimir.

La casilla Ver es la llave maestra

Mientras Ver no esté marcada, las demás casillas de esa fila están deshabilitadas. Al guardar, solo se conservan los permisos que tengan al menos Ver: si desmarcas Ver, ese permiso se pierde completo.

Flujo:

  1. Marca o desmarca las casillas necesarias.
  2. Pulsa Guardar Cambios → aparece "Permisos guardados correctamente".
  3. Los cambios aplican a todos los usuarios que tengan ese rol.

Módulos del sistema

Ruta: /seguridad/modulos — pantalla técnica/avanzada.

Los módulos son las secciones del sistema: lo que aparece en el menú de navegación y lo que agrupa los permisos de la matriz.

  • Listado con: Módulo (icono + nombre + "Padre: X" si es submódulo), Clave, Ruta (URL), Orden, Submódulos (conteo), Permisos (conteo), Estado ("Visible" verde / "Oculto" amarillo / "Inactivo" gris) y acciones (editar / eliminar con confirmación).
  • Formulario: Clave (solo minúsculas y guiones bajos; no editable después), Nombre, Descripción, Icono (clase Bootstrap, ej. bi bi-house), Orden (posición en el menú), Módulo Padre, Ruta (URL), casillas Visible en menú, Requiere autenticación y, al editar, Módulo activo.

Configuración de implementación, no de día a día

Modificar módulos afecta el menú y la matriz de permisos de todos los roles. Es configuración que normalmente solo se toca durante la implementación del sistema.

Catálogo de permisos

Ruta: /seguridad/permisos

Catálogo de los permisos individuales que se asignan a los roles:

  • Filtros: texto, Módulo y Tipo (Ver, Crear, Editar, Eliminar, Autorizar, Cancelar, Exportar, Imprimir, Configurar, Ejecutar, Especial — cada tipo con badge de color).
  • Tabla: Permiso (nombre + descripción + candado si es de sistema), Clave, Módulo, Tipo, Roles (cuántos roles lo usan), Estado y acciones (editar; eliminar solo si no es de sistema).
  • Formulario al crear:
Campo Qué es Obligatorio
Clave Formato "modulo.accion" (ej. usuarios.crear) Sí
Nombre Nombre visible Sí
Módulo Módulo al que pertenece Sí
Tipo de Permiso Uno de los tipos del catálogo Sí
Descripción Texto libre No
Orden Posición No
Nivel mínimo requerido Nivel de jerarquía mínimo que debe tener el rol para poder recibir este permiso No
  • Al editar: Clave, Módulo y Tipo quedan fijos (solo lectura); se pueden cambiar Nombre, Descripción, Orden, Nivel mínimo y la casilla Permiso activo.

Recomendaciones prácticas

Empieza por los roles estándar

La mayoría de los restaurantes opera bien con SUPERADMIN, ADMIN, GERENTE y roles operativos (mesero, cajero, cocina). Crea roles nuevos solo cuando necesites una combinación distinta de autorizaciones — por ejemplo, un "Capitán" que autorice descuentos hasta 10 % pero sin acceso a cortes de caja.

Usa la herencia para variantes

Si necesitas un rol casi igual a otro (ej. "Gerente Jr." basado en GERENTE), crea el nuevo rol con Rol Padre y la casilla "Hereda permisos del padre", y ajusta solo las diferencias.