Aller au contenu

Difference Family Audit

Status: CURRENT

À quoi sert cet audit ?

Le Difference Family Audit est un Read Service qui regroupe les écarts observés en familles de différences afin de distinguer quelques causes récurrentes d'une longue liste de symptômes.

Il intervient après une comparaison ou un audit ayant déjà produit des écarts individuels.

Différences individuelles
        ↓
Difference Family Audit
        ↓
Familles d'écarts + volumes + exemples + causes probables

Son objectif n'est pas de corriger les cas, mais d'identifier les groupes sur lesquels une investigation ou une évolution pourrait avoir le plus d'impact.

Pourquoi il existe

Une liste de centaines de différences n'indique pas si l'on observe :

  • des centaines de bugs différents ;
  • une seule règle incorrecte répétée ;
  • plusieurs limites connues ;
  • des données marchandes insuffisantes ;
  • des conflits légitimes.

Le regroupement par famille rend le diagnostic exploitable et évite les corrections produit par produit.

Entrées

Un audit reproductible doit identifier :

  • la source des différences analysées ;
  • le run, snapshot ou dataset ;
  • la verticale et les feeds concernés ;
  • la version du code ou de la règle ;
  • la définition des catégories de différence ;
  • les critères de regroupement ;
  • les exclusions.

La source peut être, par exemple, un Real Sample Comparison ou une Comparison plus large.

Sorties attendues

Chaque famille devrait exposer au minimum :

  • un identifiant ou nom stable ;
  • une définition ;
  • le nombre de cas ;
  • la part de la population concernée ;
  • des reason codes ;
  • plusieurs exemples représentatifs ;
  • la cause probable ;
  • le niveau de confiance dans cette cause ;
  • la couche probablement concernée ;
  • les limites connues.

Une famille ne doit pas être nommée uniquement par une solution supposée. Par exemple, « ajouter règle X » est moins utile que « références constructeur ambiguës après normalisation ».

Exemples de familles

Selon le domaine, une famille peut correspondre à :

  • normalisation de marque incomplète ;
  • identifiants forts contradictoires ;
  • modèle marchand trop générique ;
  • variante non distinguable ;
  • règle verticale manquante ;
  • projection obsolète ;
  • donnée source absente ;
  • conflit légitime ;
  • cas unknown correctement conservé ;
  • anomalie encore non expliquée.

Les statuts resolved, unknown, ambiguous et conflict doivent rester visibles lorsqu'ils expliquent la famille.

Lecture seule

Le Difference Family Audit peut :

  • lire les résultats d'autres Read Services ;
  • regrouper et compter les différences ;
  • produire des statistiques ;
  • sélectionner des exemples ;
  • générer un rapport.

Il ne doit jamais :

  • modifier une Canonical Identity ;
  • modifier une règle métier ;
  • écrire une projection ;
  • appeler un Write Service ;
  • reclasser silencieusement les données persistées ;
  • déclencher un Pipeline ou une synchronisation.

Ne pas confondre corrélation et cause

Une famille est d'abord un regroupement d'observations.

Le fait que plusieurs cas partagent le même symptôme ne prouve pas automatiquement qu'ils ont la même cause.

La documentation du résultat doit donc distinguer :

  • observation : ce qui est mesuré ;
  • classification : comment les cas sont regroupés ;
  • hypothèse de cause : explication à vérifier ;
  • preuve : élément confirmant réellement cette cause.

Cette distinction est essentielle avant de modifier le Domain Core ou un Vertical Module.

Priorisation

Une famille peut être priorisée selon :

  • son volume ;
  • son impact utilisateur ;
  • la gravité métier ;
  • le risque de faux positifs ;
  • la possibilité d'une correction générique ;
  • la nécessité d'une règle verticale ;
  • le coût et le risque du correctif.

Le volume seul ne suffit pas. Une petite famille de conflits graves peut être plus importante qu'une grande famille d'attributs secondaires manquants.

Diagnostic

Pour une famille importante, vérifier dans cet ordre :

  1. les exemples appartiennent-ils réellement au même phénomène ?
  2. les données sources présentent-elles le même motif ?
  3. la normalisation produit-elle le même effet ?
  4. le problème apparaît-il avant ou après le Resolver ?
  5. s'agit-il d'une règle générique ou verticale ?
  6. les cas unknown, ambiguous ou conflict sont-ils légitimes ?
  7. une projection obsolète pourrait-elle expliquer l'écart ?

Il faut identifier la bonne couche avant de proposer une correction.

Ce qu'il ne faut pas en déduire

Une famille nombreuse ne signifie pas automatiquement qu'une correction est nécessaire.

Elle peut représenter :

  • une limite volontaire ;
  • une absence de données ;
  • un conflit réel ;
  • un comportement correct mais différent de la référence initiale.

La famille doit donc être reliée à des exemples et à une preuve avant toute mutation.

Reproductibilité

À source, règles de regroupement et version identiques, l'audit doit produire les mêmes familles et les mêmes compteurs logiques.

Les critères de regroupement doivent être versionnés lorsqu'ils évoluent.

Tests attendus

Les tests doivent couvrir :

  • stabilité du regroupement ;
  • réconciliation des compteurs ;
  • absence d'écriture ;
  • cas appartenant et n'appartenant pas à une famille ;
  • catégories unknown, ambiguous et conflict ;
  • stabilité des reason codes ;
  • déterminisme de l'ordre des familles.

Invariants

  1. L'audit est read-only.
  2. Une famille est définie par des critères explicites.
  3. Tous les cas restent comptés ou explicitement exclus.
  4. Observation, classification et hypothèse de cause restent distinctes.
  5. Les exemples représentatifs accompagnent les totaux.
  6. Une famille ne déclenche jamais automatiquement un correctif.
  7. La couche responsable est vérifiée avant toute évolution.

Voir aussi