koneko/laravel-vuexy-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
laravel-vuexy-admin/docs/guia-de-convenciones-para-database-data-en-koneko-vuexy-admin-erp.md
Arturo Corro a7002701f5 Testing Alpha
2025-05-11 14:14:50 -06:00

4.7 KiB
Raw Blame History

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

'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!