docs: crear documentación completa de arquitectura de datos
- 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
This commit is contained in:
FrankZamora
354
admin/ARQUITECTURA-DATOS.md
Normal file
354
admin/ARQUITECTURA-DATOS.md
Normal file
@@ -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
|
||||
<?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
|
||||
Reference in New Issue
Block a user