# 🚀 Sistema de Costos Dinámicos de Créditos - PREALTUM v4

## 📋 Resumen de Cambios

Este documento describe la implementación completa del sistema de **costos dinámicos por créditos**, incluyendo:

- ✅ Corrección del error `Call to undefined fl` 
- ✅ Cálculo dinámico de costos según cantidad de preguntas y dificultad
- ✅ Panel de configuración de costos en admin
- ✅ Reporte de gastos de créditos en superadmin
- ✅ Validación mejorada de créditos con mensajes claros
- ✅ Sistema compatible con planes SaaS

---

## 🔧 Instalación

### 1. **Ejecutar Script SQL**

```bash
# Accede a tu base de datos MySQL y ejecuta:
mysql -u usuario -p nombre_base_datos < /path/to/sql/setup_costos_dinamicos.sql
```

O copia y pega el contenido de `sql/setup_costos_dinamicos.sql` en phpMyAdmin.

### 2. **Verificar Carpetas y Archivos**

Los siguientes archivos deben estar presentes:

```
public/admin/
├── config_creditos.php          ← NUEVO: Panel de configuración
├── questions.php                ← ACTUALIZADO: Mejorado costos dinámicos

public/superadmin/
├── reporte_creditos.php         ← NUEVO: Reporte de gastos

public/api.php                   ← ACTUALIZADO: Corregido error y validaciones

src/
├── CreditosManager.php          ← ACTUALIZADO: Nuevo método calcularCostoDinamico

sql/
└── setup_costos_dinamicos.sql   ← NUEVO: Script de configuración

```

---

## 💰 Fórmula de Cálculo de Costos

```
COSTO TOTAL = COSTO_BASE + (NUM_PREGUNTAS × PRECIO_POR_PREGUNTA) + PRECIO_POR_DIFICULTAD
```

### Ejemplo de Configuración Predeterminada:

| Tipo | Base | Por Pregunta | Dificultad 1-5 | Descripción |
|------|------|--------------|----------------|-------------|
| 🧪 Simulacro | 20 | 1 | 1,2,3,4,5 | Práctica estándar |
| 📝 Examen | 50 | 2 | 2,4,6,8,10 | Examen oficial |
| 🩺 Diagnóstico | 30 | 1 | 1,2,3,4,5 | Inicio |
| ✏️ Práctica | 10 | 0 | 0,0,0,0,0 | Sin costo adicional |
| 🔁 Repaso | 15 | 0 | 0,0,0,0,0 | Rápido |
| 📚 Curso | 25 | 1 | 1,2,3,4,5 | Reto |

---

## 🎯 Funcionalidades Implementadas

### 1. **Panel de Configuración de Costos** (`public/admin/config_creditos.php`)

📍 Acceso: **Admin → Configuración de Costos**

- ✅ Ver configuración actual de todos los tipos de generación
- ✅ Editar costos en tiempo real
- ✅ Configurar precios dinámicos por dificultad (JSON)
- ✅ Fórmula de cálculo visible

**Panel de acceso rápido:**
```
[Admin Dashboard] → [Gestión] → [⚙️ Configuración de Costos]
```

### 2. **Validación Mejorada de Créditos**

El sistema ahora:

✅ Calcula el costo ANTES de generar
✅ Muestra detalles claros del costo:
   - Costo base del tipo
   - Costo por número de preguntas
   - Bonus por dificultad
✅ Valida suficiente saldo
✅ Muestra mensajes de error detallados:
   ```
   ❌ Créditos insuficientes
   
   📋 Detalles:
   • Requieres: 47 🪙
   • Tienes: 30 🪙
   • Faltan: 17 🪙
   
   💡 Contacta a soporte para recargar tu plan.
   ```

### 3. **Reporte de Gastos** (`public/superadmin/reporte_creditos.php`)

📍 Acceso: **Superadmin → Reportes → Reporte de Créditos**

Visualiza:

- 📊 **Estadísticas Globales:**
  - Total gastado
  - Total recargado
  - Movimientos totales
  - Usuarios activos

- 💰 **Gastos por Tipo:**
  - Desglose de gastos por tipo de generación
  - Cantidad de movimientos por tipo

- 👥 **Top 5 Usuarios:**
  - Usuarios que más gastan créditos
  - Total gastado y movimientos

- 📋 **Movimientos Detallados:**
  - Historial completo de transacciones
  - Filtrable por:
    - Usuario
    - Tipo (gasto/recarga)
    - Fecha desde/hasta

