docs: agregar plan de preparación del tema para BD
- 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.
This commit is contained in:
FrankZamora
412
admin/PLAN-PREPARACION-TEMA-BD.md
Normal file
412
admin/PLAN-PREPARACION-TEMA-BD.md
Normal file
@@ -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
|
||||
<?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`
|
||||
Reference in New Issue
Block a user