From f0989f4fb0bab63494841d81aaa9fe2ac64f47d9 Mon Sep 17 00:00:00 2001 From: FrankZamora Date: Thu, 13 Nov 2025 22:59:27 -0600 Subject: [PATCH] =?UTF-8?q?docs:=20crear=20documentaci=C3=B3n=20completa?= =?UTF-8?q?=20de=20arquitectura=20de=20datos?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Diagrama de arquitectura final implementada - Estructura de tablas (defaults y components) - Flujo de datos completo (escritura/lectura) - Decisión arquitectónica: Opción A (wp_options para personalizaciones) - Responsabilidades de cada clase - Estado actual y próximos pasos - Checklist de verificación Completa documentación requerida por FASE 6 del plan --- admin/ARQUITECTURA-DATOS.md | 354 ++++++++++++++++++++++++++++++++++++ 1 file changed, 354 insertions(+) create mode 100644 admin/ARQUITECTURA-DATOS.md diff --git a/admin/ARQUITECTURA-DATOS.md b/admin/ARQUITECTURA-DATOS.md new file mode 100644 index 00000000..8306ebc7 --- /dev/null +++ b/admin/ARQUITECTURA-DATOS.md @@ -0,0 +1,354 @@ +# 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 +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