Dictionnaire de données pour une base prototype qui évite les ruptures

Pourquoi les prototypes cassent si facilement le reporting et la facturation

Les bases prototypes évoluent rapidement. Vous ajoutez une colonne pour faire marcher quelque chose, renommez un champ pour que l’interface soit plus lisible, ou changez un type pour corriger un bug. L’application tourne toujours, donc tout semble sûr.

Le reporting, la facturation et les exports sont moins indulgents. Ils reposent sur des suppositions silencieuses : ce qu’un montant inclut, quel horodatage définit un mois, ce qu’un statut signifie vraiment. Quand ces suppositions changent sans que personne ne le remarque, les chiffres dérivent et rien ne génère d’erreur.

Une panne courante ressemble à ceci : un rapport somme amount, mais un correctif rapide transforme amount de « prix avant taxes » en « prix après remises ». Les totaux s’additionnent toujours, mais ils signifient autre chose. La facturation part incorrectement, les graphiques de revenus ne correspondent plus, et il faut des semaines pour trouver la cause parce que la base fait exactement ce que vous avez demandé.

Les prototypes sont fragiles parce que le sens des colonnes est souvent flou. Des noms comme status, type, value ou total peuvent masquer des idées différentes selon les endroits. Le status d’une table peut signifier « facture envoyée », une autre « paiement reçu », et une troisième « abonnement actif ». Ajoutez du code généré par IA et vous obtenez souvent des noms incohérents, des champs dupliqués et une logique répartie sur plusieurs tables.

La plupart des cassures proviennent de petites modifications « évidentes » :

• renommer des colonnes dont dépendent les tableaux de bord ou les exports
• réutiliser une colonne pour un nouvel usage au lieu d’en créer une nouvelle
• mélanger les unités (centimes vs dollars, UTC vs heure locale)
• changer le comportement des valeurs nulles ou des valeurs par défaut
• backfiller des données sans respecter les règles originales

Un dictionnaire de données est la garde-fou la plus simple contre cela. C’est une note en langage clair pour chaque table et colonne : ce qu’elle représente, d’où elle vient et comment l’utiliser. Le but n’est pas une documentation parfaite. C’est pouvoir changer le schéma sans changer le sens de vos indicateurs métier.

Ce qu’est (et n’est pas) un dictionnaire de données

Un dictionnaire de données est une cartographie en langage clair de votre base de données. Il met l’accent sur le sens et les règles, pas seulement sur la structure.

L’important est de passer de « ce qu’il stocke » à « ce que cela signifie ». Une colonne nommée amount peut contenir un nombre, mais le sens peut être « sous-total en centimes, avant taxes, dans la devise de facturation du client, hors remboursements ». Sans ce sens écrit, deux personnes utiliseront le même champ différemment et les totaux ne correspondront pas.

Ce qu’il devrait contenir

Restez concis, mais suffisamment complet pour qu’un nouvel arrivant puisse effectuer un changement en toute sécurité :

• une description pour chaque table et colonne (sens métier, pas seulement le type)
• règles et contraintes (obligatoire vs optionnel, valeurs autorisées, arrondi, fuseau horaire)
• ownership (qui décide du sens et qui approuve les changements)
• sources et destinations (d’où viennent les données et où elles sont utilisées)
• notes sur les données sensibles (PII, tokens, durées de conservation)

Ce que ce n’est pas

Un dictionnaire de données n’est pas un diagramme ER, une liste de requêtes SQL ou un dump de commentaires auto-générés du schéma. Ceux-ci peuvent aider, mais ils expliquent généralement la forme, pas le sens.

Ce n’est pas non plus une tâche ponctuelle. Il doit évoluer avec votre schéma.

Où le stocker

Mettez-le là où les gens le mettront réellement à jour : un document, une feuille de calcul partagée ou une page wiki. L’outil importe moins que la constance. Choisissez un endroit, un format et un propriétaire.

Traitez-le comme faisant partie du changement. Si vous ajoutez une colonne, en renommez une ou modifiez le calcul d’une valeur, mettez à jour le dictionnaire le même jour.

Commencez par les sorties dont les gens dépendent

