roi-theme/admin/PLAN-PREPARACION-TEMA-BD.md

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:

-- 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):

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:

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)
        61                               // Position (61 = después de Settings que es 80)
    );
}

IMPORTANTE - Ubicación esperada en sidebar:

Dashboard
Posts
Media
Pages
Comments
...
Settings
Apus Theme  ← AL MISMO NIVEL que Settings (NO dentro)

Posiciones de menús WordPress:

2   - Dashboard
4   - Separator
5   - Posts
10  - Media
15  - Links
20  - Pages
25  - Comments
59  - Separator
60  - Appearance
65  - Plugins
70  - Users
75  - Tools
80  - Settings
100 - Separator

Usar posición 61 para que quede:

• Después de "Appearance" (60)
• Antes de "Plugins" (65)
• AL MISMO NIVEL que todos los menús principales

Verificar:

• Menú aparece en sidebar izquierdo
• Menú está AL MISMO NIVEL que "Settings", "Dashboard", etc.
• Menú NO está dentro de ningún otro menú
• Í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:

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

// 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:

public function get_defaults() {
    return array(
        'version' => APUS_ADMIN_PANEL_VERSION,
        'components' => array()
    );
}

Después:

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:

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
require_once 'wp-load.php';

$defaults_manager = new APUS_Defaults_Manager();
$settings_manager = new APUS_Settings_Manager();

// Test 1: Leer defaults de Top Bar
$top_bar_defaults = $defaults_manager->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