# 🚀 Guía Rápida - Sistema de Permisos AAT

## 🎯 Resumen Ejecutivo

Se ha implementado un sistema completo de permisos para asegurar que solo usuarios autorizados puedan acceder a módulos específicos.

---

## ✅ ¿QUÉ SE HA IMPLEMENTADO?

### 1. **Seeder de Roles y Permisos** ✅
- **Archivo:** `database/seeders/ComprehensiveRolePermissionSeeder.php`
- **Incluye:** 18 roles + 300+ permisos
- **Cubre:** TODOS los módulos del sistema

### 2. **Middlewares en Rutas** ✅
- **Archivo:** `routes/admin.php`
- **Protección:** Todas las rutas admin requieren permisos específicos
- **Ejemplos:**
  - Formularios Dinámicos → Requiere rol `Admin_Formularios` o permiso específico
  - Capacitaciones → Requiere rol `Admin_Capacitaciones` o `Instructor`
  - Asistencia → Requiere roles de RRHH o Seguridad

### 3. **Autorizaciones en Livewire** ✅
- **Componentes Protegidos:**
  - `DynamicFormCreate` → Verifica permiso `admin.dynamic-forms.create`
  - `DynamicFormEdit` → Verifica permiso `admin.dynamic-forms.edit`
  - `DynamicFormIndex` → Verifica permiso `admin.dynamic-forms.index`

### 4. **Documentación Completa** ✅
- **Archivo:** `docs/ARQUITECTURA_PERMISOS.md`
- **Contenido:** Arquitectura completa, roles, uso, ejemplos

---

## 🔥 PASOS INMEDIATOS PARA ACTIVAR PERMISOS

### Paso 1: Ejecutar Seeder
```bash
php artisan db:seed --class=ComprehensiveRolePermissionSeeder
```

**Resultado esperado:**
```
📝 Creando permisos...
✓ XXX permisos creados
👥 Creando roles...
  ✓ Rol: Super_Admin - Acceso total al sistema
  ✓ Rol: Admin - Administrador general del sistema
  ✓ Rol: Admin_RRHH - Administrador de Recursos Humanos
  ...
🔐 Asignando permisos a roles...
  ✓ Super_Admin: Todos los permisos asignados
  ✓ Admin: Todos los permisos asignados
  ...
✅ Sistema de permisos configurado correctamente
```

### Paso 2: Asignar Rol a Tu Usuario Admin
```bash
php artisan tinker
```

Dentro de tinker:
```php
$user = User::where('email', 'tu-email@admin.com')->first();
$user->assignRole('Admin');
// O si ya tienes un usuario con rol Admin:
$user->syncRoles(['Admin']); // Reemplaza roles existentes
exit
```

### Paso 3: Asignar Roles a Usuarios Específicos

Para el usuario que mencionaste (`fabian.mejia@utp.edu.co`), asignar rol específico:

```bash
php artisan tinker
```

```php
// Si debe tener acceso a formularios dinámicos:
$user = User::where('email', 'fabian.mejia@utp.edu.co')->first();
$user->assignRole('Admin_Formularios');

// Si debe tener acceso limitado:
$user->assignRole('Empleado');

// Si NO debe tener acceso a ningún módulo admin:
$user->syncRoles([]); // Eliminar todos los roles

exit
```

---

## 👥 ROLES PRINCIPALES

### Para Administradores:
- **Super_Admin** → Acceso TOTAL (para desarrollo/mantenimiento)
- **Admin** → Acceso a todo (para administración general)

### Para Módulos Específicos:
- **Admin_Formularios** → Gestión de Formularios Dinámicos
- **Admin_Capacitaciones** → Sistema de Capacitaciones
- **Admin_RRHH** → Recursos Humanos (empleados, permisos, asistencia)
- **Admin_Inventario** → Gestión de Activos e Inventario
- **Admin_Mantenimiento** → Mantenimiento y SGI
- **Admin_Seguridad** → Visitantes y Control de Acceso
- **Director_HSEQ** → PQRSD y Reportes ORAC
- **Admin_Sistema** → Gestión de usuarios, roles y permisos

### Para Usuarios Operativos:
- **Operador_Inventario** → Registro de activos (sin eliminar)
- **Tecnico_Mantenimiento** → Registros de mantenimiento
- **Instructor** → Gestión de temas y evaluaciones de capacitación
- **Vigilante** → Terminal de visitantes
- **Empleado** → Permisos propios y asistencia

---

## 🔍 VERIFICAR QUE FUNCIONA

### Test 1: Usuario Sin Rol
```bash
# En navegador, cerrar sesión
# Iniciar sesión con: fabian.mejia@utp.edu.co
# Intentar acceder a: http://127.0.0.1:8000/admin/dynamic-forms/create
```

**Resultado esperado:** ❌ Error 403 "No tienes permiso para crear formularios dinámicos."

