roi-theme/admin/ARQUITECTURA-DATOS.md

Arquitectura de Datos - Apus Theme

Fecha: 2025-01-14 Versión: 2.2.0

---

📊 ARQUITECTURA FINAL IMPLEMENTADA

┌──────────────────────────────────────────────────────────────┐
│ APUS_DB_MANAGER (Clase Única)                               │
│ ├─ Maneja AMBAS tablas con misma estructura                 │
│ ├─ Parámetro: table_type = 'components' | 'defaults'        │
│ └─ Métodos:                                                  │
│    ├─ get_config($component, $key, $table_type)             │
│    ├─ save_config(..., $table_type)                         │
│    ├─ delete_config(..., $table_type)                       │
│    └─ list_components($table_type)                          │
└──────────────────────────────────────────────────────────────┘
                            ↓
        ┌───────────────────────────────────────┐
        │                                       │
        ↓                                       ↓
┌─────────────────────┐           ┌─────────────────────┐
│ TABLA: DEFAULTS     │           │ TABLA: COMPONENTS   │
├─────────────────────┤           ├─────────────────────┤
│ wp_apus_theme_      │           │ wp_apus_theme_      │
│ components_defaults │           │ components          │
├─────────────────────┤           ├─────────────────────┤
│ PROPÓSITO:          │           │ PROPÓSITO:          │
│ Valores por defecto │           │ Personalizaciones   │
│ del tema            │           │ del usuario         │
├─────────────────────┤           ├─────────────────────┤
│ ESCRITURA:          │           │ ESCRITURA:          │
│ Algoritmo           │           │ Admin Panel         │
│ /implementar-       │           │ (Settings Manager)  │
│ componente-admin    │           │                     │
├─────────────────────┤           ├─────────────────────┤
│ LECTURA:            │           │ LECTURA:            │
│ Settings Manager    │           │ Settings Manager    │
│ Frontend            │           │ Frontend            │
└─────────────────────┘           └─────────────────────┘

---

🗄️ ESTRUCTURA DE TABLAS (Idéntica)

Ambas tablas tienen la misma estructura:

CREATE TABLE wp_apus_theme_components_defaults (
    id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    component_name VARCHAR(50) NOT NULL,
    config_key VARCHAR(100) NOT NULL,
    config_value TEXT NOT NULL,
    data_type ENUM('string', 'boolean', 'integer', 'json') DEFAULT 'string',
    version VARCHAR(10) DEFAULT NULL,
    updated_at DATETIME NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    UNIQUE KEY component_config (component_name, config_key),
    INDEX idx_component (component_name),
    INDEX idx_updated (updated_at)
);

-- Misma estructura para wp_apus_theme_components

---

🔄 FLUJO DE DATOS

1. ESCRITURA DE DEFAULTS (Algoritmo)

// Algoritmo escribe defaults a tabla defaults
$db_manager = new APUS_DB_Manager();
$db_manager->save_config(
    'top_bar',                  // component_name
    'enabled',                  // config_key
    '1',                        // config_value
    'boolean',                  // data_type
    '2.0.0',                    // version
    'defaults'                  // table_type ← IMPORTANTE
);

2. LECTURA DE DEFAULTS (Settings Manager)

// Settings Manager lee defaults
public function get_defaults() {
    $db_manager = new APUS_DB_Manager();
    $component_names = $db_manager->list_components('defaults');

    $defaults = array(
        'version' => APUS_ADMIN_PANEL_VERSION,
        'components' => array()
    );

    foreach ($component_names as $component_name) {
        $defaults['components'][$component_name] =
            $db_manager->get_config($component_name, null, 'defaults');
    }

    return $defaults;
}

3. ESCRITURA DE PERSONALIZACIONES (Admin Panel)

// Settings Manager guarda personalizaciones en wp_options
public function save_settings($data) {
    // Validar y sanitizar...

    $sanitized['version'] = APUS_ADMIN_PANEL_VERSION;
    $sanitized['updated_at'] = current_time('mysql');

    // Guardar en wp_options
    update_option(self::OPTION_NAME, $sanitized, false);

    return array('success' => true);
}

4. MERGE DE DATOS (Settings Manager)

// Combinar defaults + personalizaciones
public function get_settings() {
    $settings = get_option(self::OPTION_NAME, array());
    $defaults = $this->get_defaults();

    // wp_parse_args combina: personalizaciones sobrescriben defaults
    return wp_parse_args($settings, $defaults);
}

5. LECTURA EN FRONTEND

// Frontend obtiene datos combinados
$settings_manager = new APUS_Settings_Manager();
$all_settings = $settings_manager->get_settings();

// Ejemplo: Top Bar
$top_bar_config = $all_settings['components']['top_bar'];
echo $top_bar_config['message_text']; // Default o personalizado

---

🎯 DECISIÓN ARQUITECTÓNICA: OPCIÓN A

Personalizaciones se guardan en: wp_options (opción apus_theme_settings)

✅ Ventajas Opción A (Implementada):

• Más simple y directo
• Ya implementado y funcionando
• Compatible con Settings Manager actual
• Fácil de migrar/exportar (una sola opción)
• Respaldado automáticamente con wp_options

❌ Opción B Descartada:

• Guardar personalizaciones en wp_apus_theme_components
• Más complejo
• Requeriría cambios extensos en Settings Manager
• No aporta beneficios claros sobre Opción A

---

📝 CLASES Y RESPONSABILIDADES

APUS_DB_Manager

Ubicación: admin/includes/class-db-manager.php

Responsabilidades:

