127 lines
3.9 KiB
Markdown
127 lines
3.9 KiB
Markdown
# Koneko System Logger Helper Guide
|
|
|
|
El sistema de logs de sistema en Koneko ERP permite registrar eventos importantes de forma estructurada, segura y extensible. A través del helper `log_system()` se abstrae la lógica de registro para facilitar su uso sin exponer la clase subyacente `KonekoSystemLogger`.
|
|
|
|
## ✅ ¿Cuándo usar `log_system()`?
|
|
|
|
Este helper debe utilizarse para registrar:
|
|
|
|
- Operaciones del sistema (módulos, configuración, instalación de paquetes)
|
|
- Procesos técnicos (errores, warnings, notificaciones internas)
|
|
- Eventos relevantes relacionados con lógica de negocio o flujos administrativos
|
|
|
|
---
|
|
|
|
## 📦 Helper: `log_system()`
|
|
|
|
```php
|
|
log_system(
|
|
string|LogLevel $level,
|
|
string $message,
|
|
array $context = [],
|
|
?Model $related = null
|
|
): SystemLog
|
|
```
|
|
|
|
### Parámetros
|
|
| Nombre | Tipo | Descripción |
|
|
|--------------|----------------------------------|-------------|
|
|
| `$level` | `string\|LogLevel` | Nivel del log (`info`, `warning`, `error`, `critical`, etc.) |
|
|
| `$message` | `string` | Mensaje a registrar |
|
|
| `$context` | `array` | Datos adicionales relevantes al evento |
|
|
| `$related` | `Model|null` | Modelo relacionado (opcional, se guarda en `related_model`) |
|
|
|
|
---
|
|
|
|
## 🎯 Ejemplos de uso
|
|
|
|
### Log simple con nivel:
|
|
```php
|
|
log_system('info', 'Inicio del proceso de sincronización');
|
|
```
|
|
|
|
### Log con contexto personalizado:
|
|
```php
|
|
log_system('error', 'Error al procesar factura CFDI', [
|
|
'cfdi_id' => 3345,
|
|
'error' => $exception->getMessage(),
|
|
]);
|
|
```
|
|
|
|
### Log vinculado a un modelo:
|
|
```php
|
|
log_system(
|
|
'warning',
|
|
'El producto fue modificado manualmente',
|
|
['user' => auth()->id()],
|
|
$product
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
## 🧱 Internamente...
|
|
|
|
- Se utiliza el modelo `Koneko\VuexyAdmin\Models\SystemLog`
|
|
- Soporta `morphTo()` para asociar cualquier modelo relacionado (via `related_model`)
|
|
- Se castea `level` como Enum `LogLevel`
|
|
- Se incluye automáticamente el componente si está registrado vía `KonekoComponentContextRegistrar`
|
|
|
|
---
|
|
|
|
## 🛡️ Buenas prácticas
|
|
|
|
- Usa niveles correctos (`info`, `debug`, `warning`, `error`, `critical`) según la gravedad
|
|
- Agrega siempre contexto útil que facilite auditoría
|
|
- Usa `related` cuando el evento está directamente vinculado a un modelo (como un `Pedido`, `Producto`, etc.)
|
|
- Si estás en un módulo registrado, el helper asocia automáticamente el `componentNamespace`
|
|
|
|
---
|
|
|
|
## 🔐 Soporte a auditoría
|
|
|
|
`log_system()` es parte fundamental del sistema de trazabilidad técnica del ERP. Todos los registros quedan disponibles para consulta por el módulo de Auditoría o Seguridad Avanzada si está habilitado.
|
|
|
|
---
|
|
|
|
## 📍 Registro automático de módulo
|
|
|
|
Si el componente actual fue registrado mediante:
|
|
```php
|
|
KonekoComponentContextRegistrar::registerComponent('admin');
|
|
```
|
|
El log quedará asociado a `module = 'admin'`, sin necesidad de especificarlo manualmente.
|
|
|
|
---
|
|
|
|
## 📚 Relación con otros loggers
|
|
| Helper | Propósito |
|
|
|---------------------|-----------------------------------|
|
|
| `log_system()` | Logs técnicos y operativos |
|
|
| `log_security()` | Eventos de seguridad (auth, IP) |
|
|
| `log_interaction()` | Interacciones del usuario final |
|
|
|
|
---
|
|
|
|
## 🧪 Testing y ambiente local
|
|
|
|
En `local` o `staging`, es común agregar logs temporales para diagnóstico:
|
|
```php
|
|
log_system('debug', 'Revisando flujo de pago', ['step' => 3]);
|
|
```
|
|
|
|
Recuerda que estos deben eliminarse o ajustarse a `info` en producción.
|
|
|
|
---
|
|
|
|
## 🧭 Ubicación del modelo
|
|
```php
|
|
Koneko\VuexyAdmin\Models\SystemLog
|
|
```
|
|
|
|
Puedes extender la funcionalidad desde el modelo si se requiere una visualización especial para auditoría o tablas administrativas.
|
|
|
|
---
|
|
|
|
> Este helper está diseñado para desarrolladores del ecosistema Koneko. Evita el uso directo de `KonekoSystemLogger` salvo en integraciones muy especializadas.
|