# CHANGELOG v1.5.5 - Corrección Estructura de Datos API

**Fecha:** 24 de Enero, 2026  
**Versión:** 1.5.5  
**Código:** 2026-01-etapa4-fix2  

---

## 🔧 Problema Identificado

En v1.5.4 se implementó normalización del formato de respuesta API, pero se extraía únicamente el array `variables`, descartando otras propiedades necesarias (`paises`, `periocidad`).

### Estructura de Respuesta API v2

```json
{
  "idTema": 1,
  "variables": [
    {
      "idVariable": 78,
      "codigoVariable": "CPI_T",
      "variable": "IPC general"
    }
  ],
  "paises": [
    {
      "id": 3,
      "nombre": "Costa Rica",
      "descripcion": "Costa Rica",
      "esPais": "TRUE"
    }
  ],
  "periocidad": [...]
}
```

### Comportamiento Incorrecto (v1.5.4)

```php
// Solo retornaba variables, perdiendo paises y periocidad
return $myJSONArray['variables'];
```

### Impacto

El shortcode `params-shortcode.php` intentaba acceder a:
- `$all[0]["variables"]` ✅
- `$all[0]["paises"]` ❌ No existía
- `$all[0]["periocidad"]` ❌ No existía

**Resultado:** Los selectores de países, regiones y periodos no se mostraban en la página de parámetros.

---

## ✅ Solución Implementada

### Cambio en `inc/api.php` (líneas 181-197)

```php
// NUEVO: Normalizar formato de respuesta
// La nueva API retorna: {"idTema": X, "variables": [...], "paises": [...], "periocidad": [...]}
// El código espera: [{"variables": [...], "paises": [...], "periocidad": [...]}]
if (is_array($myJSONArray) && isset($myJSONArray['variables'])) {
    // Formato nuevo detectado, envolver en array para mantener compatibilidad con $all[0]
    if (is_user_logged_in() && function_exists('is_user_logged_in')) {
        echo "<div style='background: #e3f2fd; border-left: 4px solid #2196F3; padding: 12px; margin: 10px 0;'>";
        echo "<strong>🔄 Formato Normalizado</strong><br>";
        echo "<code>Detectado formato nuevo API v2</code><br>";
        echo "<code>Total variables: " . count($myJSONArray['variables']) . "</code><br>";
        echo "<code>Total países: " . (isset($myJSONArray['paises']) ? count($myJSONArray['paises']) : 0) . "</code><br>";
        echo "<code>Estructura convertida a: \$all[0]['variables'], \$all[0]['paises']</code>";
        echo "</div>";
    }
    // Envolver el objeto en un array para que sea accesible como $all[0]
    return [$myJSONArray];
}

return $myJSONArray;
```

### Estrategia

1. **Detectar formato nuevo:** Verificar si existe la clave `variables` en la respuesta
2. **Mantener objeto completo:** No extraer solo `variables`, mantener todo el objeto
3. **Envolver en array:** Convertir `{...}` en `[{...}]` para compatibilidad con `$all[0]`
4. **Debug mejorado:** Mostrar total de variables y países al normalizar

---

## 🎯 Resultado Esperado

### Debug Output

```
🔍 DEBUG get_report_variables()
URL: http://192.168.100.137:8081/simafir_api/ws/public/v1/criterios/IPC_GENERAL
Data param: IPC_GENERAL

📥 Response (primeros 500 chars)
{"idTema":1,"variables":[...],"paises":[...]}

🔄 Formato Normalizado
Detectado formato nuevo API v2
Total variables: 4
Total países: 7
Estructura convertida a: $all[0]['variables'], $all[0]['paises']
```

### Acceso en Shortcode

```php
// ✅ Ahora funcionan todos estos accesos
$all[0]["variables"]   // Array de variables
$all[0]["paises"]      // Array de países y regiones
$all[0]["periocidad"]  // Array de periodicidades (si existe)
```

### UI Esperada

- ✅ Selector de **Variables** con 4 opciones
- ✅ Selector de **Países** con lista completa
- ✅ Tab de **Regiones** si aplica
- ✅ Selector de **Periodicidad** si aplica
- ✅ Botones "Seleccionar todo" / "Eliminar todo" funcionales

---

## 📋 Testing Checklist

### Test 1: IPC General
- URL: `/params/?cid=0&scid=0&data=IPC_GENERAL&parent=Precios&son=IPC%20general`
- ✅ Deben mostrarse 4 variables (IPC general, variación mensual, interanual, acumulada)
- ✅ Deben mostrarse ~7 países de Centroamérica
- ✅ Tab "Regiones" debe estar visible

