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, editar reglas ERP y gestionar la configuración (API Key, zona horaria, 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.
3. Reintentos — sync manual y cola de reintentos.
4. Auditoría — registro detallado por ticket (filtros y paginación).
5. Reglas ERP — editor de reglas para perfiles en modo erp_rules.
6. Configuración — identificadores, API key, zona horaria, conexiones a BD y perfiles.

---

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, el número de estaciones, el identificador de la conexión de base de datos destino, el modo de mapeo (por ejemplo bridge_table o erp_rules) 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.
• 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 las reglas de integración que el agente aplica al escribir en el base de datos, solo para perfiles cuyo modo de mapeo sea erp_rules.

Acceso y carga

1. En Selecciona perfil erp_rules… elige un perfil (solo aparecen los que tienen mappingMode erp_rules).
2. Pulsa Cargar para traer las reglas desde el servidor.

Si aún no has elegido perfil o no hay reglas cargadas, verás un mensaje indicando que debes seleccionar un perfil con modo erp_rules. Tras cargar correctamente, se muestra el editor completo.

Cabecera del archivo de reglas

Bloque superior del editor (Descripción del archivo de reglas + Archivo:).

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: ajustar cómo se buscan, validan y escriben los tickets en el ERP desde el panel, sin editar a mano el JSON en disco salvo que tu proceso lo requiera; los cambios efectivos dependen de permisos y de cómo esté desplegado el agente.

---

Configuración

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

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.

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

• Listado en tarjetas con nombre, ID, conexión asociada, modo de mapeo, número de estaciones y vista resumida de estaciones.
• Editar y Eliminar por perfil.
• El modal de Editar perfil permite ajustar nombre, conexión de BD y estaciones asociadas.

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, añadir o corregir conexiones, revisar 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.