Bugs de fuseaux et DST : checklist pour une planification fiable

Ce qui casse la planification quand les fuseaux changent

Quand la planification foire, les utilisateurs ne pensent pas « fuseaux horaires ». Ils pensent que l’app est peu fiable. Le même événement apparaît à la mauvaise heure, les rappels arrivent en avance ou en retard, ou une réunion est manquée parce qu’elle a discrètement bougé.

Les pannes les plus déroutantes sont celles qui semblent correctes dans le code. Vous stockez une date, vous affichez une date, et les tests passent. Puis un vrai calendrier franchit une frontière de fuseau et votre conversion « simple » devient une cible mouvante. C’est le cœur des bugs de fuseaux et de DST : les offsets changent, mais votre valeur stockée ou votre conversion suppose qu’ils ne changent pas.

Les problèmes apparaissent généralement à quelques moments prévisibles :

• Début du DST (l’« heure manquante ») : une heure locale comme 02:30 peut ne pas exister.
• Fin du DST (l’« heure double ») : 01:30 peut se produire deux fois, et vous choisissez la mauvaise.
• Voyages (ou télétravail) : le même utilisateur ouvre l’app dans un fuseau différent.
• Changement de serveur ou valeurs par défaut des conteneurs : la prod s’exécute dans un fuseau différent de votre laptop.
• Backfills et imports : des données tierces arrivent avec un offset, pas une vraie zone.

Un exemple rapide : un utilisateur programme « tous les jours à 9:00 » depuis New York. Si vous le stockez comme « 09:00 moins l’offset actuel » (au lieu de « 9:00 en America/New_York »), ça peut devenir 8:00 après le DST même si l’utilisateur n’a rien demandé.

Quelques règles évitent la plupart des problèmes :

• Décidez si l’horaire est lié à un lieu (une zone) ou à un instant (UTC).
• Stockez l’UTC pour les instants réels, et stockez la zone IANA pour les horaires récurrents locaux.
• Traitez les « heures murales » pendant les transitions DST comme des cas spéciaux, pas comme des conversions normales.
• Ajoutez des tests pour le début du DST, la fin du DST et le changement de fuseau de l’utilisateur.

Vocabulaire rapide : UTC, heure locale, offsets et zones

Les bugs de planification commencent souvent parce que les gens confondent des termes qui se ressemblent. Traitez-les comme des concepts distincts et nommez-les clairement dans votre code et votre UI.

UTC (Temps Universel Coordonné) est une horloge globale unique. Elle ne change pas pour l’heure d’été. Un instant comme "2026-01-16T14:30:00Z" est sans ambiguïté partout dans le monde.

Heure locale est ce qu’une personne voit sur sa montre. « 9:00 » n’a de sens que si vous savez aussi où (et parfois quand) cela se passe.

Une répartition utile :

• Instant : un moment précis (utile pour logs, paiements, rappels).
• Temps calendaire : une date et une heure murale comme « Lundi à 9:00 » (utile pour les plans humains).
• Fuseau horaire : les règles qui transforment un instant en heure locale.

Un offset n’est qu’un nombre comme UTC-5. Il indique la différence par rapport à UTC maintenant, mais n’inclut pas les changements futurs ou passés des règles DST.

Une zone nommée (zone IANA) est une étiquette comme « America/New_York ». Elle contient l’ensemble des règles, y compris quand le DST commence et se termine.

Les événements récurrents sont le cas spécial qui piège les équipes. « Chaque mardi à 9:00 à Paris » devrait rester à 9:00 heure de Paris, même si l’instant UTC correspondant change quand le DST bouge.

Que stocker dans la base (et quoi éviter)

Beaucoup de bugs viennent d’un mauvais modèle de données. Si vous stockez la « version d’affichage » du temps (une chaîne formatée ou un offset brut), vous perdez l’information nécessaire pour prendre des décisions correctes plus tard.

Quand un événement est un moment spécifique dans le temps (un webinaire qui commence à un instant unique mondialement), stockez-le en UTC. Cela signifie typiquement des timestamps comme starts_at_utc et ends_at_utc.

Quand un événement doit suivre des règles locales (comme « tous les lundis à 9:00 à New York »), stockez l’ID de zone, pas seulement l’offset. Utilisez un nom de zone IANA comme America/New_York, parce que les offsets changent avec le DST et parfois aussi par décision légale.

