Workflow Ledger

El registro de trazabilidad de flujos de trabajo guarda estado duradero para automatizaciones de larga duración. Responde preguntas operativas que un log de consola no puede responder de forma fiable:

• ¿Qué ejecución está activa?
• ¿Qué elementos están en cola, en ejecución, completados, omitidos, listos para reintento, cancelados, fallidos o muertos?
• ¿Qué elemento tiene una reserva caducada?
• ¿Qué historial de eventos llevó al estado actual?
• ¿Qué elemento de cola está vinculado a este elemento del flujo?
• ¿Puede reintentarse, ponerse de nuevo en cola, cancelarse o enviarse a la cola de rechazos?

Conceptos del registro

Concepto	Significado
Run	Una ejecución de un flujo de trabajo, con estado, origen, marcas de inicio/fin, metadatos y estado de error
Item	Una unidad de trabajo duradera, como un portal, URL, documento o registro
Stage	El paso del flujo al que pertenece el elemento, como discovery, fetch, parse o review
State	El estado del elemento dentro de su etapa, como queued, running, completed, retry-ready, dead o cancelled
Event	Entrada de historial de solo agregado que explica qué ocurrió con una ejecución o un elemento
Resultado vinculado	Salida o referencia vinculada, como una instantánea, listado, archivo o documento de búsqueda
Lease	Toma de posesión de un proceso de trabajo que marca un elemento como en ejecución hasta un plazo

Los estados y etapas son cadenas definidas por el flujo, no conceptos rígidos del producto. El registro es suficientemente genérico para muchos flujos, mientras que cada flujo puede aportar metadatos de presentación para hacer legibles sus elementos.

Panel Workflow Ledger

El panel Workflow Ledger de la ventana principal es una superficie compacta de estado y lanzamiento. Muestra contadores de ejecuciones, contadores de elementos, contadores de atención y una lista breve de ejecuciones.

El panel es deliberadamente ligero. Úselo para comprobar estado y abrir la consola completa.

Workflow Ledger Console

La Workflow Ledger Console es la interfaz principal del operador. Se abre en su propia ventana y usa paneles dedicados para ejecuciones, elementos de la ejecución seleccionada, detalles de elemento, eventos, resultados vinculados, metadatos, estado de recuperación y vistas de grafo/depuración.

La consola sirve para gestión seria de ejecuciones y recuperación de elementos, no solo para observar logs.

Úsela para:

• Gestionar ejecuciones e inspeccionar el estado de la ejecución seleccionada.
• Buscar y filtrar elementos por texto y estado operativo.
• Paginar conjuntos grandes de elementos sin cargar toda una ejecución en la interfaz.
• Leer conteos de etapa/estado calculados sobre toda la ejecución seleccionada, no solo sobre la página visible.
• Seleccionar uno o varios elementos para reintento, cancelación, envío a rechazos o recuperación de cola.
• Inspeccionar detalles de elemento, IDs brutos, claves de elemento, intentos, estado de reserva, errores y metadatos.
• Seguir líneas temporales de elementos mediante eventos y resultados vinculados.
• Ver si un elemento del registro tiene suficientes metadatos de cola para volver a ponerse en cola.
• Copiar contenidos, IDs y detalles diagnósticos de elementos.

Ejecuciones grandes y paginación

La consola está diseñada para ejecuciones con miles de elementos. El panel Items usa paginación del lado servidor con tamaños de página acotados, mientras que los resúmenes y la matriz etapa/estado usan consultas agregadas del repositorio sobre toda la ejecución seleccionada.

La distinción importa: la virtualización solo controla el renderizado, mientras que la paginación y los agregados controlan la corrección y la carga de base de datos. Una página puede mostrar 250 filas, pero los totales de ejecución, conteos etapa/estado, elementos listos para reintento, reservas y resúmenes de atención se calculan desde la verdad del repositorio.

Los filtros rápidos como Problems, Retry Ready, Running, Leased y Terminal se aplican del lado servidor para la lista paginada.

Vocabulario de reintento

Guida separa el estado duradero del registro del trabajo ejecutable de la cola:

• Mark Retry Ready cambia el estado del registro para que el elemento sea reclamable por la lógica del flujo. No crea trabajo de cola por sí mismo.
• Requeue and Retry crea trabajo ejecutable en cola cuando el elemento del registro tiene metadatos de cola registrados, y luego devuelve el elemento del registro a un estado reclamable.

Si faltan metadatos de cola, Guida debe mostrar un mensaje de recuperación orientado al operador. La solución habitual es regenerar el elemento volviendo a ejecutar el proceso de origen o poniendo en cola un elemento corregido, no adivinar el contenido antiguo.

Enlace con colas

Los elementos de cola pueden incluir una envoltura de flujo:

{
  "workflow": {
    "workflowName": "careers-crawl",
    "runId": "abc123",
    "itemId": "def456",
    "itemKey": "portal:example"
  }
}

Cuando estos metadatos están presentes, la Queue Console puede abrir el elemento de registro relacionado, y la Workflow Ledger Console puede explicar si existe trabajo ejecutable en cola para ese elemento.

Metadatos de presentación

Los flujos pueden definir la presentación de elementos con workflow-ledger.display.json junto a workflow-ledger.schema.json. Las reglas de presentación permiten que un flujo elija etiquetas, subtítulos y campos de contexto desde campos o metadatos del elemento sin codificar una interfaz específica del dominio en Guida.

La clave bruta de elemento, el ID de elemento, el ID de ejecución, los metadatos, eventos y resultados vinculados siguen disponibles en detalles y acciones de copia incluso cuando un flujo aporta etiquetas legibles.

Atención y recuperación

La consola expone atención para la ejecución seleccionada, como:

• reservas caducadas
• elementos listos para reintento
• elementos muertos o fallidos
• problemas de enlace con colas
• elementos que no pueden volver a ponerse en cola automáticamente

La atención entre ejecuciones pertenece a vistas de gestión de ejecuciones. La operación sobre una ejecución seleccionada debe permanecer limitada a esa ejecución para que el operador no se distraiga con fallos no relacionados.

Reconciliación de ejecución

Las herramientas MCP del Workflow Ledger y la API del panel operativo incluyen resúmenes compactos de reconciliación para una ejecución seleccionada. Son útiles para comprobaciones de canalización, como el traspaso de fetch a parse:

• conteos de fetch procesado, omitido, muerto, listo para reintento, en ejecución y reservado
• conteos de parse/index en cola y completados
• conteos completos agrupados por etapa/estado

Estos resúmenes están pensados para diagnóstico operativo y agentes remotos. No sustituyen la consola, pero dan a scripts y clientes MCP una forma acotada de responder “¿adónde fue el trabajo?”.

Para espacios de trabajo con muchos flujos de crawling, use la Workflow Control Console para agrupar etapas del registro, colas, módulos y traspasos en operaciones de nivel operador. Use la Workflow Ledger Console cuando necesite la verdad detallada de los elementos detrás de una de esas filas de operación.

Siguientes pasos

• Colas y revisión — operar trabajo ejecutable en cola
• Procesos de trabajo de cola — ejecutar procesos respaldados por colas
• Workflow Control Console — modelar operaciones, mapas de flujo, módulos y traspasos
• API del panel operativo — monitorizar conteos de ejecución, colas, procesos, fallos, atención y reconciliación mediante HTTP/SSE en sola lectura
• Flujos de trabajo — organizar la automatización del espacio de trabajo en carpetas de flujo