Testing Alpha

2025-05-11 14:14:50 -06:00
parent 988b86a33d
commit a7002701f5
1903 changed files with 77534 additions and 36485 deletions
--- a/docs/Helpers/cache-helper-guide.md
+++ b/docs/Helpers/cache-helper-guide.md
@ -0,0 +1,117 @@
+# Koneko ERP - Cache Helper Guide
+
+> ✨ Esta guía detalla el uso correcto del sistema de cache en Koneko ERP, basado completamente en el helper `cache_manager()`, sin necesidad de interactuar con las clases internas como `KonekoCacheManager` o `LaravelCacheManager`.
+
+---
+
+## 🔎 Filosofía
+
+* Toda interacción de componentes con el sistema de cache debe realizarse exclusivamente mediante el helper `cache_manager()`.
+* Las clases internas son consideradas **@internal**, y no deben ser accedidas directamente por desarrolladores de componentes.
+* El sistema permite configuración jerárquica basada en namespace del componente, grupo lógico de datos y claves individuales.
+
+---
+
+## 🔍 Sintaxis del Helper
+
+```php
+cache_manager(string $component = 'admin', string $group = 'cache')
+```
+
+Retorna una instancia segura del gestor para el componente y grupo indicados. Ejemplos:
+
+```php
+cache_manager('admin', 'avatar')->enabled();
+cache_manager('website', 'menu')->ttl();
+cache_manager('website', 'html')->flush();
+```
+
+---
+
+## ⚖️ Jerarquía de Configuración
+
+Las operaciones de cache respetan la siguiente jerarquía al determinar configuraciones:
+
+1. `koneko.{componente}.{grupo}.ttl` / `enabled`
+2. `koneko.{componente}.cache.ttl` / `enabled`
+3. `koneko.cache.ttl` / `enabled`
+
+Esto permite granularidad sin perder coherencia global.
+
+---
+
+## 📃 Métodos Disponibles
+
+| Método                   | Descripción                                                   |
+| ------------------------ | ------------------------------------------------------------- |
+| `key(string $suffix)`    | Genera clave de cache completa con prefijos                   |
+| `config($key, $default)` | Accede a configuraciones con prefijo aplicado                 |
+| `ttl()`                  | TTL efectivo (en segundos)                                    |
+| `enabled()`              | Determina si el cache está habilitado para el contexto actual |
+| `flush()`                | Limpia el grupo de cache completo si el driver lo permite     |
+| `driver()`               | Devuelve el driver de cache actual                            |
+| `shouldDebug()`          | Evalúa si se encuentra en modo debug para cache               |
+| `registerDefaults()`     | Registra valores default para ttl y enabled si no existen     |
+
+---
+
+## 🚀 Ejemplos de Uso
+
+### Validar TTL efectivo
+
+```php
+$ttl = cache_manager('website', 'menu')->ttl();
+```
+
+### Verificar si está habilitado
+
+```php
+if (cache_manager('admin', 'avatar')->enabled()) {
+    // Proceder con cache
+}
+```
+
+### Limpiar cache con soporte para etiquetas
+
+```php
+cache_manager('website', 'html')->flush();
+```
+
+---
+
+## ⚠️ Buenas Prácticas
+
+* **No** uses directamente la clase `KonekoCacheManager`.
+* **No** accedas directamente al sistema `Cache::` sin pasar por el helper.
+* **No** asumas estructura de clave, usa `->key()`.
+* **Sí** configura `koneko.{componente}.{grupo}.ttl` en tu archivo `config()` si tu componente lo necesita.
+
+---
+
+## 🔍 Debug y Diagnóstico
+
+Ejecuta:
+
+```bash
+php artisan koneko:cache --component=website --group=html --ttl
+php artisan koneko:cache --component=admin --group=avatar --flush
+```
+
+El comando mostrará información relevante para depuración sin exponer clases internas.
+
+---
+
+## 🚧 Futura Expansión
+
+* Registro de tags
+* TTLs dinámicos
+* Integración con eventos y auditoría
+* Modo "read-only" para ambientes cacheados
+
+---
+
+## 🌟 Conclusión
+
+Este sistema garantiza modularidad, extensibilidad y seguridad. El helper `cache_manager()` es la única puerta de entrada para desarrolladores y debe usarse exclusivamente para mantener la integridad del ecosistema.
+
+> ✅ Si necesitas agregar un nuevo grupo de cache, simplemente define su configuración y comienza a usar el helper, sin necesidad de modificar clases o contratos.
--- a/docs/Helpers/component-access-and-exposure-policy.md
+++ b/docs/Helpers/component-access-and-exposure-policy.md
@ -0,0 +1,68 @@
+# Koneko ERP - Component Access & Exposure Policy
+
+Este documento define las reglas de exposición y acceso para los servicios técnicos clave dentro del ecosistema **Koneko ERP**. Establece los principios para mantener una arquitectura limpia, segura y coherente, facilitando su extensión y documentación.
+
+---
+
+## ✅ Componentes y su Exposición
+
+| Clase Técnica                     | Expuesta al Usuario | Acceso Recomendado         | Notas                                                            |
+| --------------------------------- | ------------------- | -------------------------- | ---------------------------------------------------------------- |
+| `KonekoSettingManager`           | ❌ No                | `settings()` helper        | Configuración modular con soporte de namespaces.                 |
+| `KonekoCacheManager`              | ❌ No                | `cache_manager()` helper   | Acceso al sistema de cache multi-driver y con TTL configurables. |
+| `KonekoSystemLogger`              | ❌ No                | `log_system()` helper      | Logger morfable con niveles y contexto extendido.                |
+| `KonekoSecurityLogger`            | ❌ No                | `log_security()` helper    | Eventos de seguridad con GeoIP y proxy detection.                |
+| `KonekoUserInteractionLogger`     | ❌ No                | `log_interaction()` helper | Auditoría de componentes y acciones sensibles.                   |
+| `KonekoComponentContextRegistrar` | ❌ No                | ❄ Solo Bootstrap           | Registra el `namespace` del componente y su `slug` actual.       |
+
+---
+
+## ⚖️ Principios de Acceso
+
+* **Acceso exclusivo por helpers**: Los helpers representan la única interfaz pública soportada para operaciones de configuración, cache y logs.
+* **Encapsulamiento interno**: Ningún componente debería invocar directamente servicios como `KonekoSettingManager` o `KonekoSystemLogger`.
+* **UI y CLI desacoplados**: Tanto los comandos artisan como el panel administrativo utilizan los helpers, nunca instancias directas.
+
+---
+
+## 💡 Buenas prácticas para desarrolladores
+
+* Usa `settings()` para acceder o escribir configuraciones modulares.
+* Usa `cache_manager()` para obtener TTL, flush o debug por componente.
+* Usa `log_system()` para registrar eventos de sistema de forma morfable.
+* Usa `log_security()` para eventos como logins fallidos o IP sospechosas.
+* Usa `log_interaction()` para acciones en Livewire, eventos UI o tracking avanzado.
+
+---
+
+## 🔹 Ejemplo práctico
+
+```php
+// Correcto
+settings()->in('website')->get('general.site_name');
+cache_manager('admin', 'menu')->ttl();
+log_system('info', 'Menú regenerado');
+```
+
+```php
+// Incorrecto ❌
+app(KonekoSettingManager::class)->get(...);
+new KonekoCacheManager(...);
+(new KonekoSystemLogger)->log(...);
+```
+
+---
+
+## 📃 Futuras extensiones
+
+* Se agregará soporte en este esquema para:
+
+  * APIManager: `api_manager()`
+  * Catalogs: `catalog()`
+  * Event Dispatchers: `event_dispatcher()`
+
+Cada uno seguirá el mismo patrón: clase técnica interna, helper de acceso documentado, y uso controlado por contexto registrado.
+
+---
+
+> Este documento forma parte del conjunto `docs/architecture/components/`. Asegúrese de mantenerlo actualizado ante cualquier refactor o nuevo helper público.
--- a/docs/Helpers/security-logger-helper-guide.md
+++ b/docs/Helpers/security-logger-helper-guide.md
@ -0,0 +1,120 @@
+# Koneko Security Logger Helper Guide
+
+> ⚖️ Auditoría de eventos de seguridad en tiempo real y bajo demanda.
+
+El logger `log_security()` forma parte de la infraestructura central de seguridad de Koneko Vuexy Admin y te permite registrar eventos sensibles como accesos, fallos de login, intentos sospechosos, detecciones de VPN, entre otros.
+
+---
+
+## ✨ Ventajas
+
+* No requiere instanciar clases.
+* Autoobtiene `Request`, `IP`, `UserAgent`, `Geolocalización`, etc.
+* Flexible para ejecutarse desde controladores, middleware, jobs o Livewire.
+* Compatible con `SecurityEvent` (modelo auditado).
+* Almacena contexto extendido con `payload`, `is_proxy`, `user_id`, etc.
+
+---
+
+## ✨ Uso básico
+
+```php
+log_security('login_failed');
+```
+
+Esto registra un fallo de login con todos los metadatos de seguridad: IP, ciudad, dispositivo, agente, URL y más.
+
+---
+
+## ⚖️ Sintaxis Completa
+
+```php
+log_security(
+    string $type,                    // Tipo de evento (ej: login_failed, login_success)
+    ?Request $request = null,        // Puede inyectarse manualmente
+    ?int $userId = null,             // Usuario relacionado (opcional)
+    array $payload = [],             // Datos adicionales como intentos, cabeceras, etc.
+    bool $isProxy = false            // ¿Fue detectado uso de proxy/VPN?
+);
+```
+
+Ejemplo completo:
+
+```php
+log_security(
+    'login_failed',
+    request(),
+    $user?->id,
+    ['intentos' => 3, 'via' => 'formulario'],
+    detectaVpnProxy(request()->ip())
+);
+```
+
+---
+
+## 🔍 Eventos soportados por defecto
+
+Puedes definirlos como constantes estáticas en tu código:
+
+```php
+SecurityEvent::EVENT_LOGIN_FAILED
+SecurityEvent::EVENT_LOGIN_SUCCESS
+```
+
+O usar strings arbitrarios con sentido:
+
+```php
+'password_reset_attempt'
+'blocked_login_from_blacklist'
+'csrf_token_fail'
+'geolocation_warning'
+```
+
+---
+
+## ⌚ Modelo generado: `SecurityEvent`
+
+El evento registrado se almacena en la tabla `security_events`, con campos como:
+
+* `ip_address`
+* `user_id`
+* `event_type`
+* `payload`
+* `region`, `city`, `country`
+* `is_proxy`, `device_type`, etc.
+
+---
+
+## 🌐 Geolocalización Automática
+
+Si tienes habilitado el trait `HasGeolocation`, el sistema hace *GeoIP Lookup* por IP:
+
+```php
+use Koneko\VuexyAdmin\Support\Traits\Helpers\HasGeolocation;
+```
+
+---
+
+## 🔐 Buenas prácticas
+
+* Usa tipos semánticos: `login_success`, `vpn_blocked`, `csrf_fail`, etc.
+* Agrega contexto extra en `payload` para debugging posterior.
+* Detecta IPs sospechosas con `isProxy` (ideal para usar junto con sistemas de listas negras).
+
+---
+
+## ✨ Extras
+
+Puedes extender la lógica de logging desde:
+
+```php
+Koneko\VuexyAdmin\Support\Logger\KonekoSecurityLogger
+```
+
+Este servicio puede adaptarse o sustituirse por otro para logs distribuidos o externos (ej: Sentry, Elastic, etc).
+
+---
+
+## ✅ Conclusión
+
+El helper `log_security()` es una herramienta robusta, flexible y elegante para capturar eventos sensibles en tu ERP. Evita trabajar directamente con el modelo, mantén la consistencia de tu registro, y delega la trazabilidad a una capa preparada para el contexto empresarial.
--- a/docs/Helpers/settings-helper-guide.md
+++ b/docs/Helpers/settings-helper-guide.md
@ -0,0 +1,161 @@
+# Koneko Settings Helper Guide
+
+Guía oficial de uso para `settings()` dentro del ecosistema Koneko ERP.
+
+---
+
+## 📁 Filosofía General
+
+KonekoSettingManager es una clase interna (@internal) encargada de gestionar configuraciones de componentes y módulos del ecosistema de forma centralizada, modular y cacheable. No debe ser usada directamente.
+
+### Acceso siempre mediante el helper global:
+
+```php
+settings()->get('clave');
+settings()->set('clave', 'valor');
+```
+
+---
+
+## ⚖️ Jerarquía de Namespace (Prioridad de Resolución)
+
+```text
+componentNamespace (ej: admin, website)
+    └️ module_slug (ej: avatar, seo, menu)
+        └️ key
+```
+
+Ejemplo real:
+
+```text
+koneko.admin.avatar.cache.ttl
+```
+
+---
+
+## ✨ Métodos Disponibles
+
+### `self(?string $subNamespace = null)`
+
+Se vincula automáticamente al componente activo según el contexto del módulo actual.
+
+```php
+settings()->self()->get('cache.ttl');
+```
+
+### `in(string $namespace)`
+
+Permite establecer un namespace manual.
+
+```php
+settings()->in('admin.avatar')->get('enabled');
+```
+
+### `get(string $key, ...$args)`
+
+Obtiene el valor de un setting.
+
+```php
+$ttl = settings()->get('cache.ttl');
+```
+
+### `set(string $key, mixed $value, ?int $userId = null)`
+
+Guarda o actualiza un setting.
+
+```php
+settings()->set('menu.visible', true);
+```
+
+### `currentNamespace()`
+
+Devuelve el namespace actual del contexto.
+
+### `listGroups()`
+
+Devuelve una colección de todos los grupos de configuración disponibles en el componente.
+
+---
+
+## 🚀 Comportamiento Avanzado
+
+### ❄️ Cache Automática
+
+* Al consultar un setting se usa el `KonekoCacheManager` de fondo si está habilitado.
+* Puedes controlar el TTL y activación por:
+
+```php
+koneko.cache.enabled
+koneko.admin.cache.ttl
+koneko.admin.avatar.cache.enabled
+```
+
+### ⚖️ Tipos automáticos
+
+* Si el valor del setting es JSON, se decodifica automáticamente.
+
+### 🔨 Almacenamiento estructurado
+
+Los datos se almacenan en la base de datos en la tabla `settings`:
+
+* `namespace`
+* `key`
+* `value`
+* `user_id`
+
+---
+
+## 🔧 Casos de Uso Comunes
+
+```php
+// 1. TTL de avatar (modo simple)
+$ttl = settings()->in('admin.avatar')->get('cache.ttl');
+
+// 2. Cambiar visibilidad del menú del website
+settings()->in('website.menu')->set('visible', true);
+
+// 3. Desde un componente que ya registró su namespace:
+settings()->get('enabled');
+
+// 4. En test con namespace explícito:
+settings()->in('admin.seo')->set('json_ld.enabled', true);
+```
+
+---
+
+## ⚡ Recomendaciones
+
+* Nunca accedas directamente a `KonekoSettingManager`
+* Usa `settings()` siempre que necesites configuración
+* El namespace se debe registrar automáticamente con `KonekoComponentContextRegistrar`
+* Puedes definir valores por `.env` o `config()` que serán sobreescritos si existen en la base de datos
+
+---
+
+## 🚩 Diagnóstico Rápido
+
+```php
+settings()->in('website.menu')->get('debug');
+settings()->in('admin.avatar')->currentNamespace();
+```
+
+---
+
+## ✨ Integración UI
+
+Todos los valores son consultables y modificables desde:
+
+* Panel de administrador
+* Vistas Livewire
+* Componentes Vue o Blade mediante API
+
+---
+
+## 🙏 Agradecimientos
+
+Sistema inspirado por la necesidad de centralizar configuraciones por módulo en entornos escalables y cacheables. Diseñado con amor para el ERP Koneko Vuexy Admin México.
+
+---
+
+\#❤️ ¿Aportaciones?
+Si tienes sugerencias, no dudes en compartirlas en el repositorio oficial Koneko.
--- a/docs/Helpers/system-logger-helper-guide.md
+++ b/docs/Helpers/system-logger-helper-guide.md
@ -0,0 +1,126 @@
+# 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.
--- a/docs/Helpers/user-interaction-logger-helper.md
+++ b/docs/Helpers/user-interaction-logger-helper.md
@ -0,0 +1,110 @@
+# 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.