Registre de traçabilité des flux de travail

Le registre de traçabilité des flux de travail enregistre l’état durable des automatisations longues. Il répond à des questions opérationnelles qu’un journal de console ne peut pas traiter de façon fiable :

• Quelle exécution est active ?
• Quels éléments sont en file, en cours, terminés, ignorés, prêts à être réessayés, annulés, en échec ou dans la file des rejets ?
• Quel élément a une prise en charge expirée ?
• Quel historique d’événements a mené à l’état actuel ?
• Quel élément de file est lié à cet élément de flux ?
• Cet élément peut-il être réessayé, remis en file, annulé ou envoyé vers la file des rejets ?

Concepts du registre

Concept	Signification
Exécution	Une exécution d’un flux de travail, avec statut, source, horodatages de début/fin, métadonnées et état d’erreur
Élément	Une unité durable de travail du flux, comme un portail, une URL, un document ou un enregistrement
Étape	L’étape du flux à laquelle l’élément appartient, comme découverte, récupération, analyse ou révision
État	Le statut de l’élément dans son étape, comme en file, en cours, terminé, prêt à réessayer, rejeté ou annulé
Événement	Une entrée d’historique append-only expliquant ce qui est arrivé à une exécution ou à un élément
Résultat lié	Une sortie ou référence liée, comme un instantané, une liste, un fichier ou un document de recherche
Prise en charge	Réservation par un processus de travail qui marque un élément comme en cours jusqu’à une échéance

Les états et les étapes sont des chaînes définies par le flux de travail, pas des concepts produit codés en dur. Le registre est assez générique pour plusieurs types de flux, tout en permettant à chaque flux de fournir des métadonnées d’affichage pour rendre les éléments lisibles.

Panneau Workflow Ledger

Le panneau Workflow Ledger de la fenêtre principale est une surface compacte d’état et de lancement. Il affiche les compteurs d’exécutions, les compteurs d’éléments, les compteurs d’attention et une courte liste d’exécutions.

Le panneau est volontairement léger. Utilisez-le pour vérifier l’état et ouvrir la console complète.

Workflow Ledger Console

La Workflow Ledger Console est l’interface opérateur principale. Elle s’ouvre dans sa propre fenêtre et utilise des panneaux dédiés pour les exécutions, les éléments de l’exécution sélectionnée, les détails d’élément, les événements, les résultats liés, les métadonnées, l’état de récupération et les vues graphes/débogage.

La console sert à gérer sérieusement les exécutions et la récupération d’éléments, pas seulement à observer des journaux.

Utilisez-la pour :

• Gérer les exécutions et inspecter l’état de l’exécution sélectionnée.
• Rechercher et filtrer les éléments par texte et statut opérationnel.
• Parcourir de grands ensembles d’éléments sans charger toute une exécution dans l’interface.
• Lire les compteurs étape/état calculés sur toute l’exécution sélectionnée, pas seulement sur la page visible.
• Sélectionner un ou plusieurs éléments pour réessai, annulation, envoi vers la file des rejets ou récupération de file.
• Inspecter les détails d’élément, IDs bruts, clés, tentatives, état de prise en charge, erreurs et métadonnées.
• Suivre la chronologie d’un élément via événements et résultats liés.
• Voir si un élément du registre a assez de métadonnées de file pour être remis en file.
• Copier contenus d’élément, IDs et détails de diagnostic.

Grandes exécutions et pagination

La console est conçue pour des exécutions avec des milliers d’éléments. Le panneau Items utilise une pagination côté serveur avec des tailles de page bornées, tandis que les synthèses et la matrice étape/état utilisent des requêtes d’agrégat du dépôt sur toute l’exécution sélectionnée.

Cette distinction compte : la virtualisation contrôle seulement l’affichage, tandis que la pagination et les agrégats contrôlent la justesse et la charge de la base de données. Une page peut montrer 250 lignes, mais les totaux d’exécution, les compteurs étape/état, les compteurs prêts à réessayer, les prises en charge et les synthèses d’attention sont calculés depuis la vérité du dépôt.

