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:

```sql
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)

```php
// 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)

```php
// 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)

```php
// 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)

```php
// 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

```php
// 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:**
```php
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:**
```php
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:

```sql
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
<?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?

```php
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