From 883853bc5c1feed47e645723d6141bc5738e75f3 Mon Sep 17 00:00:00 2001 From: FrankZamora Date: Thu, 13 Nov 2025 22:36:34 -0600 Subject: [PATCH] =?UTF-8?q?docs:=20agregar=20plan=20de=20preparaci=C3=B3n?= =?UTF-8?q?=20del=20tema=20para=20BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Plan de 6 fases para preparar tema antes de modificar algoritmo - FASE 1: Análisis de arquitectura actual - FASE 2: Corregir ubicación del menú admin (nuevo paso agregado) * Cambiar add_theme_page() a add_menu_page() * Mover 'Apus Theme Options' a menú propio en sidebar - FASE 3: Crear Defaults Manager - FASE 4: Decisión sobre personalizaciones - FASE 5: Testing y validación - FASE 6: Documentación Plan ejecutable paso a paso antes de tocar algoritmo. --- admin/PLAN-PREPARACION-TEMA-BD.md | 412 ++++++++++++++++++++++++++++++ 1 file changed, 412 insertions(+) create mode 100644 admin/PLAN-PREPARACION-TEMA-BD.md diff --git a/admin/PLAN-PREPARACION-TEMA-BD.md b/admin/PLAN-PREPARACION-TEMA-BD.md new file mode 100644 index 00000000..55d216e9 --- /dev/null +++ b/admin/PLAN-PREPARACION-TEMA-BD.md @@ -0,0 +1,412 @@ +# 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 +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`