koneko/laravel-vuexy-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Testing Alpha

Browse Source
This commit is contained in:
Arturo Corro
2025-05-11 14:14:50 -06:00
parent 988b86a33d
commit a7002701f5
1903 changed files with 77534 additions and 36485 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/<!DOCTYPE html>.html Normal file
View File

@ -0,0 +1,68 @@
<!DOCTYPE html>
<html lang="{{ dynamic_lang }}" prefix="og: http://ogp.me/ns#">
<head>
<!-- Metadatos Esenciales -->
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=5.0">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<!-- Title Tag Optimizado -->
<title>{{ page_title }} | {{ site_name }}</title>
<!-- Meta Description Dinámica -->
<meta name="description" content="{{ meta_description|truncate:160 }}">
<!-- Open Graph / Facebook -->
<meta property="og:type" content="{{ og_type }}">
<meta property="og:url" content="{{ canonical_url }}">
<meta property="og:title" content="{{ og_title|truncate:60 }}">
<meta property="og:description" content="{{ og_description|truncate:160 }}">
<meta property="og:image" content="{{ og_image_url }}">
<meta property="og:site_name" content="{{ site_name }}">
<!-- Twitter Card -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:creator" content="{{ twitter_handle }}">
<!-- ... otros meta twitter ... -->
<!-- Robots Directives -->
<meta name="robots" content="{{ index_status }}, {{ follow_status }}, max-image-preview:large">
<!-- Idioma y Geolocalización -->
<meta name="language" content="{{ main_language }}">
<meta name="geo.region" content="{{ geo_region }}">
<meta name="geo.placename" content="{{ geo_placename }}">
<!-- Enlaces Canónicos y Alternativos -->
<link rel="canonical" href="{{ canonical_url }}">
{% for alternate in alternate_langs %}
<link rel="alternate" hreflang="{{ alternate.code }}" href="{{ alternate.url }}">
{% endfor %}
<!-- Preconexiones y Preloads -->
<link rel="preconnect" href="https://www.googletagmanager.com">
<link rel="dns-prefetch" href="//fonts.googleapis.com">
<!-- Favicon Moderno (SVG + PNG fallback) -->
<link rel="icon" href="/assets/favicon.svg" type="image/svg+xml">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<!-- CSS Crítico Inline -->
<style>/* CSS mínimo para above-the-fold */</style>
<!-- Schema.org JSON-LD -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "WebSite",
"name": "{{ site_name }}",
"url": "{{ base_url }}",
"potentialAction": {
"@type": "SearchAction",
"target": "{{ search_url }}?q={search_term_string}",
"query-input": "required name=search_term_string"
}
}
</script>
</head>
<body itemscope itemtype="http://schema.org/WebPage">

117
docs/Helpers/cache-helper-guide.md Normal file
View File

@ -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.

68
docs/Helpers/component-access-and-exposure-policy.md Normal file
View File

@ -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.

120
docs/Helpers/security-logger-helper-guide.md Normal file
View File

@ -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.

161
docs/Helpers/settings-helper-guide.md Normal file
View File

@ -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.

126
docs/Helpers/system-logger-helper-guide.md Normal file
View File

@ -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.

110
docs/Helpers/user-interaction-logger-helper.md Normal file
View File

@ -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.

30
docs/factory/index.md Normal file
View File

@ -0,0 +1,30 @@
# 🏭 Koneko ERP - Factory Design Guide
Este documento describe cómo crear y extender `Factories` para modelos en el ecosistema de Koneko ERP.
## 🎯 Objetivo
Facilitar la generación de datos de prueba y semilla utilizando una estructura clara, coherente y extensible para todos los modelos del sistema.
## 🧱 Clase Base: `AbstractModelFactory`
```php
namespace Koneko\VuexyAdmin\Support\Factories;
abstract class AbstractModelFactory extends Factory
{
// Inyecta Faker automáticamente
// Ofrece métodos auxiliares como maybe()
}
```
## 🧬 Traits útiles
- `HasFactorySupport`: `maybe($probabilidad, $valor)`
- `HasContactFakeData`: CURP, RFC, teléfono
- `HasFactoryEnumSupport`: Soporte aleatorio de Enums
- `HasDynamicFactoryExtenders`: para métodos como `definitionXyz()`
## 🚘 Ejemplo: Factory para `Vehicle`
Ver archivo: `VehicleFactory.php`

181
docs/guia-de-convenciones-para-database-data-en-koneko-vuexy-admin-erp.md Normal file
View File

