09 Módulo Empleados y Usuarios Con Roles 👥 CRUD en Laravel en Laravel - Sistema de Activos Fijos
Duración: 36 minDescripción
🎓 Lección 09: Módulo de Personal y Usuarios: Custodia de Bienes, Cuentas de Acceso y Transacciones en Laravel 13
Esta lección aborda la construcción del módulo de personal para formalizar la asignación física y custodia responsable de los activos fijos empresariales. Se implementa una arquitectura desacoplada que permite registrar empleados administrativos u operativos y vincularlos de forma opcional con cuentas de usuario del sistema bajo transacciones de base de datos atómicas y roles de Spatie.
🚀 Pasos Clave con Timestamps
- 🧑💼 Fundamento de Custodia Física y Responsabilidad Laboral (⏱️ 00:00): Definición de la importancia de vincular los activos fijos a un empleado responsable específico (custodio de laptops, impresoras, maquinaria), evitando que los bienes queden desasociados dentro de la empresa.
- 📐 Modelado Entidad-Relación y Tablas Pivote en DBML (⏱️ 01:45): Análisis en diagrama.dbml de la estructura de empleados y su coexistencia con la tabla nativa users y las tablas pivote de Spatie (model_has_roles), comprendiendo que no todos los trabajadores requieren credenciales de acceso.
- 🏗️ Generación de Modelo, Migración y Controlador RESTful (⏱️ 03:10): Ejecución del comando Artisan php artisan make:model empleado -mcr para generar en una sola instrucción el modelo en singular, su archivo de migración y el controlador con recursos.
- 🗄️ Definición de Claves Foráneas Opcionales y Campo Documento (⏱️ 04:30): Configuración de la migración con user_id anulable (nullable) con regla onDelete('set null'), relaciones obligatorias a sucursals y departamentos en cascada, y estandarización del atributo documento para compatibilidad internacional (CI/DNI).
- 🧭 Enrutamiento Web y Nuevo Ítem en el Sidebar (⏱️ 06:15): Registro de las rutas de recursos en routes/web.php bajo protección del middleware auth, e inserción del ítem de navegación "Empleados" en el menú lateral de Adminator.
- 📊 Panel Principal con Filtros Cruzados y Métricas (index) (⏱️ 08:00): Construcción de la vista del listado general con tarjetas de indicadores (total empleados, activos, inactivos y con acceso al sistema), buscador y filtros selectores por sucursal, departamento y estado.
- 🏢 Formulario Extendido y Selectores Dependientes (create) (⏱️ 10:20): Ampliación de la tarjeta del formulario al ancho total (full-width) e integración de lógica condicional para que el selector de departamentos filtre automáticamente solo las áreas pertenecientes a la sucursal seleccionada.
- 🔐 Habilitación Dinámica de Credenciales y Roles Spatie (⏱️ 12:45): Inclusión de una casilla interactiva (checkbox) que despliega un panel secundario con correo, contraseña y selector de rol de Spatie (ej. Contador, Encargado de activos) exclusivamente si el empleado necesita operar el software.
- 🔄 Persistencia Multitabla con Transacciones Atómicas (store) (⏱️ 15:10): Implementación de bloques DB::beginTransaction(), DB::commit() y DB::rollBack() dentro del controlador para coordinar el guardado simultáneo en las tablas empleados, users y model_has_roles ante cualquier excepción.
- 📋 Detalle Completo y Modificación de Cuentas (show / edit) (⏱️ 17:35): Visualización desglosada del puesto laboral, sede y estado de cuenta, junto con la vista de edición que permite otorgar o revocar el acceso al sistema actualizando los roles asignados.
- 🗑️ Eliminación Segura y Limpieza de Huérfanos en BD (destroy) (⏱️ 19:40): Perfeccionamiento del borrado en el controlador para que, al eliminar un empleado con acceso, se remueva simultáneamente su usuario asociado y se revoquen sus roles en model_has_roles, respaldado por una alerta modal de advertencia en SweetAlert2.
🛠️ Comandos y Rutas Principales
| Componente / Acción | Comando Artisan / Sintaxis de Ruta | Archivo / Controlador | Propósito Técnico |
|---|---|---|---|
| Estructura Empleados | php artisan make:model empleado -mcr | Terminal / Artisan | Crear modelo Empleado, archivo de migración y EmpleadoController |
| Migración BD | php artisan migrate | database/migrations/..._create_empleados_table.php | Generar la tabla empleados con clave foránea opcional a users |
| Listado de Personal | GET /admin/empleados | EmpleadoController@index | Visualizar tabla de empleados con tarjetas KPI y filtros combinados |
| Formulario de Alta | GET /admin/empleados/create | EmpleadoController@create | Renderizar formulario con sedes, departamentos y selector de roles |
| Registro Transaccional | POST /admin/empleados | EmpleadoController@store | Ejecutar DB::transaction para guardar empleado, usuario y rol Spatie |
| Ficha del Empleado | GET /admin/empleados/{id} | EmpleadoController@show | Consultar datos personales, cargo, ubicación y cuenta de acceso vinculada |
| Formulario de Edición | GET /admin/empleados/{id}/edit | EmpleadoController@edit | Abrir formulario para modificar datos o gestionar el acceso al software |
| Actualizar Personal | PUT /admin/empleados/{id} | EmpleadoController@update | Actualizar atributos y sincronizar credenciales/roles de usuario |
| Eliminación Integral | DELETE /admin/empleados/{id} | EmpleadoController@destroy | Suprimir registro de empleado y remover su cuenta de usuario y rol pivote |
🔒 Buenas Prácticas y Seguridad
- ⚛️ Atomicidad con Transacciones de Base de Datos (DB::transaction): La creación de un empleado con acceso involucra hasta tres escrituras simultáneas (empleados, users y model_has_roles). Utilizar DB::beginTransaction() con bloques try/catch garantiza que, si alguna inserción falla, se ejecute un DB::rollBack() que evite usuarios huérfanos o empleados sin credenciales registradas.
- 🧩 Desacoplamiento entre Personal Operativo y Cuentas de Acceso: Configurar la clave foránea $table->foreignId('user_id')->nullable()->constrained('users')->onDelete('set null') permite gestionar colaboradores que custodian activos (operarios, choferes, personal de limpieza) sin necesidad de forzar la creación de un usuario o exponer credenciales de acceso innecesarias.
- 🧹 Depuración Bidireccional en Acciones Destructivas: Al eliminar un empleado con cuenta activa, el método destroy() debe verificar la existencia del user_id para eliminar tanto el registro del trabajador como el registro de la tabla users y su correspondiente rol en la tabla pivote de Spatie, notificando explícitamente dicho alcance en el diálogo de confirmación.
- 🎯 Consistencia de Entradas con Nomenclatura Global: Sustituir campos de identificación localistas (como "carnet de identidad" o "CI") por identificadores globales como documento previene problemas de adaptación si la plataforma se implementa en diferentes marcos tributarios o regiones (DNI, RFC, Cédula).