Testing Alpha

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.