diff --git a/admin/PLAN-PREPARACION-TEMA-BD.md b/admin/PLAN-PREPARACION-TEMA-BD.md new file mode 100644 index 00000000..55d216e9 --- /dev/null +++ b/admin/PLAN-PREPARACION-TEMA-BD.md @@ -0,0 +1,412 @@ +# PLAN: PreparaciΓ³n del Tema para Arquitectura con Base de Datos + +**Fecha:** 2025-01-14 +**Objetivo:** Preparar el tema Apus para trabajar con la nueva arquitectura de defaults en base de datos + +--- + +## 🎯 CONTEXTO + +### Arquitectura actual (PROBLEMÁTICA): +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Settings Manager β”‚ +β”‚ β”œβ”€ get_defaults() β†’ VACÍO ❌ β”‚ +β”‚ β”œβ”€ get_settings() β†’ wp_options βœ… β”‚ +β”‚ └─ save_settings() β†’ wp_options βœ… β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ DB Manager β”‚ +β”‚ β”œβ”€ Tabla: wp_apus_theme_components β”‚ +β”‚ β”œβ”€ get_config() βœ… β”‚ +β”‚ └─ save_config() βœ… β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Tabla: wp_apus_theme_components_defaultsβ”‚ +β”‚ β”œβ”€ Creada βœ… β”‚ +β”‚ β”œβ”€ Sin clase para leer ❌ β”‚ +β”‚ └─ VacΓ­a (sin datos) ❌ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Arquitectura deseada (OBJETIVO): +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ DEFAULTS MANAGER (NUEVO) β”‚ +β”‚ β”œβ”€ Tabla: wp_apus_theme_components_defaults β”‚ +β”‚ β”œβ”€ get_defaults($component_name) β†’ leer tabla βœ… β”‚ +β”‚ └─ OperaciΓ³n: SOLO LECTURA (escritura desde algoritmo) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SETTINGS MANAGER (MODIFICADO) β”‚ +β”‚ β”œβ”€ get_defaults() β†’ usa Defaults Manager βœ… β”‚ +β”‚ β”œβ”€ get_settings() β†’ merge defaults + personalizaciones β”‚ +β”‚ └─ save_settings() β†’ guarda SOLO personalizaciones β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PERSONALIZACIΓ“N: ΒΏDΓ³nde guardar? β”‚ +β”‚ OpciΓ³n A: wp_options (actual) βœ… SIMPLE β”‚ +β”‚ OpciΓ³n B: wp_apus_theme_components ❓ COMPLEJO β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## πŸ“‹ FASE 1: ANÁLISIS DE ARQUITECTURA ACTUAL + +### PASO 1.1: Verificar quΓ© contiene cada tabla +**DuraciΓ³n:** 5 min + +**Ejecutar queries:** +```sql +-- Verificar tabla de defaults (debe estar vacΓ­a) +SELECT COUNT(*) FROM wp_apus_theme_components_defaults; +SELECT * FROM wp_apus_theme_components_defaults LIMIT 5; + +-- Verificar tabla de componentes +SELECT COUNT(*) FROM wp_apus_theme_components; +SELECT component_name, COUNT(*) as configs +FROM wp_apus_theme_components +GROUP BY component_name; + +-- Verificar wp_options +SELECT option_value FROM wp_options WHERE option_name = 'apus_theme_settings'; +``` + +**Documentar:** +- ΒΏHay datos en `wp_apus_theme_components`? +- ΒΏHay datos en `wp_options` (apus_theme_settings)? +- ΒΏCuΓ‘l se estΓ‘ usando actualmente? + +--- + +### PASO 1.2: Analizar flujo actual de datos +**DuraciΓ³n:** 10 min + +**Revisar archivos:** +- [ ] `class-settings-manager.php` - ΒΏDe dΓ³nde lee? ΒΏDΓ³nde guarda? +- [ ] `class-db-manager.php` - ΒΏQuΓ© tabla maneja? +- [ ] Admin Panel JS - ΒΏQuΓ© endpoints AJAX llama? +- [ ] Frontend (header.php, etc.) - ΒΏDe dΓ³nde obtiene datos para renderizar? + +**Documentar:** +``` +Flujo actual: +1. Usuario abre Admin Panel β†’ AJAX: apus_get_settings β†’ ??? +2. Usuario guarda cambios β†’ AJAX: apus_save_settings β†’ ??? +3. Frontend renderiza componente β†’ FunciΓ³n: ??? β†’ Datos de: ??? +``` + +--- + +### PASO 1.3: Identificar conflictos +**DuraciΓ³n:** 5 min + +**Preguntas a responder:** +- ΒΏPor quΓ© existen 2 tablas (`wp_apus_theme_components` y `wp_apus_theme_components_defaults`)? +- ΒΏCuΓ‘l es el propΓ³sito de cada una? +- ΒΏSe estΓ‘n usando ambas o solo una? +- ΒΏHay duplicaciΓ³n de datos? + +**DecisiΓ³n arquitectΓ³nica:** +``` +OPCIΓ“N A (RECOMENDADA): +β”œβ”€ wp_apus_theme_components_defaults β†’ DEFAULTS (solo lectura tema) +β”œβ”€ wp_options (apus_theme_settings) β†’ PERSONALIZACIONES (lectura/escritura) +└─ ELIMINAR: wp_apus_theme_components (no usar) + +OPCIΓ“N B: +β”œβ”€ wp_apus_theme_components_defaults β†’ DEFAULTS (solo lectura tema) +β”œβ”€ wp_apus_theme_components β†’ PERSONALIZACIONES (lectura/escritura) +└─ ELIMINAR: wp_options (apus_theme_settings) (no usar) +``` + +--- + +## πŸ“‹ FASE 2: CORREGIR UBICACIΓ“N DEL MENÚ ADMIN + +### PASO 2.0: Mover menΓΊ a nivel superior del sidebar +**DuraciΓ³n:** 10 min + +**PROBLEMA ACTUAL:** +- ❌ "APUs Theme Settings" estΓ‘ bajo menΓΊ "Apariencia" +- ❌ Se usa `add_theme_page()` en `class-admin-menu.php` + +**SOLUCIΓ“N:** +- βœ… Crear menΓΊ propio en sidebar izquierdo (nivel superior) +- βœ… Cambiar a `add_menu_page()` en `class-admin-menu.php` + +**Modificar:** `admin/includes/class-admin-menu.php` + +**ANTES (lΓ­nea 28-36):** +```php +public function add_menu_page() { + add_theme_page( + 'APUs Theme Settings', // Page title + 'Tema APUs', // Menu title + 'manage_options', // Capability + 'apus-theme-settings', // Menu slug + array($this, 'render_admin_page'), // Callback + 59 // Position + ); +} +``` + +**DESPUΓ‰S:** +```php +public function add_menu_page() { + add_menu_page( + 'Apus Theme Options', // Page title + 'Apus Theme', // Menu title + 'manage_options', // Capability + 'apus-theme-settings', // Menu slug + array($this, 'render_admin_page'), // Callback + 'dashicons-admin-generic', // Icon (WordPress Dashicon) + 59 // Position (despuΓ©s de Settings) + ); +} +``` + +**Verificar:** +- [ ] MenΓΊ aparece en sidebar izquierdo +- [ ] Ícono es visible +- [ ] TΓ­tulo es "Apus Theme" +- [ ] Al hacer click abre el panel de configuraciΓ³n + +**Nota:** TambiΓ©n renombrar el mΓ©todo de `add_menu_page()` a algo mΓ‘s descriptivo si es necesario, ya que ahora usa la funciΓ³n `add_menu_page()` de WordPress. + +--- + +## πŸ“‹ FASE 3: CREAR DEFAULTS MANAGER + +### PASO 3.1: Crear clase Defaults Manager +**DuraciΓ³n:** 20 min + +**Archivo:** `admin/includes/class-defaults-manager.php` + +**MΓ©todos necesarios:** +```php +class APUS_Defaults_Manager { + // Leer todos los defaults de un componente + public function get_component_defaults($component_name); + + // Leer un default especΓ­fico + public function get_default($component_name, $config_key); + + // Listar componentes con defaults + public function list_components(); + + // Verificar si existen defaults para componente + public function has_defaults($component_name); +} +``` + +**Responsabilidades:** +- βœ… LEER de `wp_apus_theme_components_defaults` +- ❌ NO ESCRIBIR (escritura solo desde algoritmo) +- βœ… Parsear tipos de datos (boolean, integer, json, array) +- βœ… Cachear resultados (opcional, para performance) + +--- + +### PASO 3.2: Integrar Defaults Manager en init.php +**DuraciΓ³n:** 5 min + +**Modificar:** `admin/init.php` + +```php +// Cargar Defaults Manager +require_once APUS_ADMIN_PANEL_PATH . 'includes/class-defaults-manager.php'; + +// Inicializar +$defaults_manager = new APUS_Defaults_Manager(); +``` + +--- + +### PASO 3.3: Modificar Settings Manager para usar Defaults Manager +**DuraciΓ³n:** 15 min + +**Modificar:** `admin/includes/class-settings-manager.php` + +**Antes:** +```php +public function get_defaults() { + return array( + 'version' => APUS_ADMIN_PANEL_VERSION, + 'components' => array() + ); +} +``` + +**DespuΓ©s:** +```php +public function get_defaults() { + $defaults_manager = new APUS_Defaults_Manager(); + $components = $defaults_manager->list_components(); + + $defaults = array( + 'version' => APUS_ADMIN_PANEL_VERSION, + 'components' => array() + ); + + foreach ($components as $component_name) { + $defaults['components'][$component_name] = + $defaults_manager->get_component_defaults($component_name); + } + + return $defaults; +} +``` + +--- + +## πŸ“‹ FASE 4: DECISIΓ“N SOBRE PERSONALIZACIONES + +### PASO 4.1: Evaluar opciones +**DuraciΓ³n:** 10 min + +**OpciΓ³n A: Usar wp_options (RECOMENDADA)** +- βœ… MΓ‘s simple +- βœ… Ya implementado +- βœ… Funciona con Settings Manager actual +- ❌ Menos estructurado + +**OpciΓ³n B: Usar wp_apus_theme_components** +- βœ… MΓ‘s estructurado +- βœ… Usa DB Manager +- ❌ Requiere mΓ‘s cambios +- ❌ MΓ‘s complejo + +**DecisiΓ³n:** [A COMPLETAR POR USUARIO] + +--- + +### PASO 4.2: Implementar segΓΊn decisiΓ³n +**DuraciΓ³n:** Variable + +**Si OpciΓ³n A (wp_options):** +- [ ] Mantener Settings Manager como estΓ‘ +- [ ] Solo agregar get_defaults() con Defaults Manager +- [ ] save_settings() sigue guardando en wp_options + +**Si OpciΓ³n B (wp_apus_theme_components):** +- [ ] Modificar Settings Manager para usar DB Manager +- [ ] Cambiar save_settings() para guardar en tabla +- [ ] Cambiar get_settings() para leer de tabla +- [ ] Eliminar uso de wp_options + +--- + +## πŸ“‹ FASE 5: TESTING Y VALIDACIΓ“N + +### PASO 5.1: Poblar tabla de defaults con datos de prueba +**DuraciΓ³n:** 10 min + +**Insertar defaults de Top Bar:** +```sql +INSERT INTO wp_apus_theme_components_defaults +(component_name, config_key, config_value, data_type, version) +VALUES +('top_bar', 'enabled', '1', 'boolean', '2.0.0'), +('top_bar', 'message_text', 'Accede a mΓ‘s de 200,000...', 'string', '2.0.0'), +-- ... mΓ‘s configs +``` + +--- + +### PASO 5.2: Probar lectura de defaults +**DuraciΓ³n:** 10 min + +**Crear script de prueba:** `admin/test-defaults.php` + +```php +get_component_defaults('top_bar'); +echo "Top Bar Defaults:\n"; +print_r($top_bar_defaults); + +// Test 2: Obtener settings completos (defaults + personalizaciones) +$all_settings = $settings_manager->get_settings(); +echo "\nAll Settings:\n"; +print_r($all_settings); +``` + +--- + +### PASO 5.3: Probar guardar personalizaciones +**DuraciΓ³n:** 10 min + +**Test manual:** +1. Abrir Admin Panel +2. Modificar configuraciΓ³n de componente +3. Guardar cambios +4. Verificar que se guardΓ³ en lugar correcto (wp_options o tabla) +5. Recargar Admin Panel +6. Verificar que muestra personalizaciΓ³n + defaults + +--- + +### PASO 5.4: Probar renderizado en frontend +**DuraciΓ³n:** 10 min + +**Verificar:** +1. Frontend muestra defaults cuando no hay personalizaciones +2. Frontend muestra personalizaciones cuando las hay +3. PersonalizaciΓ³n sobrescribe default (merge correcto) + +--- + +## πŸ“‹ FASE 6: DOCUMENTACIΓ“N + +### PASO 6.1: Documentar arquitectura final +**DuraciΓ³n:** 15 min + +**Crear:** `admin/ARQUITECTURA-DATOS.md` + +**Contenido:** +- Diagrama de flujo de datos +- ExplicaciΓ³n de cada tabla +- ExplicaciΓ³n de cada clase +- CΓ³mo se combinan defaults + personalizaciones +- Ejemplos de uso + +--- + +## βœ… CHECKLIST FINAL + +Antes de modificar el algoritmo, verificar: + +- [ ] Existe `class-defaults-manager.php` +- [ ] Defaults Manager puede leer de `wp_apus_theme_components_defaults` +- [ ] Settings Manager usa Defaults Manager en `get_defaults()` +- [ ] Se decidiΓ³ dΓ³nde guardar personalizaciones (wp_options vs tabla) +- [ ] Tabla de defaults tiene datos de prueba +- [ ] Tests de lectura funcionan +- [ ] Tests de guardar funcionan +- [ ] Frontend renderiza correctamente +- [ ] Arquitectura estΓ‘ documentada + +--- + +## πŸš€ SIGUIENTE PASO + +Una vez completado este plan: +- βœ… TEMA LISTO para procesar datos de BD +- βœ… Puede leer defaults +- βœ… Puede combinar con personalizaciones +- βœ… Puede guardar personalizaciones +- βœ… Puede renderizar en frontend + +**ENTONCES:** +β†’ Proceder a modificar el algoritmo `/implementar-componente-admin`