Le tableau acquisition compte 12 400 « commandes », la finance en clôture 11 870 et les opérations en suivent 12 090. Chaque équipe utilise un événement nommé order_created, mais l’une mesure le clic, l’autre l’autorisation de paiement et la troisième la première ligne seller acceptée. Aucun écart ne peut être expliqué.
Le problème n’est pas le manque de données. Les producteurs décrivent leurs écrans et leurs tables avec des noms semblables, tandis que les consommateurs supposent une signification métier commune. Les dashboards paraissent précis, mais décisions, alertes et factures reposent sur des grains différents.
Le vrai enjeu d’une taxonomie d’événements dans une marketplace opérateur est de rendre un fait interprétable de la même façon par produit, finance, sellers et support. Contre-intuitivement, multiplier les propriétés « au cas où » aggrave souvent l’ambiguïté au lieu de l’éliminer.
Vous allez comprendre comment choisir grain, noms, contexte, identités, cycles et versions, puis gouverner collecte et usages. Les schémas restent contractuels, l’émission devient idempotente, et monitoring, réconciliation, ownership et compatibilité empêchent le langage commun de dériver à chaque release.
Définir la mission du langage événementiel
Décrire un fait métier observé
Un événement affirme qu’un fait s’est produit à un instant pour un objet et un acteur identifiables. Il ne mélange pas intention future, état courant et résultat. order_paid signifie un paiement acquis selon une règle précise, pas simplement un bouton cliqué ou une autorisation encore annulable.
La définition mentionne déclencheur, source d’autorité, grain, horloge et conditions d’annulation. Elle cite également ce que l’événement ne prouve pas. Cette frontière évite qu’un consommateur transforme une trace d’interface en engagement financier ou une tentative technique en succès métier.
Séparer faits, commandes et snapshots
Une commande demande une action, un événement relate son résultat et un snapshot décrit une situation à un instant. Les trois peuvent voyager dans le même bus sans partager le même contrat. Nommer event une instruction de remboursement rend retries et responsabilités indéchiffrables.
Le catalogue indique la nature de chaque message. Les consommateurs savent s’ils peuvent déclencher un effet, reconstruire un état ou seulement analyser. Un snapshot périodique ne remplace pas l’histoire ; il accélère la reprise tout en citant la dernière séquence appliquée.
Choisir le bon grain
Distinguer panier, commande et ligne seller
Une marketplace transforme souvent un checkout en plusieurs commandes ou lignes seller. Le grain doit être explicite dans le nom ou le schéma. Une acceptation seller porte sa ligne ou sa sous-commande, tandis que la confirmation acheteur peut porter l’ensemble du panier.
Compter les événements sans connaître ce grain multiplie ou réduit artificiellement les volumes. Les métriques déclarent leur unité : paniers, commandes opérateur, commandes seller, lignes ou unités. Les identifiants parents permettent d’agréger sans faire croire qu’un événement de ligne représente tout le checkout.
Préserver atomicité et causalité
Un événement correspond à une transition atomique du domaine. Si trois lignes changent indépendamment, trois faits sont émis avec un identifiant de corrélation. Un gros message contenant « tout ce qui a changé » rend les reprises partielles et les conséquences difficiles à isoler.
Scénario : deux sellers acceptent et un refuse. Si le système émet seulement order_updated, alors fulfillment et support ignorent quelle responsabilité a changé. Trois événements de sous-commandes, reliés au même checkout, permettent de déclencher les actions correctes sans interpréter un diff implicite.
Nommer sans ambiguïté
Utiliser domaine, objet et fait
Un nom stable combine domaine, objet et fait accompli selon une convention : payment.capture_succeeded ou seller_order.accepted. Le temps passé indique un constat. Les équipes évitent les verbes vagues processed, updated ou handled qui cachent plusieurs transitions et changent de sens selon le service.
Le nom reste indépendant du canal et de l’implémentation. checkout_button_clicked peut servir l’analytics d’interface, mais il ne remplace pas order.confirmed. Un changement de fournisseur PSP ne renomme pas les faits métier ; l’adaptateur traduit les événements externes vers le vocabulaire de la plateforme.
Définir un glossaire opposable
Chaque terme sensible possède une définition : créé, confirmé, payé, livré, remboursé, clos. Le glossaire relie mot, événement, état et métrique. Une équipe ne peut pas appeler « revenu » un montant autorisé si finance le reconnaît seulement à la capture.
Les synonymes historiques sont documentés puis dépréciés. Les labels d’écran peuvent rester adaptés aux utilisateurs, mais les contrats internes utilisent le terme canonique. Une revue linguistique accompagne les domaines transverses afin que seller, buyer et operator ne désignent pas trois rôles différents sous account.
Porter le contexte utile
Séparer envelope et payload
L’envelope porte identifiant d’événement, type, version, source, date d’occurrence, date d’émission, corrélation et causalité. Le payload contient les données du fait. Cette séparation offre traçabilité et routage constants sans imposer un schéma métier identique à tous les domaines.
Les champs techniques ne deviennent pas des dimensions business par opportunisme. Une partition Kafka n’explique pas une commande. À l’inverse, marché, seller ou canal nécessaires aux décisions doivent être présents ou résolubles par une référence versionnée, sans dépendre d’un état courant mutable.
Limiter données personnelles et secrets
Le bus ne transporte pas email, adresse complète ou jeton de paiement lorsque des identifiants suffisent. Chaque propriété possède finalité, classification et rétention. Les consommateurs accèdent aux détails via un service autorisé, ce qui évite de répliquer des données sensibles dans des dizaines de sinks.
Les logs et dead letters appliquent les mêmes règles. Une erreur de validation ne doit pas exposer le payload complet dans un outil ouvert. Sécurité vérifie masquage, chiffrement et droits ; conformité suit les usages, tandis que les équipes produit conservent seulement le contexte nécessaire à leur décision.
Stabiliser les identités
Distinguer identifiant et version
L’objet garde une identité stable ; chaque mutation augmente une version ou une séquence. L’événement possède son propre identifiant unique. Confondre order_id et event_id empêche de représenter plusieurs faits pour la même commande et rend la déduplication incorrecte.
Les identifiants anciens, externes et internes restent liés par un registre. Un webhook PSP cite sa référence et l’identité canonique résolue. Les collisions ou références inconnues rejoignent une file, sans créer automatiquement un nouvel objet sous la pression d’un événement tardif.
Relier corrélation et causalité
La corrélation regroupe un parcours ; la causalité relie un fait à celui qui l’a déclenché. Elles répondent à des questions différentes. Un remboursement et une commande partagent une corrélation, mais le remboursement peut être causé par un retour ou une décision support spécifique.
Le graphe causal permet d’expliquer effets, retries et délais sans inférer depuis les timestamps. Si un consumer produit un nouvel événement, il conserve correlation_id et renseigne causation_id. L’observabilité trace ainsi le parcours métier au-delà des frontières de services.
Décrire les cycles métier
Modéliser transitions et compensations
Les événements principaux correspondent aux transitions autorisées des machines d’états. Une annulation ne supprime pas confirmation ; elle ajoute order.cancelled avec motif et initiateur. Une compensation financière possède son fait distinct, relié à l’effet original.
Cette histoire évite les indicateurs qui changent rétroactivement sans explication. Le dashboard peut présenter confirmations brutes, annulations et net, tandis que finance reconstruit les mouvements. Les projections actuelles restent rapides grâce à des vues matérialisées, sans sacrifier l’audit.
Gérer événements tardifs et hors ordre
Occurrence et réception sont séparées. Un scan transporteur peut arriver après le remboursement tout en décrivant une livraison antérieure. Le consumer décide selon version, séquence et policy, pas selon l’ordre d’arrivée dans sa queue.
Si un événement porte une version inférieure à celle déjà appliquée, alors il est ignoré pour l’état mais conservé pour l’audit ou une projection historique. Une séquence manquante déclenche récupération ou attente bornée. Le système ne réécrit pas silencieusement le présent avec un message ancien.
Versionner les schémas
Définir compatibilité et dépréciation
Ajouter un champ optionnel peut rester compatible ; renommer, supprimer ou changer le sens ne l’est pas. Les règles sont testées dans un registry avant publication. Une version majeure coexiste le temps que les consommateurs migrent, avec date et owner de dépréciation.
La documentation générée montre exemple valide, propriétés, contraintes et historique. Elle ne remplace pas la définition métier. Chaque changement cite la décision qu’il sert et les consommateurs affectés, afin d’éviter des champs ajoutés sans propriétaire qui deviennent ensuite impossibles à retirer.
Tester producteurs et consommateurs
Les contract tests vérifient schéma, invariants, enums et sémantique sur des fixtures. Le producteur prouve qu’il émet après la transaction correcte ; le consommateur prouve qu’il accepte anciennes et nouvelles versions pendant la fenêtre prévue.
Les entrées du pipeline sont schéma candidat, exemples et matrice de consommateurs ; ses sorties sont compatibilité, ruptures et plan de migration. Platform reste owner du registry, le domaine du sens et chaque consumer de son adoption. L’instrumentation suit versions émises, rejets, dépendances et échéances.
Gouverner le catalogue
Attribuer un owner métier
Chaque type appartient au domaine qui produit le fait avec autorité. Data ne définit pas seul payment.captured et Front ne possède pas order.confirmed. L’owner répond du sens, du schéma, de la qualité et de la communication des changements.
Le catalogue liste producteurs, consommateurs connus, SLA, classification, versions et contact. Une revue légère suffit pour les faits locaux ; les événements utilisés par finance, conformité ou plusieurs domaines exigent une validation plus large. La gouvernance varie avec l’impact, pas avec le prestige technique.
Fermer doublons et événements zombies
Deux événements au sens proche déclenchent une analyse : grains différents, sources concurrentes ou duplication réelle. L’équipe choisit un canonique et documente la migration. Les dashboards ne combinent pas deux flux pour masquer l’indécision.
Un événement sans producteur actif ou consommateur déclaré peut être déprécié après observation. Avant suppression, les sinks inconnus sont recherchés dans catalogues, jobs et requêtes. La date d’arrêt et le fallback restent annoncés ; un topic silencieux ne signifie pas automatiquement inutile.
Fiabiliser la collecte
Émettre avec la transaction métier
Le transactional outbox enregistre état et événement dans la même transaction, puis un relay publie avec retry. Cette méthode évite une commande confirmée sans message ou un message publié avant le commit. Le consumer reste idempotent car une livraison au moins une fois peut produire des doublons.
L’idempotency key combine événement et consumer. Les effets externes conservent leur propre clé. Un timeout après traitement ne déclenche pas une seconde capture ou un second email. La dead letter garde motif, tentatives et résolution sans devenir un cimetière oublié.
Observer latence et complétude
Le monitoring suit événements produits, publiés, consommés, rejetés et retardés par type et version. La latence distingue occurrence, publication et traitement. Un débit stable peut masquer une source arrêtée si le volume attendu n’est pas comparé à l’activité métier.
Les entrées de réconciliation sont écritures d’autorité, outbox, bus et sinks ; ses sorties sont manquants, doublons et retards. Chaque file possède owner, seuil, runbook et rollback de déploiement. Un backfill utilise checkpoint et version pour ne pas gonfler les métriques historiques.
Contrôler la qualité
Mesurer validité et cohérence
Validité de schéma, complétude, unicité, ordre, fraîcheur et cohérence métier forment des dimensions distinctes. Un événement conforme au JSON peut rester faux si son montant ne correspond pas au ledger ou si sa transition est impossible.
Les contrôles comparent distributions et invariants par version. Une hausse soudaine de valeur inconnue dans reason_code déclenche une alerte avant que les dashboards regroupent tout sous « autre ». Les seuils tiennent compte du volume et de l’impact business.
Réconcilier avec les sources d’autorité
Chaque jour, commandes, paiements, expéditions et événements critiques sont rapprochés par identifiant. Les totaux globaux ne suffisent pas : deux écarts opposés peuvent se compenser. Le verdict descend à l’objet, la version et la cause.
Si plus de 0,1 % des paiements capturés n’ont pas d’événement correspondant après le SLA, alors les usages financiers sont suspendus. L’équipe répare le pipeline, backfille avec clés stables et prouve le rapprochement avant reprise. Les analyses exploratoires restent signalées comme incomplètes.
Relier événements et décisions
Construire des métriques contractuelles
Une métrique cite événements, grain, filtres, fenêtre, déduplication et propriétaire. GMV confirmé, payé ou livré deviennent trois mesures assumées. Le nom d’un dashboard ne masque pas la convention ; finance et produit choisissent celle adaptée à leur décision.
Les dimensions lentes utilisent leur version au moment du fait lorsque l’analyse historique l’exige. Un seller changé de segment ne réécrit pas tous ses événements passés. Les agrégats peuvent être recalculés depuis la taxonomie et les règles versionnées.
Alimenter automation et audit
Un événement critique peut déclencher payout, notification, SLA ou contrôle, à condition que son contrat supporte cet usage. Les consumers sensibles sont déclarés. Un changement analytics ne doit pas casser une automation financière cachée.
Par exemple, si return.received déclenche un remboursement, alors source, preuve, version et idempotence deviennent obligatoires. Un événement envoyé par une interface de test ne passe pas en production. L’audit relie fait, décision et effet sans reconstruire la causalité depuis plusieurs logs.
Adapter la méthode et éviter les erreurs
Pour qui une taxonomie d’événements convient
Elle devient nécessaire dès que plusieurs équipes ou systèmes interprètent les mêmes faits. Une petite plateforme peut commencer avec une dizaine d’événements critiques et un catalogue simple. Elle n’a pas besoin d’un bus complexe pour définir correctement grain, owner et sémantique.
Les domaines possèdent les faits ; Platform le registry et le transport ; Data les métriques ; Sécurité la classification ; consumers leurs effets. Un steward transverse arbitre les termes communs sans reprendre l’autorité métier de chaque équipe.
Erreurs fréquentes de la taxonomie
Nommer updated, confondre clic et résultat, omettre le grain, transporter des snapshots géants, ignorer les versions, compter les messages bruts et publier hors transaction sont les erreurs majeures. Elles fabriquent une précision apparente sans langage partagé.
Une autre erreur consiste à confier tous les noms à Data après coup. Enfin, documenter sans contrôler l’émission ne suffit pas. Le catalogue, les schémas et la réconciliation doivent décrire le même flux réel, sinon la définition reste décorative.
Plan d’action pour installer la taxonomie
Semaines 1 à 4 : faits et contrats
La première semaine sélectionne vingt décisions critiques et remonte aux faits nécessaires. La deuxième ferme grains, noms, identités, horloges et sources d’autorité. Domaine, data et finance signent définitions et contre-exemples avant de toucher aux producteurs. Une revue croisée rejoue ensuite cinq parcours réels et attribue chaque ambiguïté à un owner avec échéance, afin qu’aucun désaccord de vocabulaire ne soit reporté dans le schéma.
Les semaines trois et quatre créent envelope, schémas, catalogue et contract tests. Les fixtures couvrent multi-seller, événement tardif, doublon, version inconnue, compensation et donnée sensible. Chaque type possède owner, consumers, SLA et stratégie de dépréciation.
Semaines 5 à 8 : collecte et adoption
La cinquième semaine connecte outbox, registry et monitoring. La sixième reconstruit trois métriques de référence en parallèle des anciennes. L’instrumentation suit complétude, latence, rejets, versions et écarts par domaine avec seuils et runbooks.
Les semaines sept et huit migrent consumers et dashboards par cohorte, provoquent message hors ordre, panne de relay et rollback, puis vérifient le backfill. Le go exige décisions identiques, objets réconciliés et aucun consumer sensible non déclaré.
Le dossier final conserve glossaire, schémas, versions, fixtures, producteurs, consumers, métriques et procédures. Tout nouveau fait cite son grain et son autorité. Toute évolution incompatible possède une coexistence bornée et une preuve d’adoption avant extinction.
- À faire d’abord : fermer vingt faits critiques, leur grain et leur source.
- À tester ensuite : doublon, ordre, compatibilité, backfill et rollback.
- À différer : les propriétés sans décision ni owner identifié.
- À refuser : toute métrique critique fondée sur un événement ambigu ou non réconcilié.
Ressources complémentaires pour l’opérateur
Structurer objets et exploitation
Le catalogue PIM marketplace stabilise les identités produit consommées par les événements.
Les écrans du back-office opérateur rendent faits, versions et exceptions consultables.
Borner le premier vocabulaire
Le MVP marketplace avant ouverture aide à sélectionner les faits réellement nécessaires.
La méthode pour ouvrir une première catégorie fournit des parcours pilotes observables.
Conclusion : parler le métier
Une taxonomie utile décrit des faits atomiques, identifiés et versionnés plutôt qu’une collection de traces techniques.
Grain, causalité et owners permettent aux équipes de mesurer et d’automatiser sans réinterpréter chaque flux.
Contracts tests, réconciliation et dépréciation gardent ce langage fiable pendant les évolutions de la plateforme.
Dawap peut vous accompagner pour établir ce vocabulaire commun dans votre marketplace opérateur.
