Documento orientado al usuario final. Describe el propósito del agente y el uso de cada sección principal del panel de control.

---

La interfaz web sirve para supervisar el estado del servicio, ver historial de ejecuciones, consultar auditoría por ticket, lanzar sincronizaciones manuales, revisar reintentos, descargar o enviar reportes, editar archivos de reglas ERP, gestionar múltiples perfiles y administrar la configuración (API Key, zona horaria, email de reportes, conexiones y perfiles) desde el panel.

---

Primer registro del administrador

Propósito: crear la cuenta inicial que protege el acceso al panel.

La primera vez que abres la interfaz web del agente —una vez completados la instalación y la configuración inicial del servicio— el sistema comprueba si ya existe algún usuario registrado. Si no hay ningún usuario, aparece un modal sobre el panel para registrar un primer usuario.

Formulario

Uso: define una cuenta segura para el responsable técnico o administrador que gestionará el agente. Los accesos posteriores se harán con la pantalla «Acceso al panel»; desde Configuración podrás dar de alta usuarios adicionales cuando lo necesites.

---

Navegación principal

En la navegación verás las opciones de:

1. Dashboard — resumen de perfiles y últimas ejecuciones.
2. Ejecuciones — historial de sincronizaciones con filtro por perfil y reportes PDF/email.
3. Reintentos — sync manual y cola de reintentos.
4. Auditoría — registro detallado por ticket (filtros y paginación).
5. Reglas ERP — editor de archivos de reglas de integración (varios archivos por despliegue).
6. Configuración — identificadores, API key, zona horaria, email de reportes, conexiones a BD, perfiles y usuarios del panel.

---

Cabecera del panel

---

Acceso al panel

Propósito: iniciar sesión en el panel con una cuenta ya registrada.

Una vez creado al menos un usuario del panel, cada visita a la interfaz web exige autenticación.

Formulario

Uso: accede con la cuenta que te hayan asignado. Si es la primera vez que usas el panel y aún no existe ningún usuario, verás en su lugar la pantalla «Crear primer usuario» descrita al inicio de esta guía.

---

Dashboard

Propósito: vista general rápida.

• Perfiles configurados: tarjetas con el nombre del perfil (si existe), el ID del perfil (clic para copiar), el número de estaciones, la conexión de base de datos destino (motor, host y base de datos; clic para copiar el ID de conexión), el archivo de reglas ERP asociado y el estado que reporta el planificador para ese perfil. Si aplica, muestra el período actual que el agente está considerando.
• Ejecuciones recientes: tabla resumida de las últimas 10 sincronizaciones (mismo tipo de información que en la pestaña Ejecuciones, pero con límite corto).
• Clic en una fila: abre la pestaña Auditoría con el mismo perfil y esa ejecución seleccionados, y lanza una búsqueda para ver los tickets de esa corrida. Es la forma más rápida de pasar del resumen del run al detalle por ticket.

Uso: comprobar de un vistazo si los perfiles están activos y si hubo ejecuciones recientes sin abrir el detalle completo.

---

Ejecuciones

Propósito: historial de sincronizaciones (runs).

• Filtro por perfil o todos los perfiles.
• Botón Actualizar para recargar la lista (hasta 50 ejecuciones en esta vista).
• Clic en una fila: abre la pestaña Auditoría con el mismo perfil y esa ejecución seleccionados, y lanza una búsqueda para ver los tickets de esa corrida. Es la forma más rápida de pasar del resumen del run al detalle por ticket.

Descripción de la tabla

Columna «Tickets» — significado de cada símbolo

En una sola celda verás cinco contadores juntos, en este orden:

Columna «Error» — qué verás

• — (guión): no se registró mensaje de error para esa ejecución (típico en runs exitosos).
• Texto truncado con «…»: el mensaje es más largo; el panel solo muestra un fragmento; el texto completo suele estar en el tooltip al dejar el cursor sobre la celda.

Ejemplos del tipo de mensajes que pueden aparecer (el texto exacto depende del fallo real):

• Errores de red o API hacia UFUL: tiempo de espera agotado, servicio no disponible, respuesta inesperada.
• Errores de base de datos destino: conexión rechazada, sintaxis SQL, violación de restricción, permisos insuficientes.
• Errores genéricos del proceso: mensaje de la excepción capturada durante la sincronización.

Uso: auditar qué se sincronizó, cuándo y con qué resultado; localizar errores o períodos problemáticos; saltar a Auditoría con un clic.

---

Reintentos

Propósito: dos funciones en la misma pantalla.

1. Ejecutar sync manual

Permite forzar una sincronización sin esperar al ciclo automático del planificador.

• Perfil: obligatorio.
• Period ID: opcional. Si lo dejas vacío, el agente usa el último período cerrado disponible según la configuración del perfil.
• Forzar re-sincronización: si está marcado, se vuelve a procesar aunque ese período ya estuviera marcado como sincronizado.
• Enviar reporte por email: si está marcado, al finalizar la corrida se envía el reporte al email configurado en Configuración → Email de reportes.
• Ejecutar: lanza la operación; el resultado (éxito o detalle del error) aparece debajo del formulario como JSON legible.