Il aide aussi de stocker la date et l’heure locale originales que la personne a saisies. Cela préserve l’intention et rend les modifications prévisibles. Par exemple, si quelqu’un choisit « 2026-03-08 09:00 » en America/Los_Angeles, vous voulez vous souvenir de ce choix local même si l’instant UTC correspondant bouge autour des frontières DST.

Un ensemble pratique de champs à considérer :

• zone_id (nom IANA) pour tout horaire lié à un lieu
• local_date et local_time pour l’heure murale voulue par l’utilisateur
• starts_at_utc (et ends_at_utc) quand l’événement est un instant fixe
• created_offset_minutes (optionnel) pour audit/debug, pas comme source de vérité
• timezone_version ou un timestamp « rules updated at » (optionnel) si votre plateforme le supporte

Évitez de ne stocker que l’offset comme -0500, surtout pour des événements futurs. Il ne vous dit pas quel ensemble de règles DST appliquer et sera faux une partie de l’année.

Pour le débogage, loggez trois choses ensemble : l’ID de zone, l’offset au moment de la création, et l’instant UTC calculé. Sans ces trois éléments, les rapports « ça a bougé d’une heure » deviennent souvent du travail de déduction.

Choisir le bon modèle pour chaque type d’horaire

La plupart des bugs de planification viennent d’un décalage : vous stockez un type de temps, mais les utilisateurs en attendent un autre. Avant d’écrire du code, décidez quel modèle vous construisez.

Modèle 1 : Instant fixe (un moment réel)

Utilisez-le quand l’événement doit avoir lieu au même moment partout. Stockez-le comme un instant (timestamp UTC) et conservez une zone uniquement pour l’affichage.

Un vol partant le 2026-03-10 14:00 de JFK est un instant fixe. Si un voyageur le voit à Londres, l’heure affichée change, mais le moment ne change pas.

Modèle 2 : Heure locale flottante (même heure murale dans un lieu)

Utilisez-le quand l’événement est lié à une horloge locale, pas à un instant global. Stockez la date locale, l’heure locale, et la zone IANA (comme « America/New_York »). Résolvez en un instant seulement quand vous devez planifier des jobs ou envoyer des rappels.

Un réveil quotidien à 07:00 est une heure locale flottante. On s’attend à ce qu’il reste à 07:00 même quand le DST commence ou se termine.

Si vous n’êtes pas sûr du modèle adapté, posez-vous :

• L’événement doit-il avoir lieu au même instant pour tout le monde ?
• Ou doit-il avoir lieu à la même heure murale dans un lieu donné ?
• Si un utilisateur change de fuseau sur son appareil, l’événement doit‑il bouger ?
• Quand le DST change, l’heure murale doit‑elle rester la même ou l’instant doit‑il rester le même ?

Pour des invitations entre zones, stockez l’intention de l’organisateur. Si l’organisateur a choisi « 9:00 AM heure de New York », stockez cette zone et cette heure locale. Chaque participant peut la voir dans son propre fuseau, mais la règle source reste claire.

Écrivez la règle dans des commentaires de code et dans les noms : par exemple startsAtUtc pour les instants fixes, ou localStartTime + timeZoneId pour les horaires flottants. Cette décision unique évite que de futures « améliorations utiles » réintroduisent des surprises DST.

Afficher l’heure locale sans surprendre

Beaucoup de bugs apparaissent dans l’UI, pas dans la base. Un choix sûr : conservez l’UTC (ou l’instant) tout au long de l’app, et convertissez dans le fuseau du visualiseur au dernier moment, juste avant l’affichage.

Ce « dernier moment » compte. Si vous convertissez plus tôt (par exemple dans une réponse API ou dans la logique métier), il est facile de reconvertir deux fois plus tard ou d’obtenir des formats différents selon les écrans. Choisissez un endroit unique pour le formatage d’affichage (souvent le frontend) et réutilisez le même formateur partout pour qu’un événement apparaisse identique en liste, détail, e‑mail et notification.

Quand la confusion est probable, affichez la zone. Un simple « 9:00 » suffit pour un rappel personnel, mais c’est risqué pour des horaires partagés. Utilisez des formats comme « 9:00 AM PT » ou « 9:00 AM (America/Los_Angeles) » dans les invitations, panneaux admin et éléments cross‑équipe. Les abréviations peuvent être ambiguës (CST signifie plusieurs choses), donc utilisez le nom complet quand les enjeux sont élevés.

