Remplacer les champs d'état textuels par des énumérations pour éviter les fautes de frappe dans les workflows

Pourquoi les statuts en chaîne cassent les workflows si facilement

Les champs d'état textuels paraissent inoffensifs parce qu'ils lisent bien dans les logs et la base. Le problème, c'est que ce sont du texte libre : le code ne vous protège pas contre de petites différences comme canceled vs cancelled, Paid vs paid, ou même un espace final.

Une seule faute suffit pour sauter une branche critique. Imaginez un workflow de checkout qui doit rembourser un paiement et arrêter le fulfillment quand une commande est annulée :

if (order.status === "canceled") {
  refund(order.paymentId)
  stopFulfillment(order.id)
  sendCancelEmail(order.customerEmail)
}

Si une partie de l'app écrit cancelled, cette condition ne s'exécute jamais. Rien ne plante. La commande dérive simplement vers le mauvais chemin, et vous vous en rendez compte plus tard quand un client est débité, que l'entrepôt expédie quand même, ou qu'un e-mail ne part pas.

Ces bugs passent souvent les revues pour une raison simple : les chaînes ne montrent pas un « ensemble autorisé ». Les relecteurs voient une vérification de statut et supposent que la valeur est valide. Même si quelqu'un remarque l'orthographe, il n'est pas évident de savoir si le reste du système utilise la variante américaine ou britannique.

Les tests manquent souvent aussi. Les développeurs ont tendance à recopier la même chaîne dans le test et le code, donc le test passe même quand les données réelles sont incohérentes.

Les dégâts apparaissent généralement là où les workflows ont de vraies conséquences :

• Paiements : les remboursements ne se déclenchent pas, les retries s'exécutent alors qu'ils devraient s'arrêter
• Approbations : les demandes restent en « pending » indéfiniment, ou sont approuvées par erreur
• E-mails et notifications : le mauvais message est envoyé, ou rien n'est envoyé
• Fulfillment et accès : les envois continuent, les abonnements restent actifs, les comptes ne sont pas verrouillés

En remplaçant les champs d'état textuels par des enums, vous changez qui est responsable de la justesse. Au lieu que chaque développeur doive se souvenir de l'orthographe exacte, le compilateur (ou au moins votre vérificateur de types) impose une seule liste de statuts valides.

Cette refactorisation ne corrigera pas à elle seule une logique métier défaillante, des conditions de course ou l'absence de piste d'audit. Elle rend simplement les « états impossibles » plus difficiles à produire, donc le reste de votre code de workflow devient plus fiable.

Si vous avez hérité de code généré par l'IA, les chaînes de statut sont l'un des points de défaillance silencieux les plus courants. Il est normal de trouver des fautes éparpillées dans le code UI, les handlers API et les jobs en arrière-plan.

