# Sistema de Debug Flotante - SECMCA API v1.5.23

## 🎯 Descripción

Sistema de debug profesional con burbuja flotante y panel modal que muestra paso a paso todas las operaciones del API, incluyendo autenticación, obtención de parámetros y consulta de datos.

## ✨ Características

### 🔹 Burbuja Flotante
- **Posición**: Esquina inferior derecha
- **Badge**: Muestra el número de eventos registrados
- **Animación**: Efecto pulse para llamar la atención
- **Interactivo**: Click para abrir el panel de debug

### 🔹 Panel Modal
- **Diseño**: Popup centrado con fondo blur
- **Responsive**: Se adapta a dispositivos móviles
- **Scrollable**: Maneja grandes cantidades de información
- **Colapsable**: Cada paso se puede expandir/colapsar

### 🔹 Información por Paso
Cada operación muestra:
1. **🔐 Obtener Token** (si aplica)
   - URL de autenticación consultada
   - Payload enviado
   - HTTP Status Code
   - Respuesta completa del servidor
   - Token generado (preview)

2. **📋 Consultar Parámetros/Criterios**
   - URL consultada
   - Headers enviados
   - HTTP Status Code
   - Respuesta JSON completa
   - Resumen de datos obtenidos

3. **🔄 Formateo de Datos** (si aplica)
   - Transformaciones realizadas
   - Estructura final
   - Notas sobre compatibilidad

4. **📊 Consultar Datos** (si aplica)
   - URL consultada
   - Token utilizado
   - Headers enviados
   - HTTP Status Code
   - Respuesta del servidor

## 🚀 Cómo Usar

### 1. Instalar el Plugin
- Descomprimir `secmca-api-v1.5.23-DEBUG-PANEL-FLOTANTE.zip`
- Subir a WordPress
- Activar el plugin

### 2. Ver el Debug Panel
- **Requisito**: Usuario debe estar logueado en WordPress
- La burbuja aparece automáticamente en la esquina inferior derecha
- Click en la burbuja para abrir el panel
- El badge muestra cuántos eventos se han registrado

### 3. Navegar por el Panel
- Cada sesión (consulta) aparece como una tarjeta
- **Color Verde**: Operación exitosa
- **Color Rojo**: Operación con error
- **Color Amarillo**: Advertencia
- Click en el header de cada tarjeta para expandir/colapsar
- Scroll para ver toda la información

### 4. Cerrar el Panel
- Click en el botón ✕ del header
- Click fuera del modal
- Presionar tecla ESC

## 📁 Archivos del Sistema

```
secmca-api/
├── assets/
│   ├── css/
│   │   └── debug-panel.css          # Estilos del panel flotante
│   └── js/
│       └── debug-panel.js            # Lógica JavaScript del panel
├── inc/
│   └── api.php                       # Funciones de debug integradas
└── secmca-api.php                    # Enqueue de archivos CSS/JS
```

## 🔧 Funciones Principales

### En `api.php`:

```php
// Iniciar sesión de debug
$this->debug_start_session('Nombre de la Operación');

// Agregar un paso
$this->debug_add_step(array(
    'title' => '📋 Título del Paso',
    'url' => 'https://api.example.com/endpoint',
    'headers' => array(...),
    'httpStatus' => 200,
    'response' => $jsonData,
    'notes' => 'Información adicional'
));

// Finalizar sesión
$this->debug_end_session('success'); // o 'error', 'warning'
```

### En JavaScript:

```javascript
// El sistema registra automáticamente los eventos
window.SECMCADebug.events      // Array de eventos
window.SECMCADebug.clearEvents()  // Limpiar eventos
window.SECMCADebug.renderEvents() // Re-renderizar panel
```

## 🎨 Personalización

### Cambiar Posición de la Burbuja
Editar `assets/css/debug-panel.css`:
```css
.secmca-debug-bubble {
    bottom: 20px;  /* Cambiar distancia desde abajo */
    right: 20px;   /* Cambiar distancia desde derecha */
}
```

### Cambiar Colores
Editar variables en `assets/css/debug-panel.css`:
```css
/* Header gradient */
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);

/* Success color */
.secmca-debug-step.success { border-color: #28a745; }

/* Error color */
.secmca-debug-step.error { border-color: #dc3545; }
```

## 📊 Ejemplo de Uso

Cuando un usuario carga una página con parámetros EFPA:

1. Se inicia sesión: `"Obtener Parámetros/Criterios"`
2. Se agrega paso: `"🔐 Obtener Token de Autenticación"`
   - Muestra URL, payload, status 200, token generado
3. Se agrega paso: `"📋 Consultar Parámetros/Criterios"`
   - Muestra URL, headers, status 200, JSON con países, variables, etc.
4. Se agrega paso: `"🔄 Formateo y Transformación de Datos"`
   - Muestra estructura transformada para compatibilidad
5. Se finaliza sesión: `success`

El usuario ve una tarjeta verde expandible con todos estos pasos.

## 🐛 Troubleshooting

### La burbuja no aparece
- ✅ Verificar que el usuario esté logueado
- ✅ Verificar que los archivos CSS/JS se carguen correctamente
- ✅ Revisar consola del navegador por errores

### El panel no muestra información
- ✅ Verificar que `window.SECMCADebug` exista en consola
- ✅ Revisar que las funciones de debug se estén llamando
- ✅ Verificar que `is_user_logged_in()` retorne true

### Información incompleta
- ✅ Asegurarse de llamar `debug_start_session()` al inicio
- ✅ Agregar todos los pasos necesarios con `debug_add_step()`
- ✅ Finalizar con `debug_end_session()` al final

## 📝 Notas Importantes

1. **Solo visible para usuarios logueados**: El panel NO aparece para visitantes anónimos
2. **Performance**: Los eventos se almacenan en memoria JavaScript, no afectan la base de datos
3. **Seguridad**: Toda la información sensible (tokens) se muestra solo parcialmente
4. **Producción**: Considerar desactivar en producción modificando `is_user_logged_in()`

## 🔄 Changelog v1.5.23

- ✅ Sistema de debug flotante implementado
- ✅ Panel modal con información paso a paso
- ✅ Integración con funciones de autenticación
- ✅ Integración con obtención de parámetros
- ✅ Diseño responsive y profesional
- ✅ Animaciones y transiciones suaves
- ✅ Soporte para múltiples sesiones
- ✅ Estados de éxito/error/advertencia

## 👨‍💻 Desarrollo

Para modificar el sistema de debug:

1. **CSS**: Editar `assets/css/debug-panel.css`
2. **JavaScript**: Editar `assets/js/debug-panel.js`
3. **PHP**: Modificar funciones `debug_*` en `inc/api.php`
4. **Limpiar cache** del navegador después de cambios

## 📧 Soporte

Para reportar bugs o solicitar mejoras, contactar al equipo de desarrollo.

---

**Versión**: 1.5.23  
**Fecha**: Enero 2026  
**Autor**: Fabian Hidalgo / Codeskill.io
