Simpl-Resultat/docs/adr/0019-format-import-persiste.md

ADR 0019 — Le format d'import est une donnée persistée intégralement, jamais re-devinée

• Status: Accepted
• Date: 2026-08-13
• Issues: #326 (corpus de fixtures figeant le comportement fautif), #323 (migration v17), #324 (codec formatToRow/formatFromRow, racine du bug), #325 (règle débit/crédit + parseur ancré), #327 (détection lexicale par libellé), #328 (score de confiance + détection autonome), #329 (aperçu obligatoire + recap signé), #330 (signatures de banques + dérive d'en-tête), #331 (sources et modèles dans le format SREF), #332 (cette doc)
• Spec: spec-decisions-import-csv-format.md, spec-plan-import-csv-format.md
• Prolonge ADR 0003 (migrations SQL inline additives) pour la migration v17

Contexte

Un import CSV transforme une cellule de texte en un montant signé au grand livre. Deux informations décident du signe, et elles seules :

• amount_mode — le fichier porte-t-il un montant unique, ou deux colonnes débit et crédit ?
• sign_convention — en montant unique, une dépense s'écrit-elle négative ou positive ?

Ces deux champs vivaient sur import_config_templates mais pas sur import_sources. La source — la configuration réellement utilisée à chaque import — ne portait que les réglages mécaniques (délimiteur, encodage, format de date, mapping de colonnes). L'asymétrie était structurelle, et le code la comblait en devinant : useImportWizard.ts:321-323 ré-inférait le mode depuis mapping.debitAmount !== undefined et écrivait signConvention: "negative_expense" en dur.

Une source de carte de crédit configurée en dépenses positives revenait donc sur la convention par défaut à son deuxième import, et chaque montant était nié : les dépenses arrivaient en revenus. Sans erreur, sans avertissement, et sans contrôle agrégé capable de le voir — un signe inversé ne fait que changer le signe du total.

Le défaut n'avait pas une voie mais trois, indépendantes l'une de l'autre :

