111 lines
3.1 KiB
Markdown
111 lines
3.1 KiB
Markdown
# Koneko User Interaction Logger Helper Guide
|
|
|
|
El sistema de interacciones de usuario de Koneko permite registrar acciones relevantes dentro de la interfaz de usuario (UI) o backend, con fines de auditoría, trazabilidad, y seguridad.
|
|
|
|
> Este mecanismo está diseñado para ser invocado desde componentes Livewire, controladores o procesos sensibles que desees monitorear.
|
|
|
|
---
|
|
|
|
### ✅ Uso recomendado
|
|
|
|
Usa el helper `log_interaction()` para registrar cualquier acción de interacción importante:
|
|
|
|
```php
|
|
log_interaction('update_profile', [
|
|
'changes' => $changes,
|
|
]);
|
|
```
|
|
|
|
Puedes especificar el nivel de seguridad de la acción:
|
|
|
|
```php
|
|
log_interaction('delete_user', [
|
|
'user_id' => $user->id,
|
|
], 'high');
|
|
```
|
|
|
|
Si estás dentro de Livewire:
|
|
|
|
```php
|
|
log_interaction('submit_form', [], 'normal', 'components.users.create-user');
|
|
```
|
|
|
|
---
|
|
|
|
### 💡 Sintaxis completa
|
|
|
|
```php
|
|
log_interaction(
|
|
string $action,
|
|
array $context = [],
|
|
InteractionSecurityLevel|string $security = 'normal',
|
|
?string $livewireComponent = null
|
|
): ?UserInteraction
|
|
```
|
|
|
|
| Parámetro | Descripción |
|
|
|---------------------|------------------------------------------------------------------------------|
|
|
| `$action` | Nombre de la acción realizada, ejemplo: `create_order`, `login_success` |
|
|
| `$context` | Arreglo con datos adicionales relevantes. Puede incluir cambios, payloads...|
|
|
| `$security` | Nivel de seguridad: `low`, `normal`, `high`, `critical` |
|
|
| `$livewireComponent`| Ruta del componente Livewire, si aplica |
|
|
|
|
---
|
|
|
|
### 🔍 Ejemplo realista
|
|
|
|
```php
|
|
log_interaction(
|
|
action: 'update_user_permissions',
|
|
context: [
|
|
'user_id' => $user->id,
|
|
'new_roles' => $roles,
|
|
],
|
|
security: 'high',
|
|
livewireComponent: 'components.admin.users.user-edit-panel'
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
### 📃 Sobre el modelo `UserInteraction`
|
|
|
|
No necesitas instanciar ni importar la clase `UserInteraction` para registrar interacciones. Sin embargo, si deseas auditar desde base de datos o hacer queries personalizados, puedes usar scopes como:
|
|
|
|
```php
|
|
UserInteraction::byModule('admin')->latest()->get();
|
|
```
|
|
|
|
---
|
|
|
|
### 🔧 Extendibilidad
|
|
|
|
Puedes extender `KonekoUserInteractionLogger` para registrar interacciones con fuentes externas, agregar metadata, o enviar notificaciones.
|
|
|
|
---
|
|
|
|
### ❌ Buenas prácticas a evitar
|
|
|
|
- No usar `UserInteraction::create(...)` manualmente.
|
|
- No cambiar campos protegidos (`action`, `security_level`, etc.) después del registro.
|
|
- No registrar acciones irrelevantes o sin contexto claro.
|
|
|
|
---
|
|
|
|
### 📆 Logs relacionados
|
|
|
|
- `log_system()` — para eventos del sistema.
|
|
- `log_security()` — para eventos de seguridad como accesos o bloqueos.
|
|
|
|
---
|
|
|
|
### 🚀 Módulos compatibles
|
|
|
|
Este sistema está disponible para todos los componentes que registren `componentNamespace` en su `KonekoModule.php`, permitiendo trazabilidad completa por módulo.
|
|
|
|
---
|
|
|
|
### 🌟 Tip final
|
|
|
|
Agrégalo a tus componentes Livewire clave para auditar formularios, acciones de administración, y cambios críticos del sistema.
|