### Test 2: Tipo de Cambio
- URL: `/params/?cid=3&scid=0&data=TIP_CAMBIO_MERCADO&parent=Tipos%20de%20cambio&son=Tipo%20de%20cambio%20de%20mercado`
- ✅ Deben mostrarse variables de tipo de cambio
- ✅ Selector de países funcional
- ✅ Selector de periodicidad funcional

### Test 3: Retrocompatibilidad
- Probar endpoint antiguo (si existe): `/criterios/obtenerPorTema/IPC_GENERAL`
- ✅ Debe funcionar sin errores si devuelve formato antiguo (array directo)

---

## 🔍 Validación de Código

### Sintaxis PHP
```bash
php -l inc/api.php
# No syntax errors detected in inc/api.php
```

### Estructura de Variables
```php
// Antes de normalizar (API v2)
var_dump($myJSONArray);
// array(3) {
//   ["idTema"]=> int(1)
//   ["variables"]=> array(4) {...}
//   ["paises"]=> array(7) {...}
// }

// Después de normalizar
var_dump($result);
// array(1) {
//   [0]=> array(3) {
//     ["idTema"]=> int(1)
//     ["variables"]=> array(4) {...}
//     ["paises"]=> array(7) {...}
//   }
// }
```

---

## 📊 Impacto de Cambios

### Archivos Modificados
1. **inc/api.php** (líneas 181-197)
   - Cambio en lógica de normalización
   - Mejora en debug output

2. **secmca-api.php** (líneas 7, 12)
   - Version: `1.5.4` → `1.5.5`
   - SECMCA_VER: `2026-01-etapa4-fix` → `2026-01-etapa4-fix2`

### Funciones Afectadas
- ✅ `get_report_variables($data)` - Corregida

### Shortcodes Beneficiados
- ✅ `[scm-params]` - SIMAFIR params page
- Potencialmente: `[scm-emfa-params]`, `[scm-efpa-params]` (si usan la misma función)

---

## 🎁 Beneficios

1. **Selectores Completos:** Ahora se muestran todos los parámetros de consulta
2. **Compatibilidad Dual:** Funciona con API v1 y v2 sin cambios en shortcodes
3. **Debug Mejorado:** Muestra cantidad de variables y países detectados
4. **Estructura Consistente:** Mantiene el patrón `$all[0][key]` existente en código
5. **Sin Regresiones:** No rompe funcionalidad existente

---

## ⚠️ Notas Técnicas

### Formato API v1 vs v2

| Aspecto | API v1 (Antigua) | API v2 (Nueva) |
|---------|------------------|----------------|
| Estructura raíz | Array `[{...}]` | Objeto `{...}` |
| Variables | Directamente en `[0]` | Dentro de `variables` key |
| Países | Directamente en `[0]` | Dentro de `paises` key |
| Metadata | No incluida | `idTema` incluido |
| Compatibilidad | v1.0 - v1.4 | v1.5+ con normalización |

### Lógica de Detección

```php
// Si tiene key 'variables', es formato nuevo
if (is_array($myJSONArray) && isset($myJSONArray['variables'])) {
    // Envolver en array: {...} → [{...}]
    return [$myJSONArray];
}

// Si no, es formato antiguo (ya es array)
return $myJSONArray;
```

---

## 🚀 Próximos Pasos

1. **Instalar v1.5.5 en producción** ✅
2. **Validar página de parámetros** - Verificar selectores completos
3. **Probar flujo completo** - Desde parámetros hasta gráfico
4. **Decidir sobre debug logs** - Mantener o remover
5. **Continuar con Etapa 4B** - Migración endpoints EMFA

---

## 📦 Entregables

- ✅ **secmca-api-v1.5.5.zip** (2.9MB)
- ✅ Código validado sin errores de sintaxis
- ✅ CHANGELOG completo con documentación técnica
- ✅ Debug output mejorado para facilitar validación

---

## 👥 Créditos

**Desarrollador:** Fabian Hidalgo / Codeskill.io  
**Asistencia Técnica:** GitHub Copilot  
**Fecha de Release:** 24 de Enero, 2026  

---

## 📚 Referencias

- **Versión anterior:** v1.5.4 (extracción solo de variables)
- **Issue:** Selectores de países y periodicidad no se mostraban
- **Root cause:** Normalización incompleta de estructura API v2
- **Solución:** Envolver objeto completo en array para mantener acceso `[0]`