2. Reintentos pendientes

Lista los trabajos que el agente reintentará tras fallos (perfil, período, estado, número de intentos, próximo intento, último error).

• La columna Perfil muestra el identificador del perfil (UUID), no necesariamente el nombre.
• Actualizar refresca la tabla.

Uso: disparar una corrida puntual (por ejemplo tras corregir datos en destino) y vigilar colas de reintento.

---

Auditoría

Propósito: revisar ticket por ticket qué ocurrió en las sincronizaciones: acción aplicada, motivo, fechas y vínculo con la ejecución (run).

Cómo empezar

1. Elige un Perfil (obligatorio para buscar). Sin perfil, el panel te pedirá que selecciones uno.
2. Opcionalmente restringe por Ejecución (run). El desplegable muestra las ejecuciones recientes de ese perfil.
3. Ejecuciones en lista: controla cuántas ejecuciones recientes se muestran en el desplegable (útil si necesitas una ejecución antigua que no aparece con el valor por defecto).
4. Opcionalmente usa Filtros del ticket:
   • Period ID exacto o parcial según lo que envíe el servidor.
   • Estación y Folio: búsqueda por texto que contiene lo que escribas (según la API).
5. Resultados por página: tamaño de página para la tabla (valores habituales 50–500; el máximo puede estar limitado por la configuración del agente).
6. Pulsa Buscar.

También puedes llegar aquí desde Ejecuciones haciendo clic en una fila; el panel seleccionará perfil y run y ejecutará la búsqueda.

Paginación

Debajo de los filtros y de la tabla aparece un resumen del tipo «X–Y de Z», botones Anterior / Siguiente e indicación de página actual. Cambiar Resultados por página con un perfil ya seleccionado puede relanzar la búsqueda desde la primera página.

Descripción de la tabla de auditoría

Detalle de un ticket

Haz clic en una fila para abrir Detalle del ticket. Ahí verás, entre otros datos, el nombre del perfil, período, run completo, estación, folio, fechas y la razón completa. Junto a la acción aparece una leyenda en español (por ejemplo: aplicado correctamente, omitido, conflicto, error, sin coincidencia).

Cierra el modal con Cerrar, clic fuera del cuadro o la tecla Escape.

Uso: investigar discrepancias entre UFUL y el destino, entender por qué un ticket fue omitido o marcado en conflicto, y cruzar información con el run y el período.

---

Reglas ERP

Propósito: definir y editar los archivos de reglas de integración que el agente aplica al escribir en la base de datos del cliente. Cada perfil referencia un archivo de reglas por su identificador.

Acceso y selección de archivo

1. En Selecciona archivo de reglas… elige uno de los archivos disponibles en el servidor.
2. Pulsa Cargar para abrirlo en el editor.
3. Para crear un archivo nuevo sin partir de uno existente, pulsa Crear (el identificador se asignará al guardar por primera vez).

Si aún no has cargado ni creado un archivo, verás el mensaje: «Selecciona un archivo de reglas para editarlo o crea uno nuevo con el botón Crear.»

Al cambiar de archivo o pulsar Crear con cambios sin guardar, el panel muestra un aviso «Cambios sin guardar» para confirmar si deseas descartarlos.

Cabecera del archivo de reglas

Bloque superior del editor (Nombre del archivo de reglas, Descripción del archivo de reglas e ID de reglas).

Parámetros de Binding disponibles

Bloque 📋 Parámetros de Binding Disponibles con botón ▶ / ▼ para expandir o contraer.

• Qué es: referencia integrada en la propia pantalla: lista de placeholders (:stationId, :folio, :uuid, etc.) que puedes usar en las sentencias SQL de match y apply, más columnas devueltas por tu match.sql (bindings dinámicos).
• Secciones típicas: bindings base (estación, folio, UUID, facturación), payload (litros, monto, tipo de combustible), datos anidados de emisor y receptor, y una nota sobre campos extra que devuelve match.sql.
• Uso: consúltalo al escribir SQL para no inventar nombres de parámetros; deben coincidir con lo que el motor de reglas sustituye en tiempo de ejecución.

Cada regla (tarjeta)