Les filtres rapides comme Problems, Retry Ready, Running, Leased et Terminal sont appliqués côté serveur pour la liste paginée des éléments.

Vocabulaire des reprises

Guida sépare l’état durable du registre du travail exécutable en file :

• Mark Retry Ready modifie l’état du registre pour que l’élément puisse être repris par la logique du flux. Cela ne crée pas de travail en file par soi-même.
• Requeue and Retry crée du travail exécutable en file lorsque l’élément du registre contient les métadonnées de file nécessaires, puis replace l’élément du registre dans un état pouvant être pris en charge.

Si les métadonnées de file manquent, Guida doit afficher un message de récupération destiné à l’opérateur. La correction habituelle consiste à régénérer l’élément en relançant le processus source ou en mettant en file un élément corrigé, pas à deviner l’ancien contenu.

Liaison avec les files

Les éléments de file peuvent inclure une enveloppe de flux de travail :

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

Lorsque ces métadonnées sont présentes, la Queue Console peut ouvrir l’élément de registre lié, et la Workflow Ledger Console peut expliquer si du travail exécutable en file existe pour un élément.

Métadonnées d’affichage

Les flux peuvent définir la présentation des éléments avec workflow-ledger.display.json à côté de workflow-ledger.schema.json. Les règles d’affichage permettent à un flux de choisir libellés, sous-titres et champs de contexte depuis les champs ou métadonnées de l’élément sans coder une interface propre au domaine dans Guida.

La clé brute de l’élément, l’ID d’élément, l’ID d’exécution, les métadonnées, les événements et les résultats liés restent disponibles dans les détails et actions de copie même lorsqu’un flux fournit des libellés lisibles.

Attention et récupération

La console met en évidence l’attention liée à l’exécution sélectionnée, par exemple :

• prises en charge expirées ;
• éléments prêts à réessayer ;
• éléments rejetés ou en échec ;
• problèmes de liaison avec les files ;
• éléments qui ne peuvent pas être remis automatiquement en file.

L’attention entre plusieurs exécutions appartient aux vues de gestion des exécutions. Les opérations sur l’exécution sélectionnée doivent rester limitées à cette exécution, afin que l’opérateur ne soit pas distrait par des échecs sans rapport.

Réconciliation d’exécution

Les outils MCP du Workflow Ledger et l’API du tableau de bord opérationnel incluent des synthèses compactes de réconciliation pour une exécution sélectionnée. Elles sont utiles pour les contrôles de pipeline, comme le passage de récupération à analyse :

• compteurs traités, ignorés, rejetés, prêts à réessayer, en cours et pris en charge pour la récupération ;
• compteurs en file et terminés pour analyse/indexation ;
• compteurs complets groupés par étape/état.

Ces synthèses servent au diagnostic opérationnel et aux agents distants. Elles ne remplacent pas la console, mais donnent aux scripts et clients MCP une manière bornée de répondre à la question « où est passé le travail ? ».

Pour les espaces de travail avec de nombreux flux de crawling, utilisez la Workflow Control Console pour regrouper étapes du registre, files, modules et passages dans des opérations de niveau opérateur. Utilisez la Workflow Ledger Console lorsque vous avez besoin de la vérité détaillée des éléments derrière une de ces lignes d’opération.

Étapes suivantes

• Files d’attente et révision — gérer le travail exécutable en file
• Processus de travail des files d’attente — exécuter des processus appuyés par des files
• Workflow Control Console — modéliser opérations, cartes de flux, modules et passages
• API du tableau de bord opérationnel — superviser compteurs d’exécutions, files, processus, échecs, attention et réconciliation via HTTP/SSE en lecture seule
• Flux de travail — organiser l’automatisation de l’espace de travail dans des dossiers de flux