@ -0,0 +1,181 @@
# Guía de Convenciones para `database/data/` en Koneko Vuexy Admin/ERP
> Esta guía está diseñada para ayudar a desarrolladores a organizar, entender y aprovechar correctamente la estructura de carpetas `database/data/*` en los módulos del ecosistema **Koneko Vuexy Admin/ERP**. Aplica tanto para datos de prueba como para catálogos oficiales, importaciones, plantillas y volcados.
---
## 📂 Estructura base sugerida
Cada componente o módulo deberá tener su propia carpeta bajo `database/data/`, utilizando el nombre del paquete o alias del módulo. Por ejemplo:
```bash
database/data/vuexy-contacts/
database/data/vuexy-sat-catalogs/
database/data/vuexy-ecommerce/
database/data/vuexy-core/
```
---
## 📄 Tipos de carpetas internas
A continuación se detallan los tipos de subcarpetas recomendadas dentro de cada componente:
### 1. `seeders/`
Contiene archivos de datos utilizados para poblar la base de datos con registros reales o iniciales.
* Formatos: `.json`, `.csv`, `.php`
* Uso: Comandos como `php artisan db:seed` o `SeederOrchestrator`
**Ejemplos:**
```bash
database/data/vuexy-contacts/seeders/users.json
database/data/vuexy-ecommerce/seeders/products.csv
```
---
### 2. `fixtures/`
Datos temporales o de prueba. Generalmente usados para QA, testeo, demostraciones o sandbox.
**Ejemplos:**
```bash
database/data/vuexy-ecommerce/fixtures/demo-products.csv
database/data/vuexy-core/fixtures/test-users.json
```
---
### 3. `catalogs/`
Incluye catálogos oficiales o externos (como los del SAT, INEGI, ISO, etc.) ya convertidos a `.csv` o `.json`, listos para importar.
**Ejemplos:**
```bash
database/data/vuexy-sat-catalogs/catalogs/c_RegimenFiscal.csv
database/data/vuexy-sat-catalogs/catalogs/c_UsoCFDI.csv
```
---
### 4. `samples/` o `templates/`
Plantillas de importación para administradores o usuarios finales. Ayudan a estructurar correctamente los datos antes de importar.
**Ejemplos:**
```bash
database/data/vuexy-website-admin/samples/template_users.csv
database/data/vuexy-ecommerce/samples/sample_product.json
```
---
### 5. `dumps/`
Volcados de base de datos completos o parciales, usados como backups, sincronización o testing. No deben usarse en producción directamente.
**Ejemplos:**
```bash
database/data/vuexy-core/dumps/db-export.json
database/data/vuexy-ecommerce/dumps/partial-products.sql
```
---
### 6. `sources/`
Archivos fuente originales que requieren procesamiento, como `.xlsx` del SAT o archivos crudos.
**Ejemplos:**
```bash
database/data/vuexy-sat-catalogs/sources/SAT_Catalogos_2024.xlsx
database/data/vuexy-geo/sources/inegi_cp_2020.xlsx
```
---
### 7. `mappings/`
Mapas de conversión, reglas de transformación, diccionarios de campos, etc. Muy útiles cuando se procesan archivos externos.
**Ejemplos:**
```bash
database/data/vuexy-sat-catalogs/mappings/column_map.json
database/data/vuexy-ecommerce/mappings/type_rules.json
```
---
### 8. `commands/` (opcional)
Scripts de ejemplo para parseo, importación o generación de datos. No se ejecutan automáticamente, son de referencia.
**Ejemplo:**
```bash
database/data/vuexy-sat-catalogs/commands/parse_sat_catalog.php
```
---
## 📊 Publicación de archivos desde Providers
Los `ServiceProvider` de cada módulo pueden publicar estos archivos para que el desarrollador los copie al proyecto:
```php
'publishedFiles' => [
'seeders' => [
'database/data/vuexy-contacts/seeders' => base_path('database/data/vuexy-contacts/seeders'),
],
'catalogs' => [
'database/data/vuexy-sat-catalogs/catalogs' => base_path('database/data/vuexy-sat-catalogs/catalogs'),
],
],
```
---
## ✨ Buenas prácticas
* Usa nombres descriptivos: `products_v2.json`, `c_UsoCFDI_2024.csv`
* No sobreescribas datos productivos desde estas carpetas.
* Prefiere `json` para estructuras complejas, `csv` para tabulares simples.
* Siempre separa datos de prueba (`fixtures`) de datos de producción (`seeders`).
* Versiona si es necesario: `v1/`, `v2/`.
---
## ❓ FAQ
**¿Puedo usar archivos de `samples/` como plantilla para importadores Livewire?**
> Sí, están pensados como guías para el usuario final.
**¿Debo publicar todos los archivos por defecto?**
> No. Publica solo los que consideres necesarios para instalación o personalización.
**¿Puedo incluir múltiples carpetas del mismo tipo?**
> Sí. Puedes tener `catalogs/v3/` y `catalogs/v4/` si soportas distintas versiones.
---
## 🚀 Extensiones futuras
* Agregar validación automática de estructuras CSV.
* Sistema de visualización para cada tipo de archivo desde el admin.
* Comandos de limpieza automática (`vuexy:data:cleanup`)
---
¡Esta convención mejora la modularidad, facilita el mantenimiento y hace tu ERP más robusto y predecible!