Si un utilisateur n’a pas de fuseau enregistré, prenez par défaut le fuseau de l’appareil, mais rendez-le visible et facile à modifier. Les gens voyagent. Les équipes sont distribuées. « Mon appareil s’est trompé » est un vrai ticket support.

Les heures ambiguës lors du retour d’heure méritent une attention particulière. « 1:30 AM » se produit deux fois quand les horloges reculent. Si un utilisateur choisit une heure ce jour-là, avertissez‑le et proposez un choix clair, par exemple « 1:30 AM (avant le changement) » vs « 1:30 AM (après) », ou affichez l’offset UTC.

Gérer les sauts DST et les heures ambiguës

Le Daylight Saving Time expose beaucoup de systèmes de planification. Le plus délicat est que le changement d’heure peut rendre une heure locale impossible ou ambiguë, même si elle semble normale pour une personne.

Au « spring forward », une heure est sautée. Dans de nombreux lieux, 2:30 AM n’existe tout simplement pas ce jour-là. Si un utilisateur choisit une heure manquante, l’app doit faire quelque chose d’explicite au lieu de créer silencieusement un mauvais timestamp.

Au « fall back », une heure se répète. Une heure comme 1:30 AM a lieu deux fois, une fois avant et une fois après le recul des horloges. Cela rend l’heure locale ambiguë à moins de savoir quelle occurrence l’utilisateur voulait.

Une politique cohérente

Choisissez une politique et appliquez‑la partout (création, édition, import, API).

• Pour les heures manquantes (printemps) : avancez vers la prochaine heure valide, ou bloquez et demandez à l’utilisateur de choisir.
• Pour les heures répétées (automne) : choisissez la première occurrence (la plus tôt) ou la seconde (la plus tardive), ou demandez quand c’est important (paiements, échéances).
• Si vous résolvez automatiquement, affichez une petite confirmation comme « Ajusté à 3:00 AM à cause du DST. »
• Stockez toujours le nom de zone de l’utilisateur (par exemple America/New_York), pas seulement un offset.
• Enregistrez le choix de résolution pour que le même événement ne change pas ultérieurement.

Après avoir choisi, persistez ce que vous avez décidé. Par exemple, stockez « préférer plus tôt » vs « préférer plus tard » pour cet événement (certaines bibliothèques appellent ça un fold flag). Sans cela, un utilisateur modifiant l’événement des mois plus tard pourrait voir l’heure basculer vers l’autre occurrence.

Exemple : quelqu’un programme « 3 nov, 1:30 AM » à New York. Si votre app choisit toujours la première 1:30 AM, gardez cette décision attachée à l’événement. Si vous recalculer plus tard à partir de zéro, cela pourrait devenir la seconde 1:30 AM et décaler la réunion d’une heure.

Étape par étape : construire un flux de planification résistant au DST

Les fonctionnalités de planification échouent quand elles confondent un instant fixe et une « heure murale » attendue localement. Un flux fiable commence par choisir le modèle, puis capturer suffisamment d’informations pour recréer l’intention de l’utilisateur des mois plus tard.

Un flux de planification sûr pour le DST

• Classez l’événement : instant fixe ou heure locale flottante.
• Quand l’utilisateur choisit une heure, stockez la date/heure locale plus l’ID de zone complet (par exemple America/New_York), pas seulement un offset comme -05:00.
• Avant d’enregistrer, validez l’heure locale selon les règles de la zone : gérez les gaps DST (heure inexistante) et les overlaps (heure double) selon votre politique.
• Persistez le timestamp UTC pour l’exécution effective, et conservez le zone ID et les champs locaux originaux quand vous devez afficher « ce que l’utilisateur a choisi ».
• Lors de l’affichage, convertissez depuis l’UTC vers le fuseau du visualiseur et étiquetez quand l’ambiguïté compte (par exemple « 10:00 AM New York time »).

La règle unique à choisir

Lors d’un gap de printemps, rejetez‑vous l’heure et demandez à l’utilisateur de choisir à nouveau, ou la déplacez‑vous automatiquement vers la minute valide suivante ? Lors du chevauchement d’automne, choisissez‑vous l’occurrence plus tôt, la plus tardive, ou demandez‑vous ?

