# Documentación Técnica: BotChatModel (PHP)

El `BotChatModel` dentro del namespace `App\Models\Bot` es el encargado de gestionar la persistencia y recuperación de las sesiones de chat. Actúa como el puente entre el usuario y un agente específico, garantizando que cada sesión sea única mediante identificadores universales.

---

## Estructura de la Entidad

Este modelo define los campos necesarios para rastrear el origen y la vigencia de una conversación.

### Atributos y Campos Permitidos (`$allowedFields`)

* **id_agente**: Referencia al asistente que está atendiendo la sesión.
* **uuid_sesion**: Identificador único generado por el cliente (front-end) para mantener la persistencia entre recargas de página.
* **interaction_id_externo**: Campo opcional para vincular la sesión con sistemas de terceros o APIs externas.
* **fecha_inicio**: Registro cronológico de la creación del chat.

---

## Métodos Destacados

### `getChatByUuid($uuidSesion, $agenteId)`

Este método implementa una lógica de **"obtener o crear"**:

1. Busca una sesión existente que coincida con el UUID y el ID del agente proporcionados.
2. Si no existe, inserta automáticamente un nuevo registro con la fecha actual.
3. Retorna siempre un arreglo con los datos de la sesión activa para ser procesada por el controlador.

---

## Configuración del Modelo

| Propiedad | Valor | Descripción |
| --- | --- | --- |
| `$table` | `bot_chats` | Tabla donde se almacenan las cabeceras de conversación. |
| `$primaryKey` | `id` | Identificador interno autoincremental. |
| `$returnType` | `array` | Formato de salida para los datos recuperados. |

---

## Ejemplo de Implementación

### Recuperación Automática de Sesión

El controlador utiliza este modelo para asegurar que los mensajes siempre tengan un contenedor válido:

```php
use App\Models\Bot\BotChatModel;

$botChatModel = new BotChatModel();

// El UUID viene del front-end (ej. LocalStorage)
$uuid = '550e8400-e29b-41d4-a716-446655440000';
$agenteId = 1;

// Si no existe, el modelo lo crea internamente
$chat = $botChatModel->getChatByUuid($uuid, $agenteId);

echo "ID de sesión interna: " . $chat['id'];

```

---

## Casos de Uso

### 1. Continuidad de la Conversación

Al utilizar el `uuid_sesion`, el usuario puede cerrar el navegador o perder la conexión momentáneamente. Al regresar, el sistema reconoce el UUID y recupera la misma fila en `bot_chats`, permitiendo que el modelo de mensajes cargue el historial previo sin interrupciones.

### 2. Trazabilidad Multi-Agente

Debido a que el método `getChatByUuid` filtra por `id_agente`, un mismo usuario (con un mismo UUID) puede tener conversaciones independientes y simultáneas con diferentes bots sin que los historiales se mezclen.

### 3. Auditoría de Sesiones

La `fecha_inicio` permite a los administradores del sistema identificar picos de tráfico y momentos de mayor demanda, facilitando la limpieza de registros antiguos o el análisis de la duración promedio de las interacciones.