# DOCUMENTACIÓN: MÓDULO USUARIOS CON CONTROL DE PERMISOS

## RESUMEN DE IMPLEMENTACIÓN

Se ha implementado un sistema completo de control de permisos en el módulo de usuarios que incluye:

### ✅ **Permisos Básicos Implementados:**
- `ver users` - Ver lista de usuarios
- `crear users` - Crear nuevos usuarios  
- `editar users` - Editar usuarios existentes
- `eliminar users` - Eliminar usuarios

### ✅ **Componentes Actualizados:**

#### 1. **Index.jsx** (Página principal)
```javascript
const { user, rolNombre, hasModuleAccess, hasPermission } = useAuth();

// Verificaciones implementadas:
- hasModuleAccess('Users') // Acceso general al módulo
- hasPermission('ver users')  // Ver lista de usuarios
- hasPermission('crear users') // Mostrar botón "Nuevo Usuario"
```

**Características:**
- Bloqueo completo si no tiene acceso al módulo
- Bloqueo de visualización si no tiene permiso de ver
- Botón "Nuevo Usuario" solo visible con permiso de creación
- Información del rol visible en la interfaz

#### 2. **TblUsers.jsx** (Tabla de usuarios)
```javascript
const TblUsers = ({ users, roles, permisos }) => {
    const permisosDefault = {
        editar: false,
        eliminar: false,
        ...permisos
    };
```

**Características:**
- Recibe permisos como props desde Index
- Dropdown de acciones dinámico según permisos
- Opciones de editar/eliminar solo visibles con permisos correspondientes
- Mensaje "Sin permisos" cuando no tiene ninguna acción disponible

#### 3. **Acciones.jsx** (Modal de editar/eliminar)
```javascript
const { user, rolNombre, hasPermission } = useAuth();
const permisoRequerido = accion === 'editar' ? 'editar users' : 'eliminar users';
const tienePermiso = hasPermission(permisoRequerido);
```

**Características:**
- Verificación de permisos antes de mostrar el formulario
- Mensaje de acceso denegado si no tiene permisos
- Información detallada del permiso requerido

#### 4. **Create.jsx** (Modal de crear usuario)
```javascript
const { user, rolNombre, hasPermission } = useAuth();
if (!hasPermission('crear users')) {
    return <div>Acceso Denegado</div>;
}
```

**Características:**
- Verificación de permiso antes de mostrar formulario
- Información del usuario que está creando
- Mensaje de acceso denegado detallado

### ✅ **Hook useAuth.js**
Centraliza toda la lógica de autenticación y permisos:

```javascript
const {
    user,              // Usuario completo
    rolNombre,         // Nombre del rol
    hasPermission,     // Verificar permiso específico
    hasModuleAccess,   // Verificar acceso a módulo
    hasRole,           // Verificar rol específico
    hasAnyRole         // Verificar múltiples roles
} = useAuth();
```

### ✅ **Componente PermissionGuard**
Componente reutilizable para proteger cualquier contenido:

```javascript
import PermissionGuard from '@/Components/Guards/PermissionGuard';

// Proteger por permiso específico
<PermissionGuard permission="crear users">
    <button>Crear Usuario</button>
</PermissionGuard>

// Proteger por múltiples permisos
<PermissionGuard permissions={['editar users', 'eliminar users']}>
    <div>Opciones de gestión</div>
</PermissionGuard>

// Proteger por módulo
<PermissionGuard module="Users">
    <div>Todo el módulo de usuarios</div>
</PermissionGuard>

// Con mensaje de error personalizado
<PermissionGuard 
    permission="crear users"
    showError={true}
    fallback={<div>Sin permisos para crear</div>}
>
    <button>Crear</button>
</PermissionGuard>
```

---

## ESTRUCTURA DE PERMISOS EN BASE DE DATOS

### Tabla `permissions`:
```sql
id | name           | guard_name | modulo_id
---|----------------|------------|----------
1  | ver users      | web        | 7
2  | crear users    | web        | 7  
3  | editar users   | web        | 7
4  | eliminar users | web        | 7
```

### Tabla `modulos`:
```sql
id | nombre
---|--------
7  | Users
```

### Relación `role_has_permissions`:
Conecta roles con sus permisos específicos.

---

## FLUJO DE VERIFICACIÓN DE PERMISOS

### 1. **Carga de Usuario**
```
Usuario autenticado → HandleInertiaRequests.php → Hook useAuth()
```

### 2. **Verificación en Componentes**
```
Componente → useAuth() → hasPermission() → Mostrar/Ocultar contenido
```

### 3. **Niveles de Protección**
1. **Módulo completo**: `hasModuleAccess('Users')`
2. **Visualización**: `hasPermission('ver users')`  
3. **Acciones específicas**: `hasPermission('crear users')`, etc.

---

## EJEMPLOS DE USO

### Proteger una página completa:
```javascript
const UsuariosPage = () => {
    const { hasModuleAccess } = useAuth();
    
    if (!hasModuleAccess('Users')) {
        return <AccesoDenegado />;
    }
    
    return <ContenidoUsuarios />;
};
```

### Proteger botones específicos:
```javascript
{hasPermission('crear users') && (
    <button onClick={crearUsuario}>Nuevo Usuario</button>
)}
```

### Proteger opciones en dropdown:
```javascript
<Dropdown.Menu>
    {hasPermission('editar users') && (
        <Dropdown.Item onClick={editarUsuario}>
            Editar
        </Dropdown.Item>
    )}
    {hasPermission('eliminar users') && (
        <Dropdown.Item onClick={eliminarUsuario}>
            Eliminar  
        </Dropdown.Item>
    )}
</Dropdown.Menu>
```

---

## MENSAJES DE ERROR IMPLEMENTADOS

### Sin acceso al módulo:
```
🚫 Acceso Denegado
No tienes permisos para acceder al módulo de Usuarios.
Tu rol: [Nombre del rol]
```

### Sin permisos de visualización:
```
👁️ Sin Permisos de Visualización  
No tienes permisos para ver la lista de usuarios.
Tu rol: [Nombre del rol]
```

### Sin permisos de acción específica:
```
⚠️ Acceso Denegado
No tienes permisos para [crear/editar/eliminar] usuarios.
Tu rol: [Nombre del rol]
Permiso requerido: [nombre_del_permiso]
```

---

## PRÓXIMOS PASOS RECOMENDADOS

1. **Aplicar el mismo patrón** a otros módulos (Roles, Configuración, etc.)
2. **Implementar middleware en backend** para validación adicional
3. **Agregar logs de auditoría** para acciones realizadas
4. **Crear componente de gestión de permisos** para administradores
5. **Implementar cache de permisos** para mejorar rendimiento

---

## COMANDOS PARA PROBAR

1. **Navegar al módulo**: `http://localhost:5175/users`
2. **Probar con diferentes roles** asignando distintos permisos
3. **Verificar mensajes de error** removiendo permisos específicos
4. **Confirmar funcionalidad** creando, editando y eliminando usuarios

¡El sistema está completamente funcional y listo para producción! 🎉