Choisissez une conduite, rédigez‑la clairement, et appliquez‑la de façon cohérente aux flux de création, modification et renvoi.

Erreurs courantes qui provoquent des bugs de DST et fuseaux

Ces bugs commencent souvent petit : un raccourci dans le traitement des dates qui semble inoffensif jusqu’à ce qu’un utilisateur rencontre un changement DST ou ouvre l’app depuis une autre région.

Les erreurs les plus fréquentes :

• Stocker l’heure locale sans la zone. Sauvegarder 2026-03-08 09:00 sans aussi enregistrer la zone IANA (comme America/New_York) vous force à deviner plus tard.
• Utiliser accidentellement le fuseau du serveur. « Parse une date, crée un Date object, sauvegarde » peut fonctionner en dev et bouger en prod si le serveur/conteneur a un fuseau différent.
• Ajouter 24 heures pour dire « demain ». now + 24h n’est pas la même chose que « même heure locale demain » pendant les changements DST.
• Supposer que les offsets ne changent jamais. Des gens codent en dur -0500 et passent à autre chose. Les offsets résultent des règles de zone, pas de l’identité d’une zone, et ces règles peuvent changer.
• Parser des chaînes dépendant du locale ou des caprices du navigateur. Des entrées comme 03/04/2026 9:00 peuvent signifier des dates différentes suivant les réglages, et certains navigateurs acceptent des formats que d’autres refusent.

Une défaillance fréquente : un utilisateur programme « 9:00 AM chaque lundi » à New York. Si vous ne stockez qu’un offset (UTC-5) au lieu de la zone, l’événement dérivera d’une heure après le début du DST, alors que l’utilisateur s’attend à ce qu’il reste à 9:00.

Comment écrire des tests qui ne cassent pas deux fois par an

Les bugs de fuseau et DST apparaissent souvent seulement en mars et novembre (ou fin mars / fin octobre en Europe). La solution n’est pas « plus de tests », c’est les bons tests, exécutés de la même manière sur toutes les machines.

Rendre le temps déterministe

Éliminez les dépendances cachées. Dans chaque test, figez l’horloge et définissez un fuseau explicite. Ne vous fiez pas au laptop du développeur, au runner CI ou aux valeurs par défaut du conteneur.

Une habitude simple : construisez des dates de test à partir d’instants UTC connus, et déclarez toujours la zone dans laquelle vous convertissez.

Couvrez volontairement les dates problématiques

Choisissez au moins une zone US et une zone EU et testez à la fois le saut de printemps (heure manquante) et le chevauchement d’automne (heure répétée). Ajoutez ensuite des cas que les équipes oublient souvent :

• Heure locale invalide (gap du printemps) : une heure locale qui n’existe pas
• Heure locale ambiguë (chevauchement d’automne) : la même heure murale correspondant à deux instants
• Événements récurrents qui traversent la frontière : générez 8–12 semaines et vérifiez chaque occurrence
• Snapshots de formatage UI : vérifiez les chaînes rendues sous différents locales et zones

Par exemple, testez une réunion hebdo à 09:30 en America/New_York. Quand le DST commence, l’heure UTC changera mais l’heure locale doit rester 09:30. Quand le DST se termine, assurez‑vous que 01:30 est gérée selon votre règle choisie (première occurrence vs seconde) et que cette règle est vérifiée dans les tests.

Incluez au moins un test end‑to‑end réaliste qui crée, stocke et réaffiche l’événement. Cela attrape les décalages entre stockage DB, sérialisation API et formatage UI.

Scénario d’exemple : réunion hebdo à travers le DST pour une équipe distante

Un manager à New York crée une réunion hebdo : chaque lundi à 9:00 AM. Les participants sont à Londres et Phoenix. Tout le monde s’attend à ce que la réunion reste à 9:00 AM heure de New York, même quand les horloges changent.

Voici ce que fait souvent la logique naïve : l’app sauvegarde la première occurrence comme un timestamp UTC (par exemple 14:00 UTC) puis répète en ajoutant 7 jours en UTC. Ça paraît correct jusqu’au changement DST.