1. La restauration en dur. Recharger une source configurée écrasait sa convention par la valeur codée en dur (#324).
2. La dérive d'en-tête. La banque déplace, renomme ou ajoute une colonne ; le mapping mémorisé continue de pointer sur des positions qui ne désignent plus les mêmes données, et l'import passe sans rien signaler (#330).
3. L'export de données. dataExportService ne sérialisait ni les sources ni les modèles, puis exécutait DELETE FROM import_sources à la restauration et les remplaçait par une source synthétique « Data Import ». Restaurer une sauvegarde détruisait toute configuration d'import (#331).

Les trois produisent la même classe de panne — un format perdu, remplacé par une supposition — et une correction ponctuelle sur l'une n'apprend rien aux deux autres.

Décision

Le format d'import est une valeur persistée intégralement sur import_sources, lue telle quelle, jamais re-inférée. Quatre règles la tiennent.

1. La base porte le format en entier (migration v17)

v17 ajoute quatre colonnes à import_sources, en additif pur (v1→v16 intactes) :

Colonne	Définition
amount_mode	TEXT NOT NULL DEFAULT 'single' + CHECK (amount_mode IN ('single','debit_credit','absolute_indicator'))
sign_convention	TEXT NOT NULL DEFAULT 'negative_expense' + CHECK (sign_convention IN ('negative_expense','positive_expense'))
header_signature	TEXT — libellés normalisés de l'en-tête du dernier import réussi (détection de dérive)
template_id	INTEGER REFERENCES import_config_templates(id) ON DELETE SET NULL

Le CHECK d'amount_mode admet absolute_indicator dès maintenant : le troisième mode de montant pourra être livré sans nouvelle migration, tandis que la base refuse déjà toute valeur corrompue. Le backfill (UPDATE … WHERE column_mapping LIKE '%debitAmount%') reproduit exactement ce que le code déduisait à la volée — v17 ne change aucun comportement observable. sign_convention n'est délibérément pas backfillée : son DEFAULT restitue précisément la valeur que le code codait en dur, la seule convention passée qui puisse être inférée ; en deviner une autre réécrirait silencieusement du sens.

LIKE plutôt que json_extract, pour que la migration ne dépende d'aucune extension JSON1 dans le SQLite embarqué.

2. Un codec unique, pas un type composé

La garantie de complétude vient de src/utils/importFormat.ts, seul point de conversion entre :

• ImportFormatRow — la forme persistée (snake_case, mapping en JSON, has_header normalisé en 0/1) ;
• ImportFormat — la forme domaine consommée par le wizard et par mapRow.

Un type ImportFormat composé, partagé par les deux porteurs, était l'approche naturelle et elle est structurellement impossible : ImportSource.has_header est déclaré boolean, ImportConfigTemplate.has_header est un number, et SourceConfig est camelCase sur un mapping déjà parsé. Les porteurs sont incompatibles ; le point de passage, lui, peut être unique.

Ce qui donne des dents au codec est son test de complétude, sur deux niveaux :

• FORMAT_FIELD_PAIRS est typé Record<keyof ImportFormat, keyof ImportFormatRow> — un champ ajouté au format ne compile pas tant qu'il n'y figure pas ;
• le test compare les clés réellement produites par chaque sens du codec à cette table — un champ déclaré mais non câblé fait échouer le test.

Supprimer sign_convention de formatToRow — la forme exacte du bug d'origine — fait tomber 14 tests. Les deux écrivains de modèles passent aussi par le codec, pour qu'un nouveau champ ne puisse pas atteindre une table et manquer l'autre.

formatFromRow lève sur une valeur qu'il ne sait pas lire au lieu de retomber sur un défaut : retomber sur la branche single lirait la mauvaise colonne à chaque ligne, et toute valeur autre que positive_expense signifierait silencieusement negative_expense. L'erreur porte une clé i18n et le wizard s'ouvre alors sur une configuration neuve — bloquer le wizard rendrait « reconfigurer cette source » impossible.

3. template_id est une étiquette de provenance, jamais relue comme format

Un modèle sert à initialiser une source ; il ne la gouverne pas. template_id est enregistré, restauré et affiché, mais jamais relu pour dériver un format. Éditer un modèle ne change aucune source liée — c'est un critère d'acceptation testé de bout en bout, avec vérification de non-vacuité (le modèle a bien changé). ON DELETE SET NULL : supprimer le modèle efface l'étiquette et laisse le format intact.

La raison est la même que celle du reste de l'ADR : si le format se déduisait du modèle, il redeviendrait une valeur devinée, portée par une ligne que l'utilisateur peut modifier ailleurs et à un autre moment.

4. Le format persisté gagne, et les deux autres voies de perte sont fermées

• Détection — elle se déclenche seule sur une source sans format enregistré, et jamais sur une source qui en a un (garde !existing). Le bouton baguette reste, pour la rejouer à la demande. Une source dont le format stocké échoue à décoder émet son erreur explicite plutôt qu'une nouvelle supposition.
• Dérive d'en-tête — header_signature stocke les libellés normalisés du dernier import réussi, en tableau JSON et non en hachage : le panneau doit pouvoir nommer les colonnes qui ont bougé (« Montant : colonne 3 → 4 »). Un en-tête qui normalise différemment ouvre FormatDriftPanel au-dessus de l'aperçu, avec les deux seules issues qui existent — adopter le format re-détecté ou conserver celui enregistré. Un simple renommage cosmétique normalise à l'identique et ne dit rien. Une source dont les fichiers n'ont pas de ligne d'en-tête garde header_signature à NULL et la détection de dérive y est inopérante : c'est documenté, pas contourné — une signature inventée depuis les données se déclencherait à chaque import.
• Export/import de données — import_sources et import_config_templates sont sérialisés dans l'enveloppe SREF derrière un format_version explicite. Les modèles sont restaurés avant les sources (template_id est une clé étrangère), upsertés par nom, et template_id est remappé sur les identifiants résolus. Le wipe et la restauration sont enveloppés dans withTransaction.

Alternatives considérées

• Un type ImportFormat composé, partagé par les deux tables. Rejeté : impossible sans réécrire les deux porteurs (has_header boolean d'un côté, number de l'autre, mapping parsé vs JSON). Le codec obtient la même garantie sans toucher aux formes existantes, et son test la rend vérifiable — ce qu'un type partagé n'aurait pas donné à lui seul.
• Backfiller sign_convention en devinant depuis les données (ex. « majorité de montants négatifs ⇒ negative_expense »). Rejeté : c'est exactement la re-inférence que cet ADR supprime, appliquée une fois pour toutes et sans possibilité de la relire. Le DEFAULT restitue la seule convention réellement en vigueur avant v17.
• Dériver le format depuis template_id. Rejeté : voir la règle 3 — cela redonne au format un porteur mutable ailleurs.
• Hacher header_signature. Rejeté : un hachage détecte la dérive mais ne peut pas la décrire, et le panneau de dérive n'aurait plus rien à montrer que « ça a changé ».
• Corriger rétroactivement les transactions déjà importées à l'envers. Rejeté : on ne mute jamais des montants déjà écrits. La voie de réparation est deleteImportWithTransactions puis re-import — RepairPathNotice l'énonce dans l'interface, parce que ré-importer par-dessus double les lignes (findDuplicates apparie sur date + description + montant, donc une ligne corrigée ne s'apparie pas à la fautive).

Conséquences

• Positif. Le format d'une source est lisible en base et rejoué à l'identique. Le codec et son test forment le point de contrôle unique : ajouter un champ de format sans le persister ne compile pas, ou ne passe pas. Les trois voies de perte sont fermées par construction, pas par vigilance.
• Positif. L'aperçu signé, obligatoire à chaque import, montre ce que le format signifie (sorties, entrées, totaux signés, lignes en erreur) — un score de lecture parfait ne dit rien du signe.
• Coût. Une source dont le format enregistré est illisible (valeur hors CHECK arrivée par un chemin non prévu, JSON corrompu) affiche une erreur et repart sur une configuration neuve, au lieu de continuer sur un défaut. C'est le comportement voulu, mais c'est un arrêt visible là où il y avait un silence.
• Coût. header_signature n'est écrite qu'à l'import réussi et reste NULL pour les fichiers sans en-tête : la détection de dérive ne couvre pas ces sources.
• À surveiller. Le CHECK d'amount_mode admet absolute_indicator, que l'application refuse aujourd'hui avec un message dédié plutôt que de l'importer de travers. Le jour où ce mode sera livré, le codec devra l'accepter — la migration, elle, n'est pas à refaire.
• Portée. Les modules d'import restent entièrement en édition Gratuite ; ce chantier n'ajoute aucun gating (ADR 0017).

Liens

• Spec : spec-decisions-import-csv-format.md, spec-plan-import-csv-format.md
• ADR 0003 — migrations SQL inline via tauri-plugin-sql (v17 en suit la convention additive)
• ADR 0004 — chiffrement de l'enveloppe SREF, dont le format_version est étendu par #331
• docs/architecture.md — section « Import CSV — format persisté et détection »