Ver el código de «Portal administracion de vFlow v01.04»

== Manual de usuario — VFlow (Portal de IA) ==

<blockquote>'''Versión de la aplicación:''' v01.04.09 · © 2026 MDtel</blockquote>
----

__TOC__


=== 1. Introducción ===

'''VFlow''' es el portal de administración y analítica de los agentes de IA de MDtel. Desde una única interfaz web permite:

* Consultar '''métricas de uso''' (tokens, peticiones, sesiones y tiempos de respuesta) por modelo y periodo.
* Revisar el '''historial de peticiones''' y el '''detalle de las conversaciones''' de cada sesión.
* Gestionar la '''base de conocimiento RAG''' (almacenes de documentos y loaders).
* Administrar los componentes del sistema: '''plataformas, agentes, orquestadores, usuarios''' y '''parámetros globales'''.
* Mantener '''objetos de datos estructurados''' (Metabase de datos).

El manual recorre todas las pantallas en el orden en el que aparecen en el menú lateral.

----

=== 2. Acceso a la aplicación (Login) ===

Al abrir <code>https://labvflow/vflow</code> la aplicación redirige a la pantalla de inicio de sesión.

[[File:00-login.png|800px|Pantalla de login de VFlow]]

'''Pasos para iniciar sesión:'''

# Introduce tu '''Usuario''' en el primer campo.
# Introduce tu '''Contraseña'''.
# Pulsa el botón '''Entrar'''.

<blockquote>El acceso está restringido a usuarios expresamente autorizados. Si las credenciales son incorrectas, la aplicación no permitirá el acceso y permanecerá en esta pantalla.</blockquote>

Una vez autenticado, se accede al '''Panel''' (dashboard) principal.

----

=== 3. Estructura general y menú de navegación ===

Tras iniciar sesión, la interfaz se organiza en dos zonas:

* '''Barra lateral izquierda:''' menú de navegación por iconos. Al pasar el ratón se muestra el nombre de cada sección.
* '''Área de contenido:''' muestra la pantalla de la sección seleccionada.

El menú lateral contiene las siguientes secciones (de arriba a abajo):

{| class="wikitable"
! Icono !! Sección !! Descripción
|-
| 📊 || '''Panel''' || Analítica y métricas de uso (dashboard).
|-
| 📋 || '''Peticiones''' || Historial de todas las peticiones realizadas.
|-
| 💬 || '''Sesiones''' || Historial de sesiones y detalle de conversaciones.
|-
| 🗄️ || '''Gestión RAG''' || Documentos y versiones de los almacenes RAG.
|-
| 🛡️ || '''Administración''' || Panel de administración de todos los componentes.
|-
| ⚙️ || '''Configuración''' || Ajustes de la interfaz (tema, idioma, etiquetas).
|-
| ⤺ || '''Salir''' || Cierra la sesión.
|}

En la esquina inferior izquierda se muestra siempre la '''versión''' de la aplicación (v01.04.09) y el aviso de copyright.

----

=== 4. Panel (Dashboard) ===

'''Ruta:''' <code>/vflow/dashboard</code>

Es la pantalla de inicio. Muestra el análisis y las métricas de uso del sistema.

[[File:01-dashboard.png|800px|Panel de VFlow (dashboard)]]

'''Elementos de la cabecera:'''

* '''Total de tokens''', '''Total de peticiones''' y '''Chats únicos''': contadores globales del periodo seleccionado.
* '''Gráficas''' (desplegable): permite mostrar/ocultar las gráficas disponibles.
* '''Periodo''' (desplegable): filtra todas las métricas por el rango de fechas elegido.
* '''+ Añadir gráfica''': abre el asistente para crear una gráfica personalizada (ver 4.1).

'''Gráficas incluidas por defecto:'''

