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.
| 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
Propósito: vista general rápida.
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.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
Propósito: historial detallado de sincronizaciones (runs).
| 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. |
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). |
— (guión): no se registró mensaje de error para esa ejecución (típico en runs exitosos).Ejemplos del tipo de mensajes que pueden aparecer (el texto exacto depende del fallo real):
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
Propósito: dos funciones en la misma pantalla.
Permite forzar una sincronización sin esperar al ciclo automático del planificador.
Lista los trabajos que el agente reintentará tras fallos (perfil, período, estado, número de intentos, próximo intento, último error).
Uso: disparar una corrida puntual (por ejemplo tras corregir datos en destino) y vigilar colas de reintento.
Reintentos
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.
mappingMode erp_rules).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
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
Bloque 📋 Parámetros de Binding Disponibles con botón ▶ para expandir o contraer.
: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).match.sql.
Parámetros de binding
Cada regla es una tarjeta numerada (#1, #2, …) con un cuerpo con varios bloques.
| 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). |
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úsquedaPrimera 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 existeEvita 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 conflictoDefine 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 escrituraUno 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
transactionalCasilla transactional — envolver los pasos apply en una transacción.
Transaccional
| 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.
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