# Documentación Técnica: Sistema de Resolución de Variables Dinámicas

Este sistema permite que el conocimiento estático del bot se convierta en información dinámica y actualizada en tiempo real. Utiliza un motor de inyección de "shortcodes" que detecta etiquetas especiales en el texto y las reemplaza con datos provenientes de bases de datos o servicios externos mediante clases especializadas llamadas **Resolvers**.

---

## 1. Clase Principal: VariableResolver

La clase `VariableResolver` es el motor de búsqueda y reemplazo. Su función es escanear los fragmentos de conocimiento seleccionados por la IA en busca de etiquetas con el formato `{{shortcode}}` y ejecutar la lógica necesaria para llenarlos con datos reales.

### Flujo de Trabajo

1. **Escaneo**: Analiza el `contenido_respuesta` de todos los fragmentos de conocimiento en busca de patrones `{{...}}`.
2. **Consulta de Definiciones**: Busca en la tabla `bot_variables_sistema` qué clase y qué método deben procesar cada shortcode encontrado.
3. **Ejecución Dinámica**: Instancia la clase definida y ejecuta el método correspondiente para obtener el valor final.
4. **Inyección**: Reemplaza el shortcode original por el resultado obtenido en el texto que finalmente leerá el modelo de IA.

---

## 2. Estructura de un Resolver (Ejemplo: ContactoResolver)

Un **Resolver** es una clase diseñada para obtener datos específicos. El `ContactoResolver` es un ejemplo que transforma un ID de contacto en un "badge" de Markdown con enlaces directos a correos y WhatsApp.

### Componentes Clave:

* **Acceso a Datos**: Uso de `$this->db` para consultar tablas específicas (como `bot_agenda_contactos`).
* **Formateo**: Los métodos deben retornar texto (preferiblemente Markdown) para que la IA pueda renderizarlo correctamente en la interfaz de chat.
* **Métodos Públicos**: Cada shortcode en la base de datos debe apuntar a un método público dentro de estas clases.

---

## 3. Guía: Cómo crear nuevos Resolvers

Para implementar nuevas funcionalidades dinámicas (por ejemplo, consultar el saldo de un estudiante o la disponibilidad de un aula), siga estos pasos:

### Paso A: Crear la Clase Resolver

Cree un nuevo archivo en `app/Libraries/Resolvers/`. La clase debe ser modular y enfocada en una única responsabilidad.

```php
namespace App\Libraries\Resolvers;

class AcademicoResolver 
{
    public function getFechaExamen() 
    {
        // Lógica para consultar la fecha de un examen en la DB
        return "15 de Octubre de 2026";
    }
}

```

### Paso B: Registrar en la Base de Datos

Para que el `VariableResolver` reconozca el nuevo shortcode, debe insertar un registro en la tabla `bot_variables_sistema`:

| Campo | Valor de ejemplo |
| --- | --- |
| **shortcode** | `{{fecha_examen}}` |
| **clase_resolver** | `App\Libraries\Resolvers\AcademicoResolver` |
| **metodo_resolver** | `getFechaExamen` |
| **type_dato** | `Texto` |

### Paso C: Uso en el Conocimiento

Simplemente incluya el shortcode en cualquier registro de la tabla `bot_agente_conocimiento`:

> "La fecha del próximo examen parcial es {{fecha_examen}}. Recuerda estudiar con tiempo."

---

## Casos de Uso Potenciales

### 1. Información de Contacto en Tiempo Real

En lugar de escribir el número de teléfono en 50 registros de conocimiento, se usa `{{contacto_pagos}}`. Si el número cambia, solo se actualiza en la tabla de agenda y todos los bots se actualizan automáticamente.

### 2. Consultas Personalizadas

Si se pasa el ID del usuario a la sesión, un Resolver podría buscar datos privados como:

* `{{estudiante_deuda}}`: Consulta el saldo pendiente.
* `{{estado_solicitud}}`: Indica el estatus de un trámite administrativo.

### 3. Datos de Contexto Global

* `{{dolar_dia}}`: Obtiene la tasa de cambio actual desde una API externa.
* `{{eventos_hoy}}`: Lista los eventos del calendario institucional del día actual.