---

## 🐛 Errores Corregidos

### ❌ Error Principal: `Call to undefined fl`

**Causa:** Función `checkPregsFilter()` no estaba definida en JavaScript

**Solución:** Se agregó la función completa en el objeto Alpine.js

```javascript
checkPregsFilter(val) {
  if (!this.simFilterPregs) return true;
  const range = this.simFilterPregs;
  if (range === '1-20') return val >= 1 && val <= 20;
  // ... resto de lógica
  return true;
}
```

### ❌ Error Secundario: `sc_api()` función no definida

**Causa:** Llamada a función inexistente en PHP

**Solución:** Se reemplazó por `query(...)->fetchColumn()`

```php
// Antes (INCORRECTO):
if(sc_api("SELECT COUNT(*) FROM configuracion_creditos") == 0) { ... }

// Después (CORRECTO):
$countCostos = query("SELECT COUNT(*) FROM configuracion_creditos")->fetchColumn();
if ($countCostos == 0) { ... }
```

---

## 📊 Estructura de Bases de Datos

### Tabla: `costos_creditos_config`

```sql
id                    INT PRIMARY KEY
tipo_actividad        VARCHAR(50) UNIQUE        -- simulacro, examen, etc.
costo_base            INT                       -- Base fija
precio_por_pregunta   INT                       -- Multiplicador por pregunta
precio_por_dificultad JSON                      -- {"1":1,"2":2,...,"5":5}
activo                TINYINT DEFAULT 1
descripcion           VARCHAR(255)
actualizado_en        TIMESTAMP
```

### Tabla: `creditos_movimientos`

```sql
id                INT PRIMARY KEY
usuario_id        INT
tipo              VARCHAR(20)      -- gasto|recarga|ajuste
accion            VARCHAR(50)      -- simulacro|examen|plan_change
creditos          INT              -- Cantidad (negativo=gasto)
saldo_anterior    INT
saldo_posterior   INT
descripcion       TEXT
creado_en         TIMESTAMP
```

---

## 🔐 Permisos Requeridos

| Recurso | Role Requerido | Acceso |
|---------|---------------|--------|
| `config_creditos.php` | admin, superadmin | Lectura + Edición |
| `reporte_creditos.php` | superadmin | Solo lectura |
| Generación IA | admin, superadmin | Con validación de créditos |

---

## 📱 Interfaz de Usuario

### Panel de Generación (Mejorado)

Antes de generar, el usuario ve:

```
✨ Generar  [Costo: 47 🪙]
```

Al hacer clic, valida:
1. ✅ Tiene carrera seleccionada
2. ✅ Tiene suficientes créditos
3. ✅ Muestra desglose de costo
4. ✅ Genera con indicador de progreso

---

## 🧪 Pruebas

### Test 1: Generar con Suficientes Créditos

```
1. Ir a Admin → Simulacros
2. Configurar: 50 preguntas, Dificultad "Muy alto"
3. Costo estimado: ~75 🪙
4. Hacer clic en "Generar"
5. ✅ Debe generarse exitosamente
6. ✅ Restar créditos de la cuenta
```

### Test 2: Generar sin Suficientes Créditos

```
1. Tener saldo < 30 🪙
2. Intentar generar Examen de 50 preguntas
3. ❌ Debe rechazar con mensaje claro
4. ✅ No debe restar créditos
```

### Test 3: Reporte de Gastos

```
1. Ir a Superadmin → Reporte de Créditos
2. ✅ Ver estadísticas globales
3. ✅ Ver usuarios con más gastos
4. ✅ Filtrar por usuario o fecha
5. ✅ Ver historial detallado
```

---

## 🚀 Próximas Mejoras (Opcionales)

- [ ] Integración con Stripe para pagos
- [ ] Plan automático para nuevos usuarios
- [ ] Notificaciones cuando saldo < 10 🪙
- [ ] Historial de cambios en costos
- [ ] Descuentos por volumen
- [ ] Auditoría de ajustes de créditos

---

## 📞 Soporte

Para errores o preguntas:

1. Revisar logs en: `temp/api_errors.log`
2. Verificar permisos de base de datos
3. Ejecutar nuevamente script SQL
4. Contactar a soporte

---

**Versión:** PREALTUM v4.0
**Fecha:** 2026-05-21
**Autor:** Sistema de Desarrollo