* '''Tokens por Modelo''' — tabla con el total de tokens consumidos por cada modelo.
* '''Evolución de Peticiones''' — evolución temporal del número de peticiones.
* '''Peticiones por Modelo''' — comparativa de peticiones por modelo.
* '''Evolución de Tokens''' — evolución temporal del consumo de tokens.
* '''Llamadas LLM por Día''', '''Tiempo de respuesta por modelo (ms)''' y '''Peticiones por hora del día''' (más abajo en la página).

Cada gráfica dispone del botón '''⚙ Configuración de Gráficos''' y de una leyenda con los modelos, donde se puede quitar un modelo pulsando la '''✕''' de su etiqueta.

==== 4.1 Añadir una gráfica personalizada ====

Al pulsar '''+ Añadir gráfica''' se abre el asistente '''Crear gráfica personalizada''':

[[File:dlg-anadir-grafica.png|800px|Diálogo de creación de gráfica personalizada]]

Opciones de configuración:

* '''Nombre de la gráfica''': título que se mostrará.
* '''Fuente de datos''': origen de los datos (p. ej. ''Consumos (DAT_CONSUMOS)'').
* '''Agrupar por''': dimensión de agrupación (p. ej. ''Por Modelo'').
* '''Métrica''': valor a representar (p. ej. ''Número de llamadas'').
* '''Tipo de gráfica''': Barras, Horizontal, Línea, Área, Circular, Donut, KPI, Radar, Mapa de calor, Medidor, Histograma, Treemap o Dispersión.
* '''Color''', '''Estilo''' (mostrar leyenda, opacidad), rangos '''Y mínimo / Y máximo''' y '''Umbral de alerta'''.

A la derecha se muestra una '''Vista previa''' en tiempo real. Pulsa '''Guardar gráfica''' para añadirla al panel o '''Cancelar''' para descartar.

