Roles y permisos¶

¿Qué es?¶

El módulo de Roles y permisos define qué puede hacer cada tipo de usuario en el portal web y en la app móvil. Un rol es un conjunto nombrado de permisos que se asigna a usuarios. Los permisos se configuran módulo por módulo con checkboxes individuales para cada acción posible.

Conceptos clave¶

Rol¶

Un rol es un grupo de permisos con nombre y descripción. Ejemplos: "Administrador", "Supervisor zona norte", "Solo lectura". Los roles se asignan a usuarios desde el módulo de Usuarios.

Tipos de rol¶

Rol de sistema (is_system = true) — Marcado con badge naranja "Sistema" en la lista. No se puede editar, renombrar ni eliminar. Sus permisos son de solo lectura.
Rol personalizado — Creado por el administrador. Se pueden editar sus permisos, renombrar y eliminar.

Permiso¶

Un permiso es una acción específica sobre un módulo. Ejemplos: employees: view, contracts: create, reports: export. Cada módulo soporta un subconjunto de las 7 acciones posibles.

Un módulo es una sección del sistema (ej. Empleados, Asistencia, Contratos). Cada módulo tiene un code interno y puede aparecer en el portal, la app móvil o ambos (scope).

Vista principal¶

La página tiene un layout de dos paneles:

Panel izquierdo: Lista de roles¶

Panel de 256 px de ancho fijo, pegado al tope de la pantalla al hacer scroll.

Lista de todos los roles del sistema.
Por cada rol se muestra: nombre y cantidad de usuarios asignados ("N usuarios").
El rol seleccionado se resalta con fondo de marca.
Los roles de sistema tienen badge naranja "Sistema".
Los roles personalizados muestran dos íconos al pasar el cursor:
Lápiz — Editar nombre y descripción (requiere roles_permissions: edit).
Papelera — Eliminar el rol (requiere roles_permissions: delete).
Botón "Nuevo" en la cabecera del panel (requiere roles_permissions: create).

Panel derecho: Matriz de permisos¶

Se activa al seleccionar un rol. Si no hay rol seleccionado, muestra "Selecciona un rol para ver sus permisos".

Cabecera del panel derecho¶

Nombre del rol seleccionado.
Para roles de sistema: aviso naranja "Rol del sistema — solo lectura".
Para roles personalizados: descripción del rol (si tiene).
Botón "Guardar permisos" — Aparece activo solo cuando hay cambios pendientes (dirty = true) y el usuario tiene permiso de edición. Si no hay cambios, muestra "Sin cambios" en gris deshabilitado.

Filtro de ámbito (tabs)¶

Tres tabs que filtran las filas de la matriz:

Tab	Descripción
Todos	Muestra todos los módulos (portal + app)
App	Solo módulos de la app móvil (`scope = app` o `scope = both`)
Portal	Solo módulos del portal web (`scope = portal` o `scope = both`)

Estructura de la matriz¶

La tabla tiene: - Columna Módulo — Nombre del módulo. Las filas de categoría (cabeceras de sección) aparecen con fondo gris y texto en mayúsculas. - 7 columnas de permisos — Una por cada acción posible. - Columna "Aplica en" — Solo visible en el tab "Todos". Badge que indica el ámbito del módulo.

Columnas de permisos¶

Columna	Clave	Descripción
Ver	`can_view`	Acceder a la página o módulo
Crear	`can_create`	Crear nuevos registros
Editar	`can_edit`	Modificar registros existentes
Eliminar	`can_delete`	Eliminar registros
Exportar	`can_export`	Exportar datos (CSV, Excel, PDF)
Importar	`can_import`	Importar datos masivos
Enviar	`can_send`	Enviar notificaciones u otras acciones de envío

No todos los módulos soportan todas las acciones. Si un módulo no soporta una acción, la celda muestra "—" en lugar de un checkbox.

Excepción especial: El módulo settings (Configuración) tiene el permiso Ver siempre activo y se muestra como "Siempre" (no es un checkbox editable). Esto es porque la página de Configuración es necesaria para que el usuario pueda cerrar sesión.

Categorías de módulos¶

Los módulos se organizan en tres categorías que aparecen como filas de cabecera en la matriz:

Categoría	Código	Módulos típicos
Personas	`people`	Empleados, Usuarios, Contratos, Ausencias
Operaciones	`operations`	Asistencia, Turnos, Monitor, Minutas, Novedades, Adicionales, Formularios, Reportes
Admin	`admin`	Clientes, Proyectos, Puestos, Zonas, Nómina, Configuración, Roles y permisos

Badges de ámbito (Aplica en)¶

En el tab "Todos", la columna "Aplica en" muestra un badge por módulo:

Badge	Significado
Portal (índigo)	El módulo solo aparece en el portal web
App (verde esmeralda)	El módulo solo aparece en la app móvil
Ambos (gris)	El módulo aparece tanto en el portal como en la app