Une base prototype est plus facile à documenter de l’extérieur vers l’intérieur : commencez par ce dont l’entreprise dépend aujourd’hui. Les tables peuvent changer chaque semaine, mais les factures, tableaux de bord, exports et e‑mails clients tendent à devenir la « vérité » dans la tête des gens.

Commencez par identifier qui est pénalisé quand les chiffres changent :

• la finance se soucie des totaux, des taxes et des remboursements
• l’exploitation se soucie de l’état de réalisation et de livraison
• le produit se soucie du comportement de l’app dans les cas limites
• l’analytics se soucie des définitions et des fenêtres temporelles
• le support se soucie de ce que voient les clients et de ce que les agents peuvent expliquer

Puis choisissez quelques sorties métier critiques et traitez chacune comme un contrat, rédigé en langage clair. Exemples :

• “Invoice total = sum(line items) + tax - discounts.”
• “Monthly active users excludes internal accounts.”

Ces phrases deviennent des ancres pour vos définitions de tables et colonnes.

Ne devinez pas. Rassemblez quelques artefacts réels que votre équipe utilise déjà :

• une facture payée ou un reçu récent
• un export CSV qu’un client ou un collègue utilise réellement
• une capture d’écran d’un tableau de bord considérée comme « source de vérité »
• un modèle d’e‑mail de support qui inclut des chiffres (fin d’essai, montant dû)
• une réponse API exemple utilisée par un autre système

Choisissez une petite portée initiale : les 5–10 tables qui alimentent l’argent et les métriques clés. Si vous pouvez retracer “Subtotal”, “Tax” et “Total” d’une facture jusqu’à la requête exacte qui les calcule, vous avez trouvé le point de départ.

Que documenter pour chaque table et colonne

Commencez par ce que votre base sait déjà, puis ajoutez le sens humain qui empêche les petites corrections de casser le reporting, la facturation ou les exports.

Pour chaque table

Rédigez une phrase d’objectif qui dissipe l’ambiguïté.

Exemple : invoices stocke une ligne par facture client, pas par tentative de paiement.

Cette ligne unique fait gagner des heures plus tard quand quelqu’un joint la mauvaise table ou suppose la mauvaise granularité.

Pour chaque colonne

Capturez deux couches :

• Faits de schéma : type, nullable, valeur par défaut, et si c’est unique ou indexé.
• Signification en bon français : ce qu’elle représente, plus 2–3 valeurs exemples.

Ajoutez ensuite les règles qui maintiennent la stabilité des chiffres :

• Règles de données : valeurs autorisées, unités, arrondi et hypothèses de fuseau horaire.
• Lignage : d’où elle vient, qui l’écrit et quand elle est mise à jour.
• Notes de confidentialité : contient-elle des PII et ce qui ne doit jamais être exporté.

Les règles de données cachent souvent les pires pièges dans les prototypes :

• Si vous avez amount, précisez dollars ou centimes, la devise et l’arrondi.
• Si vous avez created_at, indiquez le fuseau horaire et si c’est l’app ou la base qui le définit.
• Si vous avez status, listez les valeurs autorisées et ce que chacune signifie.

Le lignage est encore plus important dans des prototypes désordonnés. Une colonne peut être écrite par un job en arrière‑plan, un webhook ou un formulaire client. Si personne ne peut répondre à « qui crée cette valeur ? », les rapports dériveront.

Enfin, signalez la confidentialité clairement. Marquez email, adresse, IP et tout token ou secret, et notez ce qui ne doit jamais apparaître dans les exports.

Un modèle simple de dictionnaire réutilisable

Choisissez un format que vous maintiendrez réellement. Pour les petits prototypes, une seule feuille de calcul suffit : soit un onglet par table, soit un seul onglet où les lignes sont groupées par nom de table.

Un dictionnaire utile vous aide à répondre rapidement à deux questions :

• Que signifie ce champ ?
• Qu’est‑ce qui cassera s’il change ?

Modèle (copier/coller)

Utilisez le même ensemble de colonnes pour chaque table, même si certaines cellules restent vides au début :

Table:

