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:**
```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
<?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`