• Spring forward : New York passe de UTC-5 à UTC-4. Si vous continuez à répéter 14:00 UTC, la réunion devient 10:00 AM à New York.
• Fall back : New York passe de UTC-4 à UTC-5. Répéter le même UTC fait apparaître la réunion à 8:00 AM localement.

Le comportement correct commence par stocker la zone et la règle, pas seulement un timestamp. Pour une réunion hebdo, enregistrez par exemple : zone = America/New_York, weekday = Monday, local time = 09:00, frequency = weekly. Ensuite, calculez chaque occurrence pour cette zone et convertissez en UTC uniquement pour la livraison (invites calendrier, rappels, payloads API).

Londres verra le décalage d’une heure pendant les semaines où les US et le UK changent à des dates différentes. Phoenix (sans DST) verra aussi des décalages. C’est attendu quand la règle est « 9:00 AM New York time ».

Un libellé clair pour l’utilisateur évite la confusion. Affichez la zone quand c’est important et confirmez la règle en termes simples :

• Affichage : « Lun 9:00 AM (New York time) »
• Confirmation : « Répète chaque lundi à 9:00 AM America/New_York. Les heures peuvent différer pour les coéquipiers dans d’autres fuseaux lors des changements d’heure d’été. »

Checklist rapide avant de déployer une fonctionnalité de planification

Les bugs apparaissent souvent après le lancement, quand de vrais utilisateurs traversent des frontières ou que les horloges changent. Un contrôle rapide avant livraison peut vous éviter des semaines de support.

Vérifications du modèle de données

Pour chaque chose planifiée, répondez à : est‑ce un instant fixe, ou suit‑il des règles murales locales ?

• Instants fixes (rappels ponctuels, timestamps de logs) : stockez en UTC.
• Événements récurrents « heure locale » (ex. chaque lundi 9:00 à Berlin) : stockez l’heure locale + l’ID de zone IANA (par ex. Europe/Berlin), pas seulement un offset.
• Ne traitez jamais un offset numérique (ex. -05:00) comme un fuseau horaire.

Vérifications DST et côté utilisateur

Faites des cas limites DST une partie intégrante du comportement produit.

• Quand un utilisateur choisit une heure locale, détectez et gérez les heures invalides (gap du printemps) et ambiguës (répétition d’automne). Décidez : bloquer, ajuster ou demander.
• Tests : figez « maintenant » et définissez un fuseau explicite dans chaque test. Incluez au moins un cas début DST et un cas fin DST.
• UI et notifications : affichez le fuseau quand c’est crucial, surtout dans les e‑mails, les invitations calendrier et les rappels.

Prochaines étapes : corriger des bugs existants sans tout réécrire

Si votre fonction de planification est déjà en production, corriger les bugs DST consiste surtout à améliorer la visibilité, puis à durcir une couche à la fois. Pas besoin d’un gros rewrite pour arrêter l’hémorragie.

Commencez par un audit rapide des données. Cherchez des champs qui mélangent discrètement des concepts, comme une colonne start_time qui parfois contient du UTC, parfois de l’heure locale, ou des chaînes comme « 2026-01-16 09:00 » sans zone. Cherchez aussi des champs dupliqués (utc_time et local_time) où personne ne se souvient de la source de vérité.

Ajoutez des logs légers autour de chaque conversion. Quand un utilisateur signale « ça a bougé d’une heure », vous voulez des preuves de ce que le système a décidé :

• Logguez la zone IANA de l’utilisateur (par ex. America/New_York), pas seulement un offset.
• Logguez l’offset utilisé à cet instant (pour la visibilité DST).
• Logguez la valeur d’entrée et le résultat UTC calculé.
• Logguez le chemin de rendu (valeur stockée en UTC -> affichage local).

Corrigez ensuite par ordre d’impact utilisateur : d’abord l’affichage et les écrans de confirmation, puis les règles de stockage, puis la logique de récurrence.

Si vous avez hérité d’un code généré par l’IA, supposez que la gestion du temps est incohérente partout. Conversions cachées, valeurs par défaut de bibliothèques et tests qui ne passent que hors semaines DST sont fréquents.

Si vous avez besoin d’un deuxième regard rapide, FixMyMess (fixmymess.ai) est conçu pour diagnostiquer et réparer du code applicatif généré par l’IA, y compris la logique de planification qui casse autour du DST. Un audit court suffit souvent à repérer où offsets, zones et conversions se sont mélangés.