| Column | Type | Null? | Description | Example | Key/Relation | Used by (report/billing/export) | Owner | Notes / Warnings |
|--------|------|-------|-------------|---------|--------------|----------------------------------|-------|------------------|
| id     | uuid | no    | Primary identifier for this row | 8f... | PK | internal joins | Eng | DO NOT CHANGE format |

Dans “Key/Relation”, écrivez des indications de jointure simples, pas des essais. Exemple : “FK -> users.id (many invoices belong to one user).”

Si une relation n’est que logique dans le code (fréquent dans les prototypes générés par IA), documentez-la quand même comme « FK logique » pour que la prochaine personne ne la rate pas.

Ajoutez des avertissements seulement quand c’est important. Si une colonne alimente les totaux de facture, les taxes, les rapports de revenus ou un export destiné au client, étiquetez‑la clairement (par exemple, “alimente les totaux de facture - ne changez pas le nom/type sans mettre à jour les exports”).

Règles de nommage pour éviter la confusion

Vous n’avez pas besoin d’un énorme guide de style. Quelques conventions cohérentes évitent la plupart des dérives :

• choisissez noms de tables au singulier ou au pluriel et gardez‑les constants
• choisissez un format de clé primaire (id ou <table>_id) et conservez‑le
• nommez les clés étrangères <referenced_table>_id (exemple : customer_id)
• stockez l’argent en centimes entiers quand c’est possible (ex : amount_cents) et documentez l’arrondi
• standardisez les timestamps (created_at, updated_at) et documentez le fuseau

Construisez la première version en une après‑midi

Vous n’avez pas besoin d’un doc parfait. Il vous faut quelque chose qui empêche de casser l’argent et les métriques.

1) Exportez le schéma existant

Listez chaque table et colonne telles qu’elles existent aujourd’hui. La plupart des bases et des ORM peuvent produire cela rapidement (interface d’administration, fichier de schéma, dump SQL). Collez‑le dans une feuille ou un doc, une ligne par colonne.

Faites un tri rapide et marquez les tables qui touchent :

• invoices, payments, subscriptions, discounts, refunds
• tableaux de bord de métriques et rapports hebdomadaires
• tout export CSV ou intégration qui quitte votre système

Si vous n’êtes pas sûr, cherchez dans le code “invoice”, “total”, “export”, “report” et “balance” et notez quelles tables ces requêtes touchent.

2) Remplissez le sens et les règles, en commençant par l’argent

Rédigez des définitions pour les champs qui pilotent les totaux et les changements d’état. Commencez par la devise et le temps car les petites incompréhensions créent de gros problèmes.

Concentrez‑vous d’abord sur :

• champs de montant (devise, taxe incluse ou non, centimes vs décimales)
• champs de statut (valeurs autorisées et signification exacte)
• timestamps (quel événement ils représentent et le fuseau)
• clés étrangères (ce que la relation signifie dans la réalité)
• identifiants (ce qui est destiné aux utilisateurs vs interne)

Mettez la règle à côté de la colonne, pas dans une section “règles” séparée.

Exemples :

• “invoice.status = paid seulement après capture du paiement, pas lors d’une tentative.”
• “line_item.amount_cents exclut les remises ; discount_cents est séparé.”

Validez ensuite avec une personne non technique qui dépend des chiffres (finance ou exploitation). Parcourez un scénario réel : “Si un client est remboursé, quelles colonnes changent et quel rapport doit toujours correspondre ?” Ajustez la formulation jusqu’à ce qu’elle soit d’accord.

Conservez un tout petit journal de modifications (date, ce qui a changé, pourquoi) et assignez un propriétaire pour la revue.

Rattachez les colonnes aux métriques, factures et exports

Un dictionnaire vaut surtout s’il protège les sorties dont les gens dépendent. Chaque métrique clé, ligne de facture et colonne d’export doit pointer vers les champs exacts qui la produisent.

Pour chaque sortie « ne pas se tromper » (MRR, factures payées, solde dû, abonnés actifs, exports clients), capturez :

• ce que cela signifie (une phrase qu’un collègue non technique approuverait)
• la règle temporelle (date de facture vs date de paiement, et le fuseau utilisé)
• les filtres (valeurs de statut incluses, comptes de test exclus)
• les dépendances (table.colonne list, y compris les clés de jointure)
• la “source de vérité” quand les valeurs divergent