Ce que les enums corrigent (et ce qu'elles ne corrigent pas)

Une enum est une liste nommée de valeurs autorisées. Au lieu d'enregistrer une chaîne en texte libre comme pending ou cancelled, vous choisissez parmi un ensemble fixe comme PENDING, PAID, CANCELED. Le code traite ces valeurs comme les seules options valides.

Le plus grand avantage est d'avoir une source de vérité unique pour les statuts existants. Vous n'avez pas à vous souvenir si c'est cancelled, canceled, CANCELLED ou order_cancelled. L'enum rend l'ensemble autorisé explicite, et tout le reste est invalide.

Les enums vous aident aussi à échouer vite. Avec des chaînes, une faute peut passer en production et ne casser un workflow que sur un chemin rare. Avec des enums, beaucoup d'erreurs remontent plus tôt :

• Votre éditeur et votre compileur peuvent compléter automatiquement et signaler des valeurs inconnues
• Les tests unitaires échouent à l'endroit exact où un statut invalide est défini
• Les switch ou match peuvent vous avertir quand vous avez oublié de gérer un nouvel état
• Les schémas d'API et validateurs peuvent rejeter immédiatement les entrées erronées

Les enums ne règlent pas des règles métier floues. Si l'équipe ne sait pas quand une commande doit être ON_HOLD vs PENDING, une enum ne le tranchera pas. Elles ne résoudront pas non plus un cycle de vie désordonné où plusieurs parties de l'app écrivent le statut de façon conflictuelle. Les enums rendent ces problèmes plus visibles, mais il vous faut toujours des règles claires et une propriété des transitions.

Valeurs stockées vs libellés d'affichage

Une erreur courante est de confondre ce que vous stockez avec ce que vous affichez.

Les valeurs stockées doivent être stables et ennuyeuses, car elles finissent dans les bases, les logs et les intégrations. Les libellés d'affichage peuvent être conviviaux et changer sans rien casser.

Par exemple, stockez CANCELED comme valeur d'enum, mais affichez « Canceled » dans l'UI. Si plus tard vous voulez afficher « Cancelled » pour les utilisateurs UK, cela doit être un changement de libellé UI, pas une migration de base.

Cette distinction compte encore plus lors du nettoyage de code généré par l'IA, où les prototypes codent souvent des chaînes UI comme valeurs de statut. Séparer les enums internes du texte humain aide à empêcher la prochaine faute de finire en incident de production.

Commencez par inventorier vos statuts actuels

Avant de passer aux enums, faites un inventaire propre de ce que vous avez réellement en production. La plupart des équipes pensent avoir 6 statuts, puis en trouvent 18 une fois qu'elles regardent la base, les payloads API, les libellés UI et les anciens logs.

Récupérez les valeurs de statut depuis tous les endroits où elles peuvent apparaître : lignes de base de données (courantes et historiques), requêtes et réponses API (webhooks inclus), état UI (filtres, badges, règles de bouton), jobs et intégrations (facturation, e-mail, expédition), et logs ou événements analytiques.

Cherchez ensuite les doublons et quasi-doublons. Les évidents sont les variantes d'orthographe comme "canceled" vs "cancelled". Les sournois sont des synonymes presque équivalents, comme "paid" vs "payment_received", ou des valeurs qui mélangent état et cause, comme "failed" vs "declined".

Choisissez ensuite des noms canoniques et décrivez en langage simple ce que signifie chaque statut. Une phrase suffit, mais elle doit être précise. Par exemple, paid peut signifier « nous avons capturé l'argent » ou « nous avons généré une facture ». Ces deux interprétations entraînent des workflows différents.

Un petit contrôle de validité : répondez à deux questions pour chaque statut :

• Quels événements peuvent y conduire ?
• Quelles actions sont autorisées pendant qu'on y est ?

Si vous ne pouvez pas répondre clairement, il y a probablement deux statuts cachés dans un seul libellé.

Enfin, décidez quoi faire des valeurs legacy déjà stockées. Approches courantes : mapper les valeurs legacy à l'ensemble canonique (sûr et flexible), renommer in-place lors d'une migration (plus simple mais plus risqué), ou déprécier des valeurs (arrêter de les écrire, continuer de les lire temporairement).

Exemple : vous trouvez "cancelled" dans d'anciennes commandes, "canceled" dans les nouvelles et "void" dans une intégration. Vous pouvez choisir "canceled" comme canonique, mapper "cancelled" et "void" vers lui, et garder un champ séparé pour la raison d'annulation si besoin.

Concevoir une enum de statuts lisible

Une enum de statut doit remplir deux rôles : empêcher les erreurs dans le code et rester lisible quand vous déboguez un incident. Si elle paraît « intelligente », les gens la contourneront et vous retomberez dans le chaos des chaînes.

Décidez où réside la source de vérité

Choisissez un endroit qui définit les valeurs de statut, et traitez tout le reste comme consommateur. Pour beaucoup d'équipes, le backend est la source de vérité la plus sûre car il gère validation et stockage.

Si vous avez plusieurs services, un module partagé ou un schéma peut fonctionner, mais seulement si vous le versionnez et le maintenez.

Une règle simple aide : définir les statuts une fois, les importer partout, et bloquer les chaînes ad hoc en revue de code. C'est ainsi que vous évitez de créer une seconde liste concurrente de statuts.

Règles de nommage qui sauvent la santé mentale

Les statuts doivent ressembler à des codes internes stables, pas à des libellés UI. Choisissez un format et gardez-le partout.

Règles ennuyeuses mais efficaces :

• Utilisez un temps cohérent, généralement le passé pour les états complétés (par ex. PAID, CANCELED, FULFILLED)
• Évitez les synonymes (CANCELLED vs CANCELED). Choisissez une orthographe et appliquez-la
• Gardez les codes courts et clairs. Si vous avez besoin d'une phrase pour expliquer, l'état est probablement trop spécifique
• Réservez UNKNOWN pour de vrais besoins de migration, pas comme cachette pour des bugs

Séparez le texte visible utilisateur. La valeur d'enum est pour les machines et les logs. L'UI peut mapper CANCELED à « Cancelled by customer » ou « Order cancelled » selon le contexte, la langue et le ton.

Pour tout statut susceptible d'être mal compris, ajoutez un court commentaire à sa définition : quand il devient valide et ce qui doit être vrai avant qu'il puisse se produire. Exemple : "REFUNDED": only after PAID; never set directly from PENDING. De petites notes comme ça évitent des transitions accidentelles plus tard.

Étape par étape : refactoriser le code applicatif

Commencez par la couche applicative. Vous voulez que le code cesse d'accepter des chaînes aléatoires bien avant d'avoir touché chaque ligne de la base.

1) Ajouter l'enum (sans l'utiliser partout tout de suite)

