Enregistrement : le grand livre qui survit au redémarrage

1. Contexte & Objectif de Terrain : un classeur dans une pièce qu’on repeint

Un enregistrement qualité se juge à une chose : on le retrouve intact le jour de l’audit. Imaginez un classeur rangé dans une pièce de l’atelier. Un jour, on repeint la pièce et on la vide. Le classeur disparaît avec les cartons.

Mon bot tient un grand livre : les achats effectués et quelques indicateurs de rentabilité, dans un fichier au format Markdown. Il tourne dans un conteneur Docker. Le fichier était écrit dans le dossier de travail du conteneur, c’est-à-dire dans la pièce qu’on repeint.

L’objectif : que ce livre survive à toute recréation du conteneur, avant d’y enregistrer de vrais achats.

2. Anatomie de l’Échec & Fausses Pistes : trois frictions, dont un test qui mentait

Le livre était perdu à chaque recréation du conteneur. C’était déjà le cas chez l’ancien hébergeur. Rien n’avait cassé : le dispositif faisait exactement ce qu’on lui demandait, à savoir repartir d’une pièce vide.

Un test comptait les occurrences d’un identifiant. Il était fragile : l’identifiant d’un achat figure aussi dans le titre de sa ligne, donc le compte doublait. La bonne mesure consiste à compter des lignes, pas des occurrences d’un mot.

Un piège d’encodage. Une commande PowerShell qui lit un fichier avec Get-Content puis l’écrit avec Set-Content, sans préciser l’encodage en lecture, abîme les accents d’un fichier UTF-8. La lecture doit déclarer l’encodage.

Trois mots utiles : image, conteneur, volume. Une image est le moule. Le conteneur est la pièce fabriquée à partir de ce moule, et tout ce que le conteneur écrit pendant sa vie reste dans la pièce. Recréer le conteneur, c’est fabriquer une nouvelle pièce à partir du moule : ce qui avait été écrit dedans disparaît. Un volume est un espace de stockage rattaché séparément, qui survit à la pièce.

3. Décryptage Méthodologique par l’Analogie QSE : la feuille volante et l’armoire d’archivage

Deux réflexes d’atelier résolvent le problème.

L’armoire hors de l’atelier. Les enregistrements importants ne restent pas dans la pièce de production. Dans le monde du conteneur, cette armoire s’appelle un volume : un espace de stockage qui survit à la recréation du conteneur. Le chemin du livre devient un réglage, placé sur ce volume.

La feuille volante. On ne réécrit pas la page du classeur en direct. On rédige la nouvelle version sur une feuille volante. Quand elle est complète, on remplace la page. Si le stylo lâche en cours de route, la page du classeur reste intacte.

Une règle complète le tout : on ne remplace jamais un enregistrement existant par un modèle vierge. Le modèle ne sert que si le livre n’existe pas encore.

4. Le Pivot Architectural & L’Implémentation Déterministe : écrire à côté, puis remplacer

Quatre décisions, toutes simples :

1. Le chemin est un réglage (PROOF_OF_TRUTH_PATH). Par défaut, le comportement local ne change pas. Sur le serveur, le fichier docker-compose.yml le fixe sur le volume /data.
2. Création depuis un modèle, sans jamais écraser. Sur un volume sans livre, le livre est créé à partir du modèle de l’image. Un livre existant n’est jamais écrasé. Sans livre ni modèle, l’erreur nomme les deux chemins cherchés.
3. Écriture atomique : on écrit à côté, puis on remplace (code ci-dessous).
4. Un format simple. Un fichier Markdown lisible par un humain, sur le volume. Une base SQLite a été écartée pour l’instant : le fichier lisible suffit tant que le besoin d’une base n’est pas démontré.

L’écriture atomique tient en dix lignes :

def _write_atomic(path: Path, content: str) -> None:
    """Write to a sibling temp file, then replace: a crash never truncates the ledger."""
    path.parent.mkdir(parents=True, exist_ok=True)
    tmp = path.with_name(f"{path.name}.tmp")
    try:
        tmp.write_text(content, encoding="utf-8")
        os.replace(tmp, path)
    except BaseException:
        tmp.unlink(missing_ok=True)
        raise

Le fichier .tmp est écrit à côté du livre. Le remplacement (os.replace) est ensuite une opération indivisible : le livre est soit l’ancien, soit le nouveau, jamais un fichier tronqué. En cas d’échec, le fichier temporaire est supprimé.

Pourquoi écrire le fichier temporaire à côté du livre, et non ailleurs ? Le remplacement n’est indivisible que si les deux fichiers se trouvent sur le même espace de stockage. Un fichier voisin garantit cette condition. Ce détail est la différence entre une opération qui réussit ou échoue d’un bloc, et une copie qui peut s’arrêter à mi-chemin.

5. Données Chiffrées, Benchmarks & Résultats Mesurés : même empreinte avant et après

• 10 tests ajoutés ; la suite complète est au vert : 538 tests réussis sur 538.
• Preuve sur le serveur : un achat de test a été enregistré, puis le conteneur a été recréé de force (--force-recreate), son identifiant a changé. Le livre est identique au bit près : la même empreinte SHA-256 avant et après, et les indicateurs sont conservés. Le livre de test a ensuite été supprimé, la base de données est restée intacte.

Ce qui n’a pas été couvert : le parcours complet par Telegram (le bouton de confirmation), l’écriture concurrente, et le cas d’un livre corrompu. Ces trois cas restent des risques assumés, pas des problèmes résolus.

6. Déploiement Zéro-Terminal (Le Mode d’Emploi pour Marc) : un classeur maître et une feuille volante

Vous pouvez appliquer la même méthode à un fichier Excel de suivi, sans console.

1. Un fichier maître, rangé sur le lecteur partagé, pas sur le poste de travail.
2. Avant toute modification, « Enregistrer sous » une copie datée (par exemple suivi_2026-10-19.xlsx). C’est votre feuille volante.
3. Modifiez la copie, vérifiez les totaux, puis remplacez le fichier maître seulement si les totaux sont cohérents.
4. En cas de doute, le maître n’a pas bougé. Rien n’est perdu.

Exemple : le fichier maître s’appelle suivi_achats.xlsx. Avant toute modification, vous faites « Enregistrer sous » suivi_achats_2026-10-19.xlsx. Vous travaillez sur cette copie, vous vérifiez le total, puis vous la renommez suivi_achats.xlsx en acceptant de remplacer l’ancien fichier. Gardez les trois dernières copies datées : c’est votre historique, et votre marche arrière.

Un contrôle simple : notez le total clé du fichier (par exemple le capital engagé) avant et après la modification. S’il a changé sans raison, vous avez trouvé l’écart avant l’audit.

7. Les 3 Règles d’Or Actionnables & Conclusion : l’enregistrement ne voyage pas avec la pièce

1. Un enregistrement vit hors de la pièce de production. Chemin réglable, espace de stockage qui survit.
2. On écrit à côté, puis on remplace. Une coupure ne doit jamais tronquer l’enregistrement existant.
3. On ne remplace jamais un enregistrement par un modèle vierge. Le modèle ne sert qu’à créer, jamais à écraser.

Une preuve vaut mieux qu’une promesse : le même condensat avant et après. Il reste trois cas non couverts, annoncés comme tels. L’amélioration continue commence par cette honnêteté sur ce qu’on n’a pas encore vérifié.