Soyez explicite quand le schéma offre deux sources concurrentes. Si le reporting peut utiliser soit payments.amount soit invoices.paid_amount, décidez lequel prévaut et écrivez si l’autre est dérivable (recalculable) ou fait autorité (ne doit pas être écrasé).

Documentez les cas limites qui provoquent souvent des divergences :

• remboursements comme paiements négatifs vs lignes de remboursement séparées
• paiements partiels et paiements multiples par facture
• abonnements annulés qui facturent toujours jusqu’à la fin de la période
• factures rétrodatées ou données historiques migrées
• clients dupliqués créés par des flux d’inscription “magiques”

Vous n’avez pas besoin de coller du SQL partout. Enregistrer la logique en mots suffit généralement :

• “Sommer les paiements où status = succeeded, groupés par mois de facture, en excluant les remboursements, en utilisant paid_at.”

Erreurs courantes qui coûtent cher

Les bases prototypes “fonctionnent” parce que l’app est tolérante. La surprise vient plus tard, quand une petite modification casse un rapport, un total de facture ou un export CSV utilisé par un client.

Renommer sans vérifier l’usage en aval

L’app peut continuer à tourner, mais les feuilles de finance, les dashboards BI et les scripts d’export peuvent toujours chercher l’ancien nom.

Champs d’argent vagues

Une colonne amount peut signifier centimes ou dollars, net ou brut, avant taxe ou après taxe, remboursements inclus ou non. Si personne ne l’écrit, vous finirez par discuter de « pourquoi les totaux ne correspondent pas ».

Fuseaux temporels mélangés

Les prototypes mélangent souvent created_at, paid_at, fulfilled_at et “quand le job s’est terminé” dans un même graphique. Si un rapport groupe par date de création et un autre par date de paiement, les chiffres de fin de mois peuvent fortement varier.

Types d’identifiants incohérents

Si customer_id est une chaîne dans une table et un entier dans une autre, les jointures échouent, des doublons apparaissent et des lignes sont manquées dans les exports.

“Status” qui devient une poubelle

De nouvelles valeurs sont ajoutées en période de rush, et personne ne documente leur sens. Plus tard, quelqu’un filtre sur le mauvais ensemble de statuts et modifie silencieusement une métrique.

Un ensemble rapide d’odeurs à détecter avant de déployer une modification :

• un nom de colonne a changé mais les rapports/exports n’ont pas été vérifiés
• les champs monétaires ne précisent pas la devise et si la taxe est incluse
• plusieurs timestamps existent mais un seul est utilisé “parce qu’il était là”
• les IDs n’ont pas le même type entre les tables
• les valeurs de status ne sont pas listées avec leur signification en clair

Checklist rapide avant de modifier la base

Avant de renommer une colonne ou “d’ajouter un champ vite fait”, marquez une pause et vérifiez les éléments qui préservent la trésorerie et le reporting :

• Les tables de facturation ont des propriétaires. Si une table affecte factures, paiements, abonnements, remises ou remboursements, quelqu’un est responsable de son sens et de quand il peut changer.
• Chaque colonne monétaire est sans ambiguïté. Documentez la devise, la précision (centimes ?), et si c’est net ou brut. Indiquez si elle inclut taxes, frais ou crédits.
• Chaque champ temporel indique l’événement et le fuseau. “created_at” peut signifier insertion de la ligne, clic sur « Payer » ou règlement effectif. Choisissez un sens et documentez‑le.
• Les jointures principales sont identifiées. Listez les jointures « chemin d’or » utilisées en reporting (ex : invoices -> invoice_items -> customers).
• Les exports définissent des contrats. Si un export attend des dates ISO, des centimes en entier ou des noms de colonnes précis, écrivez‑le pour qu’un refactor ne casse pas les outils en aval.

Conservez un journal simple qui répond :

• ce qui a changé (schéma et définition)
• qui a changé et quand
• pourquoi cela a changé et quelles sorties re‑vérifier