• ✅ Crear ambas tablas (components y defaults)
• ✅ CRUD en tabla defaults (algoritmo escribe)
• ✅ CRUD en tabla components (si se necesita en futuro)
• ✅ Parsear tipos de datos (boolean, integer, json, string)

Métodos principales:

get_table_name($table_type = 'components')
create_tables()
table_exists($table_type = 'components')
save_config($component, $key, $value, $data_type, $version, $table_type = 'components')
get_config($component, $key = null, $table_type = 'components')
delete_config($component, $key = null, $table_type = 'components')
list_components($table_type = 'components')

APUS_Settings_Manager

Ubicación: admin/includes/class-settings-manager.php

Responsabilidades:

• ✅ Leer defaults desde tabla defaults (vía DB Manager)
• ✅ Leer personalizaciones desde wp_options
• ✅ Combinar defaults + personalizaciones (merge)
• ✅ Guardar personalizaciones en wp_options
• ✅ Validar datos (vía Validator)
• ✅ Sanitizar datos
• ✅ AJAX endpoints (get/save)

Métodos principales:

get_settings()        // Retorna: defaults + personalizaciones
get_defaults()        // Lee desde tabla defaults
save_settings($data)  // Guarda en wp_options
ajax_get_settings()   // AJAX endpoint
ajax_save_settings()  // AJAX endpoint

---

🚀 ESTADO ACTUAL

✅ COMPLETADO:

1. ✅ APUS_DB_Manager mejorado para soportar ambas tablas
2. ✅ Ambas tablas creadas (vacías)
3. ✅ Settings Manager integrado con DB Manager
4. ✅ get_defaults() lee desde tabla defaults
5. ✅ Menú admin movido a nivel superior en sidebar
6. ✅ Sistema listo para leer/escribir datos

⏳ PENDIENTE:

1. ⏳ Poblar tabla defaults con datos de prueba
2. ⏳ Probar lectura de defaults
3. ⏳ Probar guardar personalizaciones
4. ⏳ Probar merge defaults + personalizaciones
5. ⏳ Probar renderizado en frontend
6. ⏳ Modificar algoritmo /implementar-componente-admin

---

📋 PRÓXIMOS PASOS

PASO 5.1: Poblar tabla defaults

Insertar datos de prueba del componente Top Bar:

INSERT INTO wp_apus_theme_components_defaults
(component_name, config_key, config_value, data_type, version, updated_at)
VALUES
('top_bar', 'enabled', '1', 'boolean', '2.0.0', NOW()),
('top_bar', 'message_text', 'Accede a más de 200,000 Análisis...', 'string', '2.0.0', NOW()),
('top_bar', 'show_icon', '1', 'boolean', '2.0.0', NOW()),
('top_bar', 'icon_class', 'bi bi-megaphone-fill', 'string', '2.0.0', NOW()),
('top_bar', 'cta_text', 'Ver Catálogo', 'string', '2.0.0', NOW()),
('top_bar', 'cta_url', '#', 'string', '2.0.0', NOW());

PASO 5.2: Crear script de prueba

Archivo: admin/test-defaults.php

<?php
require_once '../../../wp-load.php';

$db_manager = new APUS_DB_Manager();
$settings_manager = new APUS_Settings_Manager();

// Test 1: Leer defaults de DB
echo "=== TEST 1: Leer defaults de tabla ===\n";
$defaults = $settings_manager->get_defaults();
print_r($defaults);

// Test 2: Guardar personalización
echo "\n=== TEST 2: Guardar personalización ===\n";
$custom_data = array(
    'components' => array(
        'top_bar' => array(
            'message_text' => 'Texto personalizado por usuario'
        )
    )
);
$result = $settings_manager->save_settings($custom_data);
print_r($result);

// Test 3: Leer settings combinados
echo "\n=== TEST 3: Leer settings combinados ===\n";
$all_settings = $settings_manager->get_settings();
print_r($all_settings);

---

🎓 CONCEPTOS CLAVE

¿Por qué UNA clase para ambas tablas?

Razón: Ambas tablas tienen estructura idéntica y almacenan el mismo tipo de datos (configuraciones de componentes). La única diferencia es el PROPÓSITO:

• Defaults: Valores originales del tema
• Components: Personalizaciones del usuario

Usar una sola clase con parámetro table_type es más limpio y DRY (Don't Repeat Yourself).

¿Dónde se almacenan las personalizaciones?

wp_options (opción apus_theme_settings)

¿Por qué no en tabla components?

• Más simple
• Ya implementado
• Fácil de migrar/exportar
• La tabla components queda disponible para uso futuro si se necesita

¿Cómo funciona el merge?

wp_parse_args($personalizaciones, $defaults)

Resultado:

• Si existe personalización para una clave → usa personalización
• Si NO existe personalización → usa default
• Ejemplo:
  • Default: message_text = "Accede a más de 200,000..."
  • Personalización: message_text = "Texto personalizado"
  • Resultado: "Texto personalizado"

---

🔍 VERIFICACIÓN DE ARQUITECTURA

Checklist pre-modificación de algoritmo:

• ✅ Existe APUS_DB_Manager con soporte para ambas tablas
• ✅ DB Manager puede leer/escribir en tabla defaults
• ✅ Settings Manager usa DB Manager para get_defaults()
• ✅ Settings Manager guarda personalizaciones en wp_options
• ✅ Ambas tablas existen en la base de datos
• ⏳ Tabla defaults tiene datos de prueba
• ⏳ Tests de lectura funcionan
• ⏳ Tests de escritura funcionan
• ⏳ Frontend renderiza correctamente

---

Última actualización: 2025-01-14 Estado: ARQUITECTURA IMPLEMENTADA - LISTO PARA TESTING