Créez un type enum unique dans un endroit central et faites-en la source de vérité. Gardez les noms cohérents.

// Example (TypeScript)
export enum OrderStatus {
  Draft = "DRAFT",
  Submitted = "SUBMITTED",
  Approved = "APPROVED",
  Canceled = "CANCELED",
}

2) Migrer les comparaisons et forcer l'exhaustivité

La plupart des bugs de workflow résident dans de petites vérifications comme if (status === "cancelled"). Remplacez-les par des comparaisons d'enum pour que les fautes ne compilent pas.

Un ordre de refactor qui marche souvent :

• Remplacez les comparaisons de chaînes par des valeurs d'enum (status === OrderStatus.Canceled)
• Rendre les switch exhaustifs pour que les états oubliés échouent bruyamment
• Mettre à jour les types pour que les variables communiquent le changement (status: OrderStatus au lieu de status: string)
• Supprimez les branches « fallback par défaut » qui masquent les cas manquants
• Cherchez les littéraux de statut et nettoyez-les un par un

Si votre langage le supporte, utilisez un pattern assert never (ou les checks du compilateur) pour que l'ajout d'un nouveau statut vous force à le gérer partout.

3) Ajouter la validation aux frontières (là où les chaînes arrivent)

Même après la refactorisation, des entrées arrivent toujours sous forme de chaînes : requêtes HTTP, événements webhook, payloads de jobs, messages en file. Validez et convertissez à la frontière, puis gardez les enums à l'intérieur.

De bonnes validations aux frontières incluent : rejeter les statuts inconnus tôt avec une erreur claire, mettre en quarantaine les événements inattendus au lieu de deviner, valider les payloads de job avant tout changement d'état, et limiter les dropdowns admin à la liste d'enum.

4) Garder un adaptateur temporaire pour les chaînes legacy

Pendant le déploiement, vous devrez peut‑être lire d'anciennes valeurs comme "cancelled" dans des enregistrements ou des callbacks tiers. Ajoutez un petit adaptateur qui mappe les chaînes legacy à l'enum, et isolez-le.

Ce pattern garde les entrées désordonnées aux frontières, convertit une fois, et rend le cœur du workflow difficile à casser par une simple faute.

Mettre à jour la base sans surprises de downtime

Les changements de base de données sont souvent là où les refactors de statut dérapent. L'approche la plus sûre est d'ajouter d'abord la nouvelle structure, de garder les anciennes lectures fonctionnelles, puis de durcir les règles quand l'app écrit complètement les nouvelles valeurs.

Type enum vs table de lookup

Vous avez typiquement deux bonnes options :

• Type enum en base : rapide, compact et bloque les valeurs invalides, mais peut être pénible à modifier plus tard
• Table de lookup (statuses + foreign key) : facile à étendre et peut stocker des métadonnées, mais ajoute un join et un setup

Si la liste risque d'évoluer souvent (nouveaux états, états retirés, variantes par tenant), une table de lookup est souvent le choix plus serein.

Un pattern de migration sûr

Pour passer des chaînes aux enums sans downtime, utilisez un flux expand → migrate → contract :