El mismo rol controla el acceso en ambas superficies. Un usuario con rol "Supervisor" tendrá los mismos permisos en el portal y en la app.

Reglas de permisos interdependientes¶

El sistema aplica dos reglas automáticamente al cambiar checkboxes:

Si se activa cualquier permiso distinto de "Ver" → el permiso "Ver" se activa automáticamente (no tiene sentido crear sin poder ver).
Si se desactiva "Ver" → todos los demás permisos del módulo se desactivan automáticamente.

Esto garantiza que los permisos sean coherentes.

Acciones disponibles¶

Crear nuevo rol¶

Botón "Nuevo" en la cabecera del panel izquierdo. Abre el modal de creación. Requiere permiso roles_permissions: create.

Editar nombre de un rol¶

Ícono de lápiz al pasar el cursor sobre el rol en la lista. Abre el modal de edición. Requiere permiso roles_permissions: edit. No disponible para roles de sistema.

Eliminar un rol¶

Ícono de papelera al pasar el cursor sobre el rol en la lista. Muestra diálogo de confirmación: "¿Eliminar el rol 'Nombre'? Esta acción no se puede deshacer." Requiere permiso roles_permissions: delete. No disponible para roles de sistema.

Nota: Si el rol tiene usuarios asignados, el servidor puede rechazar la eliminación.

Guardar permisos¶

Botón "Guardar permisos" en la cabecera del panel derecho. Solo aparece activo cuando hay cambios pendientes. Al guardar, si el administrador está editando su propio rol, los cambios se propagan inmediatamente (el sidebar y los controles del portal se actualizan sin recargar la página).

Campos¶

Nombre — Nombre del rol (obligatorio). Ej: "Supervisor zona norte". Se presiona Enter para guardar.
Descripción — Texto descriptivo opcional del rol.

Validaciones¶

El nombre es obligatorio: "El nombre es requerido".

Comportamiento al cambiar de rol con cambios sin guardar¶

Si el usuario tiene cambios pendientes en la matriz y hace clic en otro rol, aparece un diálogo:

"Cambios sin guardar" — "¿Descartar los cambios de permisos del rol actual?"

Descartar → Abandona los cambios y carga el nuevo rol.
Cancelar → Permanece en el rol actual con los cambios intactos.

Este diálogo no aparece para roles de sistema (que son de solo lectura).

Permisos necesarios para usar este módulo¶

Acción	Permiso requerido
Ver la página y la matriz	`roles_permissions: view`
Crear un rol	`roles_permissions: create`
Editar nombre/descripción o guardar permisos	`roles_permissions: edit`
Eliminar un rol	`roles_permissions: delete`

Páginas relacionadas¶

Usuarios — Los roles se asignan a usuarios desde el módulo de Usuarios. El campo role_id en el formulario de usuario vincula el rol.
Configuración — La configuración del perfil del usuario está relacionada con el permiso settings: view.

Preguntas frecuentes¶

¿Qué pasa si un usuario no tiene rol asignado? El sistema muestra "Sin rol" en la lista de usuarios. Un usuario sin rol solo tiene acceso a los módulos que están configurados como accesibles por defecto (generalmente solo la página de configuración para poder cerrar sesión).

¿Puedo duplicar un rol existente? No existe un botón de duplicar en la interfaz. Debes crear un rol nuevo y configurar sus permisos manualmente checkbox por checkbox.

¿Los cambios de permisos afectan a los usuarios actualmente conectados? Sí, los cambios de permisos se aplican de inmediato. La próxima acción del usuario (navegar a otra página, recargar) reflejará los nuevos permisos. Si el administrador edita su propio rol, el cambio se propaga sin necesidad de recargar.

¿Por qué el permiso "Ver" de Configuración no se puede desactivar? La página de Configuración contiene el botón de cierre de sesión. Si se pudiera desactivar "Ver" en Configuración, los usuarios quedarían atrapados sin poder cerrar sesión. Por eso siempre está activo y se muestra como "Siempre".

¿Puedo editar los permisos de un rol de sistema? No. Los roles de sistema son de solo lectura y sus permisos no se pueden modificar desde la interfaz. El panel muestra "Rol del sistema — solo lectura" y los checkboxes aparecen deshabilitados.

¿Los permisos "Importar" y "Enviar" aplican a todos los módulos? No. Solo los módulos que soportan esas acciones muestran el checkbox correspondiente. En módulos que no soportan importar o enviar, la celda muestra "—".

¿El filtro de ámbito (App/Portal/Todos) cambia los permisos guardados? No. El filtro solo cambia qué filas se muestran en la pantalla para facilitar la revisión. Los permisos guardados aplican en todos los ámbitos independientemente del filtro visual.