Un petit exemple : renommer paid_at en paid_on peut sembler inoffensif, mais cela peut casser un export comptable ou déplacer les métriques “payé aujourd’hui” si le nouveau champ commence à stocker un autre événement.

Exemple : réparer un schéma de facturation désordonné sans casser les totaux

Problème fréquent : une app construite par IA a invoices et une table transactions, mais personne ne sait réellement ce que signifie chaque champ. On trouve des colonnes comme amount, total, fee, status, type, notes et meta. Le reporting semble correct jusqu’à ce que vous “nettoyiez” le schéma et que les totaux de facture, taxes ou remboursements ne correspondent plus à ce que les clients ont payé.

Commencez petit : concentrez‑vous uniquement sur la facturation. Choisissez une facture que vous savez correcte (le montant payé par le client correspond au processeur de paiement). Retracez comment le total affiché dans l’UI a été calculé, puis écrivez le sens de chaque colonne impliquée.

Clarifiez ce qui détermine réellement les totaux

Soyez explicite sur la source de vérité et les conventions de signe :

• transactions.gross_amount_cents : charge complète avant remises et remboursements (documentez la devise et l’arrondi).
• transactions.tax_cents : part fiscale, et si elle est comprise dans le brut ou ajoutée en plus.
• transactions.discount_cents : remises appliquées au moment de la charge, pas après.
• transactions.refund_cents : remboursements enregistrés en centimes positifs (ou lignes négatives). Choisissez une convention et documentez‑la.
• invoices.total_cents : définissez la formule (gross - discount - refunds + tax) et les lignes exactes qu’elle somme.

Une fois ces significations écrites, un “petit refactor” comme renommer amount en total ne pourra pas se faire à la légère. Si quelqu’un change les types (centimes → dollars), inverse les signes, ou filtre par un status différent, vous verrez immédiatement quels rapports et factures changeront.

Documentez un export de bout en bout

Choisissez un export CSV que la finance ou une agence utilise réellement. Rédigez les colonnes attendues, les formats et les hypothèses. Exemple :

• invoice_number (string)
• issued_at (date ISO)
• subtotal_cents (integer)
• tax_cents (integer)
• total_cents (integer)
• indiquation si les remboursements apparaissent en lignes séparées

C’est là que les cassures cachées se montrent. Les outils en aval attendent souvent des centimes, des noms de colonnes stables et un traitement constant des remboursements. Un dictionnaire vous force à conserver ces contrats.

Si le schéma est trop désordonné ou dangereux à toucher (jointures floues, devises incohérentes, données sensibles aux mauvais endroits), suspendez le refactor et établissez un plan avant de modifier quoi que ce soit.

Étapes suivantes : gardez‑le à jour et demandez de l’aide quand le prototype résiste

Un dictionnaire de données ne vous protège que s’il reste à jour. La règle la plus simple fonctionne bien : aucun changement de schéma ne part tant que l’entrée du dictionnaire n’est pas mise à jour.

Gardez les définitions accessibles à des non‑techniques. Visez une phrase, un seul sens. Si une colonne signifie deux choses selon l’écran ou le workflow, considérez que le reporting ou la facturation est déjà incohérent.

Ajoutez une revue légère pour les changements à haut risque

Vous n’avez pas besoin d’un gros processus, mais vous avez besoin d’un bouton pause pour tout ce qui touche à l’argent ou aux métriques cœur.

Avant de merger un changement qui affecte la facturation ou le reporting, confirmez :

• l’entrée du dictionnaire a été mise à jour (table, colonne, sens, exemple)
• les rapports/exports/calc de facture dépendants ont été identifiés
• les anciennes valeurs sont traitées (plan de migration ou comportement par défaut)
• quelqu’un possède la définition (un nom, pas « engineering »)

Si vous avez hérité d’un prototype généré par IA et que vous n’êtes pas sûr de ce qui est sûr à changer, un audit court peut vous faire gagner des jours de discussions. FixMyMess (fixmymess.ai) réalise un diagnostic de code et des réparations pour les apps construites par IA, et propose un audit de code gratuit pour cartographier les problèmes de facturation, reporting et logique de base de données avant d’intervenir sur les données de production.