54
docs/notify-guide-koneko.md Normal file
View File

@ -0,0 +1,54 @@
# Notificaciones en Koneko ERP
Este documento describe cómo utilizar el sistema de notificaciones centralizado mediante `NotifyChannelService` en el ecosistema Koneko ERP.
## 🧩 Drivers disponibles
- **Toastr** (predeterminado, clásico)
- **Notyf** (UX moderna, ligera)
- **Toastify** (notificaciones mínimas flotantes)
- **SweetAlert2** (modales avanzados, carga bajo demanda)
- **PNotify** (notificaciones avanzadas y persistentes, carga bajo demanda)
- **Custom** (ejecuta `window.VuexyNotify(payload)` si está definido)
## 📦 Uso básico
Puedes disparar una notificación global desde cualquier JS:
```js
import { NotifyChannelService } from '@/vuexy/notifications/notify-channel-service';
NotifyChannelService.notify({
type: 'success',
message: 'Usuario guardado correctamente',
title: 'Éxito',
channel: 'toastr' // 'notyf', 'toastify', 'sweetalert', 'pnotify', 'custom'
});
```
## 🌐 Desde Livewire
Puedes emitir un evento desde tu componente PHP:
```php
$this->dispatchBrowserEvent('notify', [
'type' => 'success',
'message' => 'Operación exitosa',
'channel' => 'toastify'
]);
```
Y en tu JS global:
```js
document.addEventListener('notify', (event) => {
window.NotifyChannelService.notify(event.detail);
});
```
## 📄 Recomendaciones
- **Toastr**, **Toastify** y **Notyf** pueden convivir cargados.
- **SweetAlert2** y **PNotify** se cargan dinámicamente.
- Configura el canal por defecto desde `settings('core.notify.driver')` si lo deseas.

32
docs/seeder/config.md Normal file
View File

@ -0,0 +1,32 @@
# ⚙️ Configuración del sistema de seeders
El archivo `config/seeder.php` permite controlar el comportamiento global de todos los módulos.
## 🔑 Opciones principales
| Opción | Tipo | Descripción |
|----------------|---------|-------------|
| `env` | string | Entorno actual (local, demo, etc.) |
| `modules` | array | Lista de módulos con su configuración individual |
| `defaults` | array | Valores por defecto para todos los seeders |
| `clear_assets` | array | Define qué carpetas se borran antes de iniciar |
## 🧩 Configuración por módulo
Cada módulo acepta:
```php
'users' => [
'enabled' => true,
'seeder' => UserSeeder::class,
'file' => 'users.json',
'depends_on' => ['permissions'],
'truncate' => true,
'faker_only' => false,
'fake' => [
'min' => 5,
'max' => 100,
'images' => [...]
],
],
```

33
docs/seeder/create-new-seeder.md Normal file
View File

@ -0,0 +1,33 @@
# 🧱 Cómo crear un nuevo Seeder compatible
## 1. Crear el Seeder
```php
class ProductoSeeder extends AbstractDataSeeder
{
use HasSeederFactorySupport;
use HandlesFileSeeders;
public function run(array $config = []): void
{
$this->seedFromJson('productos.json');
}
public function runFake(int $total, array $config = []): void
{
Producto::factory()->count($total)->create();
}
}
```
## 2. Registrar en `config/seeder.php`
```php
'products' => [
'enabled' => true,
'seeder' => ProductoSeeder::class,
'file' => 'products.json',
'faker_only' => false,
'fake' => ['min' => 5, 'max' => 100],
],
```

10
docs/seeder/index.md Normal file
View File

@ -0,0 +1,10 @@
# 🌱 Koneko ERP - Sistema de Seeders Modular
Este sistema permite poblar la base de datos del ERP de forma controlada, desde archivos CSV/JSON o mediante generación con Faker, incluyendo soporte para:
- Seeders con dependencias (`depends_on`)
- Modo `dry-run` (simulación sin afectar BD)
- Reportes en formato Markdown y JSON
- Limpieza automática de assets (ej. avatares)
- Soporte para múltiples entornos (`SEEDER_ENV`)
- Generación de imágenes y datos falsos

30
docs/seeder/usage.md Normal file
View File

@ -0,0 +1,30 @@
# 🚀 Cómo ejecutar los seeders
## 🧪 Modo normal
```bash
php artisan migrate:fresh --seed
```
## 🎯 Ejecutar módulo específico
```bash
php artisan db:seed --class=DatabaseSeeder --only=users
```
## 🧹 Activar limpieza de assets
Controlado por `config/seeder.php > clear_assets`.
## 🧼 Dry run
```php
$orchestrator->run(only: 'users', options: ['dry-run' => true]);
```
## 📁 Reportes
Se generan automáticamente:
- `database/seeders/reports/local/seed-report-*.md`
- `database/seeders/reports/local/seed-report-*.json`

0
docs/structure.md Normal file
View File