Cada regla es una tarjeta numerada (#1, #2, …) con varios bloques.

Encabezado de la tarjeta

Descripción

Campo Descripción con texto legible que explica qué hace la regla (para quien mantenga la configuración).

match — Consulta de búsqueda

Primera fase: localizar la fila o el contexto en la base ERP antes de escribir.

Reglas de idempotencia (y política de conflicto)

Estas reglas indican al agente cómo actuar al validar si un campo específico tiene o no un valor registrado en la tabla del cliente.

Si el campo está vacío o si el valor coincide con el valor entrante, la regla se considera válida y no falla.

En cambio, si el campo en la tabla del cliente contiene un valor y este es diferente al valor entrante, la regla falla y se aplica la política correspondiente.

Esto evita que el agente realice cambios no deseados en campos donde el cliente ya cuenta con datos previamente establecidos.

Aunque todo dependerá de los campos a modificar definidos en la regla de aplicación (apply).

La regla de idempotencia y la política ante conflicto se configuran como una o más sub-reglas dentro del bloque Reglas de idempotencia.

Para cada regla de idempotencia puedes definir:

Puedes añadir varias reglas con + Agregar regla de idempotencia y eliminar cada una con ✕.

apply — Pasos de escritura

En esta sección se define la consulta de escritura que el agente ejecutará para aplicar los datos de cada ticket recibido.

Además, aquí también se pueden configurar los parámetros de enlace (binding params) para utilizar los valores de los tickets provenientes de UFUL.

+ Agregar paso añade otro bloque de paso dentro de la misma regla.

transactional

Casilla transactional — envolver los pasos apply en una transacción.

• Si está marcada, los pasos de apply de esa regla se ejecutan en una sola transacción de base de datos: o todo se confirma o todo se revierte ante error.
• Si está desmarcada, el comportamiento depende del motor (pasos sin envoltura transaccional única).

Acciones globales del editor

Uso: mantener uno o varios conjuntos de reglas reutilizables, asignarlos a distintos perfiles desde Configuración → Perfiles, y ajustar SQL, validaciones e idempotencia sin editar JSON en disco manualmente.

---

Configuración

Propósito: consultar identificadores del despliegue y editar parámetros clave del agente desde el panel (API key, zona horaria, email de reportes, conexiones a base de datos, perfiles y usuarios del panel).

Encabezado

API Key

• Campo para ver o reemplazar la API Key (se muestra enmascarada por defecto; botón Mostrar / Ocultar).
• Test: valida la clave contra el servicio antes de guardar.
• Guardar: persiste la clave. Si cambiaste el valor y no has validado con Test, el flujo puede ejecutar la validación automáticamente antes de guardar.

Zona horaria

• Selector TimeZone con zonas disponibles en el servidor.
• Guardar aplica la zona horaria a la configuración de la API.

Email de reportes

• Campo Email con la dirección a la que se enviarán los reportes de ejecución (PDF).
• Guardar persiste el valor.
• Si no hay email configurado, el envío por correo fallará hasta que lo definas aquí.

Conexiones de base de datos

• Listado de conexiones disponibles para el agente (mssql, mysql2, pg).
• + Nueva conexión abre un formulario (modal) para alta.
• Editar y Eliminar en cada tarjeta. Al eliminar se pide confirmación.
• En el modal puedes usar Test conexión antes de Guardar. Tras un cambio de datos, suele ser necesario probar de nuevo la conexión antes de persistir.
• Opciones específicas de SQL Server (cifrado, certificado) aparecen cuando el cliente es mssql.

Perfiles

El agente puede operar con varios perfiles en paralelo. Cada perfil define su propia conexión de BD, archivo de reglas ERP y conjunto de estaciones. No existe un «perfil activo» global: en otras pestañas eliges el perfil al filtrar o al ejecutar sync manual.

• Listado en tarjetas con nombre, ID, conexión asociada, archivo de reglas ERP, número de estaciones y vista resumida de estaciones (hasta cinco chips visibles; si hay más, aparece +N más).
• + Nuevo perfil abre el modal de alta.
• Editar y Eliminar (✕) por perfil. Al eliminar se pide confirmación.
• Siempre debe quedar al menos un perfil configurado; no se puede eliminar el último.

Modal «Nuevo perfil» / «Editar perfil»

Restricciones al guardar:

• No se permiten dos perfiles con la misma conexión de BD, el mismo archivo de reglas y al menos una estación en común (evita duplicar el mismo alcance operativo).
• Si cambias la API Key del agente, las estaciones disponibles se actualizan al abrir el modal; conviene revisar la selección de estaciones de cada perfil tras un cambio de clave.

Usuarios del panel

Propósito: gestionar las cuentas de acceso al panel y asignar el rol de cada una.

Esta sección solo es visible para usuarios con rol admin. Los permisos efectivos los calcula el servidor según el rol; no se pueden definir permisos personalizados por usuario.

Listado de usuarios

Tabla con las cuentas registradas:

Nuevo usuario

Formulario para dar de alta otra cuenta:

Roles y acceso en el panel

Cada rol tiene un conjunto fijo de permisos. La interfaz oculta pestañas y acciones que tu rol no permite; el servidor también rechaza operaciones no autorizadas aunque se intenten por API.

Uso: operar el agente sin acceder al servidor solo por terminal: rotar API key, alinear zona horaria, configurar destino de reportes, añadir o corregir conexiones, crear y mantener varios perfiles y gestionar usuarios del panel (solo administradores). Para delegar acceso, asigna viewer a perfiles de consulta, operator a operación diaria y admin únicamente a quien deba modificar la configuración o las cuentas.