1. Expand : ajoutez une nouvelle colonne (status_v2) ou le nouveau type enum tout en gardant l'ancienne colonne status. N'ajoutez pas encore de contrainte stricte.
2. Dual write : faites en sorte que les nouveaux enregistrements/updates écrivent à la fois status (ancien) et status_v2 (nouveau enum ou FK). Les lectures existantes continuent d'utiliser l'ancien champ.
3. Backfill : lancez un job pour mapper les anciennes chaînes aux nouvelles valeurs. Normalisez les espaces, la casse, et décidez quoi faire des inconnues (quarantaine ou fallback sûr).
4. Lock it down : une fois le backfill terminé et l'écriture double en place, ajoutez des contraintes pour empêcher les mauvaises valeurs à l'avenir (contrainte enum, clé étrangère, et éventuellement NOT NULL).
5. Contract (cleanup) : basculez les lectures sur le nouveau champ, surveillez un cycle de release complet, puis supprimez l'ancien champ ou conservez-le temporairement pour compat.

Avant d'ajouter NOT NULL, vérifiez combien de lignes n'ont pas status_v2. Si le compte n'est pas zéro, corrigez le mapping d'abord pour éviter des échecs de migration surprises.

Aligner l'API, l'UI et les intégrations

Une fois passé aux enums, les plus gros bénéfices viennent de faire en sorte que chaque point d'entrée soit d'accord sur les mêmes valeurs autorisées. Si votre API accepte n'importe quoi, l'UI peut encore envoyer des fautes, et un webhook peut injecter d'anciennes chaînes.

Verrouiller le contrat d'API

Mettez à jour le schéma API et la validation pour que seuls les statuts connus soient acceptés. Si quelqu'un envoie une valeur inconnue, échouez vite avec un message qu'une personne non technique peut comprendre.

Contrôles pratiques :

• Validez le statut à chaque écriture (create, update, bulk), pas seulement sur un endpoint
• Retournez une erreur claire du type : "Status must be one of: pending, approved, canceled" (et incluez la valeur reçue)
• Faites des réponses cohérentes : renvoyez toujours la valeur d'enum canonique
• Ajoutez des tests qui essayent les fautes courantes (comme cancelled) et confirment que vous les rejetez

Rendre l'UI et les intégrations honnêtes

Sur le front, évitez les chaînes hardcodées à plusieurs endroits. Dropdowns, filtres et badges doivent provenir des mêmes valeurs autorisées que le backend impose. Sinon quelqu'un « renomme un label » et change accidentellement la valeur envoyée au serveur.

Pour les intégrations externes, vous ne pourrez souvent pas imposer un changement rapide côté partenaire. Utilisez le versioning ou une couche de traduction qui accepte les anciennes valeurs et les mappe vers l'enum. Exemple : un partenaire peut encore envoyer "cancelled" alors que votre enum utilise "canceled". Acceptez-le temporairement, mappez-le et loggez un avertissement pour savoir qui doit être mis à jour. Planifiez une date pour retirer la compatibilité.

Mettez aussi à jour l'analytics et les rapports pour que les graphiques ne se segmentent pas entre anciennes et nouvelles chaînes. Normalisez les valeurs historiques vers l'enum avant les exports ou tableaux de bord.

Exemple : le bug canceled vs cancelled dans un vrai workflow

Un endroit fréquent où ça mord est un système de commandes où le statut contrôle trois choses à la fois : remboursements, e-mails clients et fulfillment. Ça paraît simple jusqu'à ce qu'une faute d'orthographe crée un second « statut valide ».

Imaginez un flow de checkout qui écrit order.status = "cancelled" (double L) quand un acheteur annule. Mais le job de remboursement filtre pour "canceled" (single L) parce que quelqu'un a copié l'orthographe depuis un autre fichier. Maintenant vous avez deux branches qui ne se rencontrent jamais.

Comment ça échoue en vrai :

• L'UI montre « Cancelled », donc le support suppose que le remboursement est en cours
• Le worker de remboursement ne le récupère jamais (il filtre canceled)
• Le fulfillment peut toujours s'exécuter si lui n'empêche que canceled, donc une commande « cancelled » peut être expédiée
• Les templates d'e-mail peuvent diverger aussi, si bien que le client reçoit le mauvais message

Avec une enum, il n'y a pas deux orthographes. Il y a une seule valeur, et le code qui essaie d'utiliser autre chose ne compilera pas (ou échouera en validation tôt, selon votre stack).

Les données anciennes et les anciens événements nécessitent toujours de l'attention. Une approche pragmatique : migrer les lignes existantes en mappant les deux chaînes (canceled, cancelled) vers la valeur d'enum unique, garder un fallback temporaire lors de la lecture d'anciens événements, et ajouter un audit pour compter les statuts inconnus afin de corriger les retardataires.

