Descripción General
El sistema de roles y permisos permite controlar el acceso a funcionalidades mediante un modelo basado en resource.action. Cada usuario tiene un rol asignado, y cada rol tiene un conjunto de permisos configurables.Modelo de Permisos
Estructura del Permiso
Los permisos siguen el patrónresource.action:
Tablas de Base de Datos
Roles del Sistema
Rol Administrador (rol_id = 1)
El administrador tiene privilegios especiales:- Acceso total: Bypasea todas las verificaciones de permisos
- Multi-empresa: Puede ver y cambiar entre todas las empresas activas
- Sin restricciones: No requiere permisos explícitos en
role_permission
app/Models/User.php:78
Roles Personalizados
Los roles no-admin tienen permisos configurables:- Vendedor
- Cajero
- Almacenero
- Contador
Verificación de Permisos
Middleware CheckPermission
El middlewareCheckPermission protege las rutas API:
app/Http/Middleware/CheckPermission.php:17
Uso en Rutas
routes/api.php
API de Permisos
Listar Todos los Permisos
Filtrar por módulo específico
Obtener Permisos del Usuario Autenticado
Obtener Permisos de un Rol
Actualizar Permisos de un Rol
Array de IDs de permisos a asignar
Refrescar Permisos del Usuario
Después de cambiar permisos, el frontend debe solicitar la recarga:Módulos de Permisos
Lista de módulos con permisos configurables:| Módulo | Permisos Disponibles | Descripción |
|---|---|---|
ventas | view, create, edit, delete | Facturación y ventas |
productos | view, create, edit, delete | Gestión de inventario |
clientes | view, create, edit, delete | Base de clientes |
proveedores | view, create, edit, delete | Gestión de proveedores |
compras | view, create, edit, delete | Registro de compras |
cotizaciones | view, create, edit, delete | Cotizaciones |
guias-remision | view, create, edit, delete | Guías de remisión |
cuentas-cobrar | view, edit | Cuentas por cobrar |
cuentas-pagar | view, edit | Cuentas por pagar |
caja | view, create, edit, delete, abrir, autorizar | Gestión de cajas (ver Permisos de Caja) |
banco | view, create, edit, delete | Cuentas bancarias |
finanzas | view, create, edit, delete | Reportes financieros |
utilidades | view | Dashboard de utilidades |
Ejemplo de Implementación
Propiedades Especiales de Roles
ver_precios
Controla si los usuarios con este rol pueden ver información de precios:- Precio de compra
- Precio de venta
- Márgenes de utilidad
- Costos en reportes
puede_eliminar
Permite o restringe la eliminación de registros críticos:- Ventas emitidas
- Compras contabilizadas
- Documentos enviados a SUNAT
Estas propiedades son adicionales a los permisos granulares. Un usuario puede tener
ventas.delete pero si puede_eliminar = false, no podrá eliminar registros.Códigos de Error
| Código | Mensaje | Causa |
|---|---|---|
| 401 | No autenticado | Token inválido o ausente |
| 403 | No tienes permiso para realizar esta acción | Usuario no tiene el permiso requerido |
| 404 | Rol no encontrado | El rol_id no existe |
| 422 | Error de validación | Datos inválidos en la solicitud |
| 500 | Error al actualizar permisos | Error de base de datos |
Mejores Prácticas
Principio de Mínimo Privilegio
Asigna solo los permisos estrictamente necesarios para cada rol.
Validación en Backend
NUNCA confíes solo en validación frontend. Siempre verifica permisos en el servidor.
Auditoría de Cambios
Registra quién cambia permisos de roles usando timestamps en role_permission.
Testing de Permisos
Prueba cada endpoint con diferentes roles para asegurar el control de acceso.