# Reestructuración del Asistente IA

## Inventario encontrado

Antes de la unificación convivían estas superficies visibles:

- panel de análisis estructurado del agente dentro del ticket;
- chat contextual del ticket;
- panel heredado de resumen, conversación, SLA, similares, conocimiento y
  generación de respuesta;
- flujo separado «IA rápida» para crear un ticket desde texto;
- generación de borradores de artículos desde un ticket;
- diagnóstico técnico del proveedor.

En backend existen `IaController`, `TicketsAiAgentModel`,
`TicketsAiToolsModel`, `TicketsAiChatModel`, `TicketsAiAuditModel`,
`TicketsAiModel`, `AssistantSchemaModel`, `AssistantQueryModel`,
`TicketsAiReportsModel` y el proveedor central `AiClient`. Las llamadas HTTP a
Ollama/API ya están centralizadas en `AiClient`; no hay llamadas al proveedor
desde vistas ni controladores.

## Experiencia resultante

La navegación funcional expone **Asistente IA**. Dentro de un ticket se muestra
el mismo componente visual con el contexto del caso cargado por el servidor.
Las tres superficies anteriores del ticket quedan unificadas en una
conversación continua. El editor conserva una capacidad puntual
**Mejorar con IA**, integrada al flujo de respuesta.

La pantalla global incluye un historial lateral por usuario. Cada conversación
cerrada conserva su título derivado de la primera pregunta, vista previa,
fecha, cantidad de mensajes y todos sus turnos. Los hilos anteriores se abren
en modo de solo lectura para que una respuesta nueva nunca termine en una
conversación distinta de la actual.

El flujo de creación asistida conserva su funcionalidad, pero se presenta como
**Crear desde texto**, no como otro módulo de IA. El diagnóstico permanece en
Administración porque es una función técnica, no una herramienta de trabajo.

## Arquitectura

```text
Componente Asistente IA (_assistant.php)
                ↓
IaController::responderAsistente()
                ↓
TicketsAiAgentModel::responderAsistente()
                ↓
contexto global o contexto de ticket
                ↓
registro cerrado de TicketsAiToolsModel
                ↓
AiClient (Ollama/API)
                ↓
respuesta + historial + auditoría
```

Las rutas `chat` y `consultar` se conservan como contratos compatibles, pero
delegan en un único manejador. El agente selecciona herramientas según el
ámbito (`ticket`, `global` o `ambos`) y los permisos reales del usuario.

## Funcionalidad conservada

- análisis estructurado y sus registros históricos;
- resumen y generación de borradores heredados;
- búsqueda de casos similares y base de conocimiento;
- consulta de catálogos, técnicos e historial del solicitante;
- búsqueda global de casos e indicadores de mesa;
- clasificación de correo, creación desde texto y borradores de artículos;
- diagnóstico, auditoría, límites de uso y proveedor local Ollama/API.

Los flujos heredados que duplicaban interfaz ya no se muestran, pero sus datos,
servicios y endpoints no se eliminan.

El análisis estructurado existente se reutiliza mediante la herramienta interna
`analizar_caso`, por lo que una petición natural como «analiza este caso» sigue
ejecutando esa capacidad sin exponer un botón o panel independiente.

## Esquema y funcionamiento del sistema

El esquema no se inyecta completo en cada prompt. Eso desperdiciaría contexto
y quedaría obsoleto al aplicar una migración. `AssistantSchemaModel` consulta
la base activa bajo demanda y ofrece inventario total, búsqueda por concepto y
detalle de una tabla. Incluye tipos, nulabilidad, llaves, índices y relaciones;
marca campos potencialmente sensibles y jamás devuelve valores almacenados.

El conocimiento de «cómo funciona» complementa esos metadatos con un mapa
funcional de tickets, SLA, usuarios/permisos, conocimiento, automatización,
reportes e IA, además del registro real de módulos habilitados.

## Reportes, gráficas y exportaciones

`TicketsAiReportsModel` ofrece un catálogo cerrado de reportes: `resumen`,
`tendencia`, `estados`, `prioridades`, `categorias`, `agentes`, `sla` y
`tickets`. Reutiliza `TicketsModel::getAnalyticsDashboard` y `ReportesModel`,
de modo que los artefactos publicados salen siempre de la analítica existente y
no de SQL improvisado por el modelo.

Lo que ningún reporte cerrado alcanza —un listado a medida, un filtro, un cruce
entre tablas— se resuelve con `consultar_datos`, la única herramienta que acepta
SQL redactado por el modelo. Está acotada a lectura por tres barreras
independientes (sintáctica, transacción `READ ONLY` en conexión propia y
enmascarado de columnas sensibles en la salida); el detalle está en
`docs/05_OPERATIONS.md` y la implementación en `AssistantQueryModel`.

Una respuesta puede transportar artefactos tipados (`indicadores`, `grafica`,
`tabla` y `descarga`). Se guardan junto con el mensaje, reaparecen al recargar
la conversación y se renderizan sin insertar HTML procedente del modelo.

Las exportaciones se reconstruyen en un endpoint autenticado con tipos y
filtros validados; no se crean archivos temporales ni se aceptan rutas, tablas
o columnas desde la URL. El CSV usa UTF-8 y conserva los límites del exportador
existente. La acción `Ia.exportar` se concede a los mismos roles que ya tienen
`Ia.asistente`.