Erreurs et pièges courants lors d'une refactorisation de statuts

Les refactors de statuts échouent moins parce que les enums sont difficiles, et plus parce que l'ancien et le nouveau monde coexistent un certain temps. C'est dans cet overlap que les bugs se cachent.

Un piège fréquent est de laisser les enums côté backend alors que l'API, l'UI ou la base acceptent encore du texte libre. Vous vous retrouvez avec une demi-migration où du code utilise OrderStatus.Canceled et d'autres parties continuent d'écrire "cancelled". Si vous devez supporter les deux pendant la transition, faites la conversion à un seul endroit et forcez tout le reste à utiliser l'enum.

Un autre oubli fréquent est de renommer un statut sans poursuivre tous les consommateurs « invisibles ». Filtres de dashboard, exports CSV, alertes ou vues support peuvent encore chercher l'ancienne valeur. L'app semble OK jusqu'à ce que quelqu'un dise : « le rapport des commandes cancelled est vide ».

Les jobs en arrière-plan et les intégrations sortantes sont faciles à oublier. L'UI peut arrêter d'envoyer des chaînes, mais un job nocturne, un handler webhook ou un callback de paiement peut encore définir un statut directement. Traitez toute valeur externe comme non fiable et traduisez-la.

Erreurs qui coûtent le plus :

• Laisser strings et enums actifs dans différentes couches pendant des semaines, si bien que personne ne sait ce qui est canonique
• Renommer des statuts sans mettre à jour filtres sauvegardés, exports, alertes et dashboards admin
• Oublier des écrivains non-UI comme cron, queues, webhooks et callbacks tiers
• Laisser passer des statuts vides ou inconnus à cause d'une validation faible (« default to empty string » est un classique)
• Sauter les tests pour des états rares comme chargeback, manual review, expired, ou dispute

Un petit exemple réel : vous ajoutez une enum et mappez "cancelled" vers Canceled, mais vous oubliez un ancien chemin qui écrit encore "canceled" comme chaîne brute. Résultat : deux orthographes dans la base à nouveau, et le job de remboursement ne récupère qu'une des deux.

Pour réduire les surprises avant livraison : rejetez les valeurs inconnues aux frontières (API, webhooks), loggez et comptez les mappings de fallback pour voir qui envoie encore les chaînes legacy, testez avec des enregistrements proches de la production incluant d'anciennes orthographes, et fixez une date de dépréciation pour les entrées en chaîne (puis retirez-les vraiment).

Checklist rapide et prochaines étapes pratiques

Le but est simple : l'app doit accepter uniquement des statuts connus, stocker uniquement des statuts connus et afficher uniquement des statuts connus.

Avant de déclarer la refactorisation terminée, vérifiez ces points :

• Cherchez les chaînes de statut dans la base de code. Idéalement, vous ne les trouvez qu'à un seul endroit : un petit adaptateur qui traduit les entrées legacy (anciennes valeurs DB, webhooks entrants, anciens clients) vers votre enum.
• Faites en sorte que la base rejette les statuts invalides (type enum natif, contrainte CHECK, ou table de référence) et confirmez que les anciennes valeurs ont été migrées.
• Confirmez que l'API et l'UI s'accordent sur les options autorisées et utilisent la même source de vérité.
• Vérifiez les logs et l'analytics. Si vous suivez les changements de statut, assurez-vous que les tableaux ne se divisent pas silencieusement en deux statuts proches.

Quelques tests ciblés rapportent souvent bien :

• Essayez de parser ou définir un statut inconnu (comme "cancelled" quand l'enum n'autorise que "canceled") et attendez-vous à une erreur claire
• Lancez un test de workflow bout-en-bout (create -> pay -> cancel) et affirmez que le statut stocké est exactement la valeur d'enum
• Si vous avez des intégrations, envoyez un statut legacy à l'adaptateur et confirmez qu'il mappe correctement (et rejette les valeurs vraiment invalides)

Si ce bazar vient d'un prototype généré par l'IA, un audit rapide révèle souvent des écritures de statut éparpillées dans handlers, routes API et jobs. FixMyMess (fixmymess.ai) se concentre sur le diagnostic et la réparation de ces motifs cassants pour la production, et une refactorisation en enum est souvent l'un des moyens les plus rapides d'empêcher des failures silencieuses avant un nettoyage plus profond.