<blockquote>Nota: la creación de gráficas personalizadas puede estar limitada por rol (ver [[#8.5 Configuración del sistema|8.5 Configuración del sistema → Overrides por rol]]).</blockquote>

----

=== 5. Peticiones ===

'''Ruta:''' <code>/vflow/requests</code>

Muestra el '''Historial de Peticiones''': la lista completa de todas las peticiones realizadas al sistema.

[[File:02-peticiones.png|800px|Historial de Peticiones]]

'''Filtros (parte superior):'''

* '''Plataformas''', '''Agentes''', '''Orquestadores''': desplegables para filtrar por cada componente.
* '''Periodo''': filtra por rango de fechas.

'''Tabla de Peticiones:'''

* Campo de '''Búsqueda''' y selector de '''Registros por página''' (10 por defecto).
* Columnas: '''Message ID''', '''ID de sesión''', '''Fecha''', '''Pregunta''' y '''Respuesta'''.
* Indicador ''"Mostrando 1 a 10 de N resultados"'' y '''paginación''' en la parte inferior.

Es la vista de referencia para auditar de forma tabular qué se preguntó, cuándo y qué respondió el agente.

----

=== 6. Sesiones ===

'''Ruta:''' <code>/vflow/conversations</code>

Muestra el '''Historial de sesiones'''. Cada sesión agrupa los mensajes de una conversación.

[[File:03-sesiones.png|800px|Listado de Sesiones]]

'''Panel izquierdo (listado):'''

* Buscador '''"Buscar por ID de sesión o texto"'''.
* Botón '''Cargar más''' para paginar resultados.
* Cada tarjeta muestra: plataforma (p. ej. <code>omsui_1</code>), fecha/hora, '''agente''' e '''ID de sesión''', y el número de mensajes (<code>N msg</code>).
* Filtros superiores: '''Plataformas''', '''Agentes''', '''Orquestadores''', '''Sesiones''' y '''Periodo'''.

'''Panel derecho (detalle):''' al seleccionar una sesión se muestra la conversación completa en formato chat.

[[File:sesion-detalle.png|800px|Detalle de una sesión]]

En el detalle se ven, en orden cronológico, los mensajes del '''usuario''' (a la derecha) y las respuestas del '''agente''' (a la izquierda, con el nombre del agente), junto con la cabecera de la sesión (plataforma, agente e ID).

----

=== 7. Gestión RAG ===

'''Ruta:''' <code>/vflow/rag-management</code>

Permite gestionar los documentos del sistema '''RAG''' (Retrieval-Augmented Generation), organizados por almacén (''store'').

[[File:04-gestion-rag.png|800px|Gestión RAG]]

* Cada bloque corresponde a un '''RAG Store''' (p. ej. <code>ARA002</code>, <code>General</code>, <code>DS_ARA</code>) e indica su '''UUID''' y un estado ('''ACTUALIZADO''').
* Al expandir un store (flecha ▾) se muestran sus '''documentos/loaders'''. Para cada documento:
** Nombre del documento (p. ej. <code>ARA002_ld1</code>).
** '''Versión activa''' (etiqueta, p. ej. <code>v3</code>).
** Acciones: '''subir/actualizar''' (icono nube) y '''eliminar''' (icono papelera).

<blockquote>Esta pantalla es la vista operativa del contenido RAG. La definición de los stores y loaders se realiza en Administración (ver [[#8.6 RAG Stores|8.6]] y [[#8.7 RAG Loaders|8.7]]).</blockquote>

----

=== 8. Administración ===

'''Ruta:''' <code>/vflow/admin</code>

Panel central para administrar y configurar todos los componentes del sistema VFlow. Se presenta como una cuadrícula de tarjetas de acceso.

[[File:05-administracion.png|800px|Panel de administración de VFlow]]

Tarjetas disponibles:

{| class="wikitable"
! Tarjeta !! Función
|-
| '''Plataformas''' || Gestión de plataformas.
|-
| '''Agentes''' || Gestión de agentes.
|-
| '''Orquestadores''' || Gestión de orquestadores.
|-
| '''Usuarios''' || Gestión de usuarios.
|-
| '''Configuración del sistema''' || Parámetros y ajustes globales.
|-
| '''RAG Stores''' || Almacenes de documentos RAG.
|-
| '''RAG Loaders''' || Loaders de documentos RAG.
|-
| '''Metabase de datos''' || Objetos, campos y registros estructurados.
|}

<blockquote>Aviso mostrado en la propia pantalla: ''"Desde este panel puedes administrar todas las configuraciones críticas del sistema VFlow. Asegúrate de tener los permisos necesarios antes de realizar cambios."''</blockquote>

En todas las subpantallas de administración el botón '''← Volver''' regresa a este panel.

==== 8.1 Plataformas ====

'''Ruta:''' <code>/vflow/admin/plataformas</code>

Listado de plataformas conectadas (p. ej. VIVAit, OmniSuite).

[[File:adm-plataformas.png|800px|Listado de Plataformas]]

* Columnas: '''Nombre''', '''Identificador (UUID)''', '''Descripción''', '''Tipo''' (<code>vivait</code>, <code>omniSuite</code>…), '''Max Sesiones''' y '''Acciones''' (editar ✏️ / eliminar 🗑️).
* Botón '''+ Crear''' para dar de alta una plataforma.

'''Formulario de creación/edición:'''

[[File:dlg-plataforma.png|800px|Formulario de plataforma]]

Campos:

* '''Nombre''' ''(obligatorio)''.
* '''Tipo''' ''(obligatorio)'': selector de tipo de plataforma.
* '''Descripción'''.
* '''Max Sesiones Abiertas''', '''Max Peticiones Simultáneas''', '''Max Peticiones/Min/Sesión''': límites de capacidad.

Pulsa '''Guardar''' para confirmar o '''Cancelar''' para descartar.

==== 8.2 Agentes ====

'''Ruta:''' <code>/vflow/admin/agentes</code>

Gestión de los agentes de IA.

[[File:adm-agentes.png|800px|Listado de Agentes]]

* Columnas: '''Nombre''', '''Descripción''', '''Plataformas''', '''Orquestadores''', '''IDs entorno''' (PRO / PRE / PRU) y '''Acciones'''.
* Los '''IDs entorno''' muestran el identificador del agente en cada entorno: '''PRO''' (Producción), '''PRE''' (Preproducción) y '''PRU''' (Pruebas).
* Botón '''+ Nuevo Agente'''.

'''Formulario de agente:'''

[[File:dlg-agente.png|800px|Formulario de nuevo agente]]

Campos:

* '''Nombre''' ''(obligatorio)''.
* '''ID Agente Producción''' ''(obligatorio)'', '''ID Agente Preproducción''', '''ID Agente Pruebas''': identificadores del agente en cada entorno.
* '''Descripción'''.
* '''Plataformas''' ''(obligatorio)'' y '''Orquestadores''' ''(obligatorio)'': selección del componente asociado.
* '''Timeout Respuesta (ms)''': tiempo máximo de espera de respuesta (30000 por defecto).

Los campos marcados con <code>*</code> son obligatorios. Pulsa '''Guardar'''.

==== 8.3 Orquestadores ====

'''Ruta:''' <code>/vflow/admin/orquestadores</code>

Gestión de los orquestadores (motores que enrutan/ejecutan las peticiones, p. ej. ''Flowise'', ''Bucle'').

[[File:adm-orquestadores.png|800px|Listado de Orquestadores]]

* Columnas: '''Nombre''', '''Descripción''', '''Tipo''' (Bucle, Flowise…), '''URL Conexión''' y '''Acciones'''.
* Botón '''+ Crear'''.

'''Formulario de orquestador:'''

[[File:dlg-orquestador.png|800px|Formulario de orquestador]]

Campos:

* '''Nombre''' ''(obligatorio)'' y '''Tipo''' ''(obligatorio)''.
* '''URL Conexión''' ''(obligatorio)'': endpoint del orquestador.
* '''URL Proxy (opcional)''', '''URL RAG'''.
* '''Cadena de Autenticación''': Bearer token o API Key.
* '''Usuario (opcional)''' y '''Contraseña (opcional)'''.
* '''Descripción'''.

==== 8.4 Usuarios ====

'''Ruta:''' <code>/vflow/admin/usuarios</code>

Gestión de las cuentas de usuario de VFlow.

[[File:adm-usuarios.png|800px|Listado de Usuarios]]

* Columnas: '''Nombre''', '''Cuenta (login)''', '''Rol''' (Invitado, Usuario, Administrador), '''Activo''' y '''Acciones'''.
* Botón '''+ Crear'''.

'''Formulario de usuario:'''

[[File:dlg-usuario.png|800px|Formulario de usuario]]

Campos:

* '''Nombre''' ''(obligatorio)'', '''Primer Apellido''', '''Segundo Apellido'''.
* '''Email''' ''(obligatorio)'', '''Móvil''', '''Cuenta (login)''' ''(obligatorio)''.
* '''Contraseña''' ''(obligatorio)''.
* '''Rol''' ''(obligatorio)'': perfil de permisos.
* '''Modo de Login''': ''Local'' (u otros modos disponibles, p. ej. SSO).

==== 8.5 Configuración del sistema ====

'''Ruta:''' <code>/vflow/admin/configuracion</code>

Parámetros y ajustes globales del sistema. Está organizada en '''pestañas'''. Los cambios se confirman con el botón '''Guardar Configuración''' (abajo a la derecha).

'''Pestaña Monitorización''' — estado general e incidencias recientes del frontend:

[[File:adm-configuracion-sistema.png|800px|Configuración del sistema — Monitorización]]

Muestra tarjetas de estado: '''Estado''' (Backend disponible), '''Nivel de log''', '''Stores pendientes''', '''Histórico de sincronización''', '''Errores recientes''', '''Warnings recientes''' y '''Última comprobación'''. El botón '''Actualizar estado''' refresca los datos. Debajo se listan los ''stores pendientes'' de sincronización y el ''histórico de sincronización''.

<blockquote>Indicación en pantalla: los logs de frontend se ven en <code>F12 > Consola</code>; los del backend en <code>/opt/tomcat11/logs/catalina.out</code>.</blockquote>

'''Pestaña Tarificación:'''

[[File:cfg-tarificacion.png|800px|Configuración del sistema — Tarificación]]

* '''Peticiones por Bloque a Tarificar''' y '''Segundos por Bloque a Tarificar'''.

'''Pestaña Configuración runtime''' — se guarda en <code>vflow-config.json</code> y se aplica al refrescar la aplicación:

[[File:cfg-configuracion.png|800px|Configuración del sistema — Configuración runtime]]

* '''URL de la API backend''' (p. ej. <code>/vflow/api</code>): ruta que usa el frontend para llamar al backend.
* '''Tamaño de página de sesiones''': nº de sesiones por tanda en la pantalla de conversaciones.
* '''Nivel de log''': DEBUG muestra todo, ERROR solo fallos.
* '''Overrides por rol''': permite ajustar 2FA y la '''visibilidad del dashboard''' por perfil (Administrador, Invitado, Usuario), incluyendo qué gráficas ve cada rol y si puede crear gráficas personalizadas.

'''Pestaña Rutas de Archivos''' — configuradas en servidor, '''no editables''' desde la interfaz:

[[File:cfg-rutas.png|800px|Configuración del sistema — Rutas de Archivos]]

* '''Ruta de Documentos''' (p. ej. <code>/etc/MDtel/vFlow/Documentos/</code>).
* '''Ruta API Loader''' (p. ej. <code>/var/www/html/storages/</code>).

'''Pestaña Timeouts de Sesión (segundos):'''

[[File:cfg-timeouts.png|800px|Configuración del sistema — Timeouts de Sesión]]

* '''Dormir Sesión''', '''Sesión Voz''', '''Sesión Chat''' y '''Sesión Email''': tiempos de expiración por tipo de sesión.

==== 8.6 RAG Stores ====

'''Ruta:''' <code>/vflow/admin/rag-stores</code>

Gestión de los almacenes de documentos RAG.

[[File:adm-rag-stores.png|800px|Listado de RAG Stores]]

* Columnas: '''Nombre''', '''Descripción''', '''Plataformas''', '''ID Store Producción''', '''ID Store Preproducción''', '''ID Store Pruebas''' y '''Acciones'''.
* Botón '''+ Nuevo RAG Store'''.

'''Formulario de RAG Store:'''

[[File:dlg-ragstore.png|800px|Formulario de RAG Store]]

Campos:

* '''Nombre''' ''(obligatorio)'', '''Plataformas''' ''(obligatorio)'', '''Orquestadores''' ''(obligatorio)''.
* '''Descripción'''.
* '''ID Store Producción''' ''(obligatorio)'', '''ID Store Preproducción''', '''ID Store Pruebas''': identificadores del Document Store en cada entorno.

==== 8.7 RAG Loaders ====

'''Ruta:''' <code>/vflow/admin/rag-loaders</code>

Gestión de los ''loaders'' (cargadores de documentos) asociados a los RAG Stores.

[[File:adm-rag-loaders.png|800px|Listado de RAG Loaders]]

* Columnas: '''Nombre''', '''RAG Stores''', '''Interno (gestionado por VFlow)''', '''Configuración JSON''' y '''Acciones''' (eliminar).
* Botón '''+ Añadir loader'''.

'''Formulario de loader:'''

[[File:dlg-ragloader.png|800px|Formulario de añadir loader]]

Campos:

* '''Nombre''' ''(obligatorio)''.
* '''Descripción'''.
* '''Nombre del archivo''' ''(obligatorio)''.
* '''Seleccione un RAG Store''' ''(obligatorio)'': store al que se asocia.
* '''Contenido detectado del archivo base''': área de texto con el contenido.

Pulsa '''Crear''' para añadirlo.

==== 8.8 Metabase de datos ====

'''Ruta:''' <code>/vflow/metadata</code>

Gestión de '''objetos de datos estructurados''' (tablas de datos que puede usar el sistema: clientes, doctores, etc.).

[[File:adm-metabase.png|800px|Metabase de datos]]

* Cada tarjeta representa un '''objeto''' (p. ej. ''Clientes'', ''Doctores'') e indica su descripción, el '''JSON''' asociado y la '''Ruta'''.
* Acciones por objeto: '''Editar objeto''' (definición/estructura) y '''Editar/Ver datos''' (registros).
* Botones superiores: '''↻''' (refrescar) y '''+ Nuevo objeto'''.

'''Nuevo objeto / Editar objeto''' — define la estructura del objeto:

[[File:dlg-metaobjeto.png|800px|Diálogo de nuevo objeto]]

Campos:

* '''Nombre''' ''(obligatorio)'', '''Descripción'''.
* '''Nombre del JSON''' y '''Ruta de upload'''.
* '''Campos''': definición de los campos del objeto (botón '''+ Añadir campo''').
* A la derecha se muestra una vista previa del '''JSON''' resultante.

'''Editar/Ver datos''' — gestiona los registros del objeto:

[[File:meta-ver-datos.png|800px|Vista de datos de un objeto (registros)]]

* Tabla paginada con los registros y sus columnas (Id, Nombre, Fecha, Dirección, Localidad, Teléfono, Email, etc.).
* Acciones por fila: '''editar''' ✏️ y '''eliminar''' 🗑️.
* Botones superiores: '''← Volver''', '''↻''' refrescar, '''⤒ Importar''', '''Generar JSON''', '''Eliminar todo''' y '''+ Nuevo registro'''.

----

=== 9. Configuración de la interfaz ===

Al pulsar el icono '''⚙ Configuración''' de la barra lateral (parte inferior) se despliega un pequeño menú de ajustes de la interfaz:

[[File:menu-configuracion.png|800px|Menú de configuración de la interfaz]]

Opciones:

* '''Tema Claro / Oscuro''': interruptor para cambiar el aspecto visual.
* '''Idioma''': selector de idioma (p. ej. '''ES''').
* '''Etiquetas de navegación''': interruptor para mostrar u ocultar los textos junto a los iconos del menú lateral.

Estos ajustes afectan únicamente a la visualización de la interfaz para el usuario actual.

----

=== 10. Salir de la aplicación ===

Para cerrar la sesión, pulsa el icono '''⤺ Salir''' situado en la parte inferior de la barra lateral. La aplicación cerrará la sesión y volverá a la pantalla de [[#2. Acceso a la aplicación (Login)|Login]].

----

=== Anexo — Rutas de la aplicación ===

{| class="wikitable"
! Sección !! Ruta
|-
| Login || <code>/vflow/login</code>
|-
| Panel || <code>/vflow/dashboard</code>
|-
| Peticiones || <code>/vflow/requests</code>
|-
| Sesiones || <code>/vflow/conversations</code>
|-
| Gestión RAG || <code>/vflow/rag-management</code>
|-
| Administración || <code>/vflow/admin</code>
|-
| Plataformas || <code>/vflow/admin/plataformas</code>
|-
| Agentes || <code>/vflow/admin/agentes</code>
|-
| Orquestadores || <code>/vflow/admin/orquestadores</code>
|-
| Usuarios || <code>/vflow/admin/usuarios</code>
|-
| Configuración del sistema || <code>/vflow/admin/configuracion</code>
|-
| RAG Stores || <code>/vflow/admin/rag-stores</code>
|-
| RAG Loaders || <code>/vflow/admin/rag-loaders</code>
|-
| Metabase de datos || <code>/vflow/metadata</code>
|}

----

''Manual generado para su publicación en MediaWiki. Las imágenes se encuentran en la carpeta <code>img/</code>.''