### Test 2: Usuario Con Rol Correcto
```bash
# Asignar rol en tinker:
$user = User::where('email', 'tu-admin@email.com')->first();
$user->assignRole('Admin_Formularios');

# En navegador, iniciar sesión con ese usuario
# Acceder a: http://127.0.0.1:8000/admin/dynamic-forms/create
```

**Resultado esperado:** ✅ Página carga correctamente

### Test 3: Verificar Logs
```bash
tail -f storage/logs/laravel.log
```

**Buscar líneas como:**
```
Usuario accedió a creación de formulario dinámico {"user_id":1,"user_email":"admin@example.com"}
```

---

## 📦 ESTRUCTURA DE PERMISOS

### Nomenclatura:
```
admin.{module}.{action}
```

### Ejemplos:
```
admin.dynamic-forms.index    → Ver lista
admin.dynamic-forms.create   → Crear nuevo
admin.dynamic-forms.edit     → Editar existente
admin.dynamic-forms.destroy  → Eliminar
admin.dynamic-forms.publish  → Publicar (acción especial)
```

---

## 🛠️ COMANDOS ÚTILES

### Ver Todos los Roles:
```php
php artisan tinker
Role::all()->pluck('name');
```

### Ver Todos los Permisos:
```php
Permission::all()->pluck('name')->take(20); // Primeros 20
```

### Ver Roles de un Usuario:
```php
$user = User::find(1);
$user->getRoleNames();
```

### Ver Permisos de un Usuario:
```php
$user = User::find(1);
$user->getAllPermissions()->pluck('name');
```

### Asignar Múltiples Roles:
```php
$user->syncRoles(['Admin_Formularios', 'Admin_Capacitaciones']);
```

### Dar Permiso Directo (sin rol):
```php
use Spatie\Permission\Models\Permission;
$permission = Permission::findByName('admin.dynamic-forms.create');
$user->givePermissionTo($permission);
```

---

## 🚨 PROBLEMAS COMUNES

### Problema: "This action is unauthorized" en Livewire
**Solución:** El usuario no tiene el rol/permiso necesario.
```php
// Verificar roles del usuario:
$user = User::find(USUARIO_ID);
$user->getRoleNames(); // Ver roles actuales
$user->assignRole('ROL_NECESARIO'); // Asignar rol
```

### Problema: "Route [admin.dynamic-forms.index] not defined"
**Solución:** Error de rutas, no de permisos. Verificar `routes/admin.php`.

### Problema: Usuario admin tampoco puede acceder
**Solución:** Verificar que el usuario tenga rol asignado:
```php
$user = User::where('email', 'admin@example.com')->first();
$user->assignRole('Admin');
```

### Problema: Cambios no se reflejan
**Solución:** Limpiar caché:
```bash
php artisan cache:clear
php artisan config:clear
php artisan view:clear
```

---

## 📋 CHECKLIST DE IMPLEMENTACIÓN

- [x] Seeder de roles y permisos creado
- [x] Middlewares aplicados en rutas admin
- [x] Autorizaciones en componentes Livewire
- [x] Documentación completa generada
- [ ] **Seeder ejecutado** → `php artisan db:seed --class=ComprehensiveRolePermissionSeeder`
- [ ] **Roles asignados a usuarios** → Usar `tinker` para asignar
- [ ] **Pruebas con usuario sin permisos** → Verificar error 403
- [ ] **Pruebas con usuario con permisos** → Verificar acceso correcto
- [ ] **Logs verificados** → Revisar `storage/logs/laravel.log`

---

## 🎓 MEJORES PRÁCTICAS

### 1. Principio de Menor Privilegio
✅ Dar solo los permisos mínimos necesarios  
❌ No dar `Super_Admin` a usuarios regulares

### 2. Usar Roles, No Permisos Directos
✅ `$user->assignRole('Admin_Formularios')`  
❌ `$user->givePermissionTo('admin.dynamic-forms.create')` (usar solo en casos especiales)

### 3. Verificar en Múltiples Capas
✅ Middleware en rutas  
✅ Autorización en controladores  
✅ `@can` en vistas  
❌ Confiar solo en ocultar elementos en la UI

### 4. Auditar Accesos
✅ Logging de accesos a módulos críticos  
✅ Revisión periódica de roles asignados  
❌ Dar permisos y olvidarse

---

## 📞 SIGUIENTE PASO

**EJECUTAR EL SEEDER AHORA:**
```bash
cd C:\xampp\htdocs\laravel\aat
php artisan db:seed --class=ComprehensiveRolePermissionSeeder
```

**Luego asignar roles a tus usuarios principales.**

---

**Fecha:** 2025-01-12  
**Versión:** 1.0.0  
**Estado:** ✅ Implementado, ⏳ Pendiente activar

