Uso de la interfaz web del Agente Uful
Guía para el usuario del panel de control
Documento orientado al usuario final. Describe el propósito del agente y el uso de cada sección principal del panel de control.
Cabecera del panel
| Elemento | Significado |
|---|---|
| DEV / PROD | Entorno en el que está corriendo el agente (desarrollo o producción). |
| idle / running (u otro estado del planificador) | Si el planificador está en reposo o ejecutando trabajo. |
| Actualizado: … | Hora de la última actualización de estado mostrada en pantalla (se refresca de forma periódica). |
Cabecera del panel
Dashboard
Propósito: vista general rápida.
- Perfiles configurados: tarjetas con el identificador de cada perfil, número de estaciones, conexión de base de datos destino, modo de mapeo (por ejemplo
erp_rules), y el estado que reporta el planificador para ese perfil (por ejemplo sincronizado, en revisión o error). Si aplica, muestra el período actual que el agente está considerando. - Ejecuciones recientes: tabla resumida de las últimas sincronizaciones (mismo tipo de información que en la pestaña Ejecuciones, pero limitada en cantidad).
Uso: entra aquí para comprobar de un vistazo si los perfiles están activos y si hubo ejecuciones recientes sin abrir el detalle completo.
Dashboard
Ejecuciones
Propósito: historial detallado de sincronizaciones (runs).
- Filtro por perfil o todos los perfiles.
- Botón Actualizar para recargar la lista.
Columnas de la tabla
| Columna | Qué muestra |
|---|---|
| Run ID | Identificador único de la ejecución (en pantalla se acorta; el valor completo aparece al pasar el cursor). |
| Perfil | Perfil de configuración con el que se ejecutó la sincronización. |
| Período | Período contable o de cierre que se procesó (por ejemplo 2026-03-3). |
| Estado | Resultado global del run (por ejemplo success, failed, running). |
| Inicio | Fecha y hora local en que comenzó la ejecución. |
| Duración | Tiempo transcurrido en segundos (o — si no hay dato). |
| Tickets | Resumen numérico por tipo de resultado; ver símbolos abajo. |
| Error | Texto breve del fallo si lo hubo, o — si no hubo error. El mensaje completo suele mostrarse al pasar el cursor sobre la celda. |
Columna «Tickets»
En una sola celda verás cinco contadores juntos, en este orden:
| Símbolo | Significado |
|---|---|
| ✅ | Aplicados: tickets escritos correctamente en el destino según las reglas del perfil. |
| ⏭ | Omitidos: tickets que el agente no volvió a aplicar (por ejemplo ya procesados o fuera de alcance en esa corrida). |
| ⚠ | Conflicto: tickets donde hubo conflicto de negocio (p. ej. duplicado o política alert_only), sin tratarlos como error técnico fatal del run. |
| ❌ | Fallidos: tickets que no se pudieron aplicar por error al procesarlos. |
| 📋 | Sin coincidencia: tickets para los que no hubo fila o regla coincidente en el destino según la lógica del perfil (no_match). |
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 (p. ej.
ECONNREFUSED,timeout, descripción de la causa).
Uso: auditar qué se sincronizó, cuándo y con qué resultado; localizar errores o períodos problemáticos.
Ejecuciones
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 en el cuadro debajo del formulario.
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).
- Actualizar refresca la tabla.
Uso: disparar una corrida puntual (por ejemplo tras corregir datos en destino) y vigilar colas de reintento.
Reintentos
Reglas ERP
Propósito: definir y editar las reglas de integración que el agente aplica al escribir en el ERP, solo para perfiles cuyo modo de mapeo sea erp_rules.
Acceso y carga
- En Selecciona perfil erp_rules… elige un perfil (solo aparecen los que tienen
mappingModeerp_rules). - Pulsa Cargar para visualizar las reglas actualmente configuradas.
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.
Acceso a reglas ERP
Cabecera del archivo de reglas
Bloque superior del editor (Descripción del archivo de reglas + Archivo:).
| Componente | Función |
|---|---|
| Descripción del archivo de reglas | Texto libre que describe el conjunto de reglas (qué perfil o proceso cubren). Se guarda con el archivo. |
Archivo: ruta |
Ruta del archivo de reglas en el servidor (solo lectura informativa; indica dónde persisten los datos, p. ej. ./config/erpRules.json). |
Cabecera del archivo 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 tumatch.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.
Parámetros de binding
Cada regla (tarjeta)
Cada regla es una tarjeta numerada (#1, #2, …) con un cuerpo con varios bloques.
Encabezado de la tarjeta
| Elemento | Función |
|---|---|
| #N | Orden de la regla en la lista (la ejecución respeta el orden definido por el motor). |
| Nombre de la regla | Campo opcional con identificador técnico (p. ej. update_ticket_invoice_refs). Útil para documentar y localizar la regla en logs o revisiones. |
| ✕ | Elimina esta regla del conjunto (suele pedir confirmación). |
Descripción
Campo Descripción de esta regla: texto legible que explica en lenguaje natural qué hace la regla (para quien mantenga la configuración).
Tarjeta de regla — encabezado
match — Consulta de búsqueda
Primera fase: localizar la fila o el contexto en la base ERP antes de escribir.
| Campo | Función |
|---|---|
| SQL | Consulta SELECT que usa bindings (:stationId, :folio, etc.). Las columnas devueltas alimentan el resto de la regla (bindings dinámicos para idempotencia, conflicto y apply). |
expectsRow (casilla) |
Si está marcada, el match debe devolver al menos una fila; si no hay filas, se considera error según la política. Si no está marcada, «no hay fila» puede ser un caso válido. |
whenNoMatch (lista) |
Qué hacer cuando el SELECT no devuelve filas. Opciones: por defecto (si expectsRow es falso se puede continuar hacia apply tipo INSERT; si es verdadero, fallar), apply (seguir hacia idempotencia/apply, p. ej. INSERT), skip (omitir esta regla), fail (fallar la regla), alert (registrar no-match como inesperado, nivel advertencia en log), notify (registrar no-match como esperado, nivel informativo en log). |
Bloque match
idempotency — Saltar si ya existe
Evita volver a aplicar cambios cuando el dato «entrante» ya está reflejado en el resultado del match.
| Campo | Función |
|---|---|
skipIfFieldHasValue |
Nombre de columna del resultado del match (p. ej. existing_uuid). Si ese campo ya tiene valor, se omite la escritura (idempotencia). |
incomingFrom (opcional) |
Binding del valor entrante a comparar; si lo dejas vacío, por defecto se usa el concepto asociado a uuid del ticket. |
Idempotencia
conflict — Política de conflicto
Define qué pasa cuando el match indica que ya existe algo incompatible o duplicado según el campo que configures.
| Campo | Función |
|---|---|
| Campo de conflicto | Columna del resultado del match que se usa para detectar conflicto (p. ej. existing_uuid). |
| Política | alert_only: registra el conflicto en auditoría pero no bloquea el run. block: detiene el run y lo marca como fallido. |
Conflicto
apply — Pasos de escritura
Uno o más pasos numerados (Paso 1, Paso 2, …). Cada paso puede ser un UPDATE, INSERT, etc.
| Campo | Función |
|---|---|
| Paso N + ✕ | Identifica el paso y permite eliminarlo. |
| Condición (opcional) | Expresión en JavaScript evaluada con los bindings del match (ejemplos en la etiqueta: !id, !existing_uuid && id). Si la condición es falsa, ese paso no se ejecuta. Vacío = ejecutar siempre. |
| SQL | Sentencia que modifica datos (p. ej. UPDATE … SET uuid = :uuid WHERE id = :id). |
expectsAffected |
Validación de filas afectadas: sin validación, ≥1, =1, =0, ≥2. Ayuda a detectar errores silenciosos (p. ej. un UPDATE que no tocó ninguna fila cuando debía). |
+ Agregar paso añade otro bloque de paso dentro de la misma regla.
Apply — pasos de escritura
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).
Transaccional
Acciones globales del editor
| Botón | Función |
|---|---|
| + Agregar regla | Añade una regla nueva al final con valores por defecto (match vacío, idempotencia/conflicto con campos por rellenar, un paso apply inicial, etc.) y hace scroll hasta la nueva tarjeta. |
| Guardar | Envía al servidor el archivo de reglas (descripción global + todas las reglas editadas). El resultado (éxito o detalle del error) aparece brevemente en un cuadro bajo los botones. |
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: solo lectura — muestra la configuración efectiva que el agente tiene cargada (en formato JSON estructurado).
Sirve para verificar rutas, API, perfiles, planificador y demás parámetros tal como los ve el proceso en ejecución. No edita la configuración desde aquí; los cambios habituales se hacen en el archivo de configuración o en el flujo de despliegue que use tu organización.
Configuración