docs: architecture, ADR 0019, guide utilisateur et changelog #332

New issue

Closed

opened 2026-08-12 20:14:34 +00:00 by maximus · 0 comments

maximus commented

2026-08-12 20:14:34 +00:00

Owner

Refs: spec-decisions-import-csv-format.md + spec-plan-import-csv-format.md (racine du repo).

Contexte

Dernier maillon de la pile. Le CHANGELOG est centralise ici plutot que reparti sur les neuf issues precedentes : chaque maillon touche les memes fichiers, et une entree par PR garantirait un conflit a chaque rebase.

Taches

docs/architecture.md : migration v17 et les quatre colonnes, couche de detection lexicale, signatures de banques, nouvelle etape du wizard, sources et modeles dans le format SREF. Mettre a jour le compte de migrations (v1->v17)
docs/adr/0019-format-import-persiste.md — decision structurante : le format d'import est une donnee persistee integralement, jamais re-devinee. Documenter les trois voies de perte qui existaient (restauration en dur, derive d'en-tete, export de donnees) et pourquoi la composition d'un type ImportFormat unique les ferme structurellement. Inclure une ligne Spec: pointant les deux fichiers de spec force-ajoutes a la racine (precedent #295 : les specs sont gitignorees, une ligne Spec: non force-add donne un 404)
docs/guide-utilisateur.md : nouveau parcours d'import (detection automatique, score, apercu obligatoire, inversion des signes, formats de banques reconnus)
Cles docs.* FR et EN correspondantes
CHANGELOG.md et CHANGELOG.fr.md sous [Unreleased] — categories Added / Changed / Fixed, couvrant les neuf issues precedentes

Criteres d'acceptation

docs/architecture.md decrit v17 et le compte de migrations est juste
ADR 0019 redige, statut Accepted, ligne Spec: valide
Les deux CHANGELOG portent les memes entrees, traduites

Depends on #331

Revision /review-spec — 2026-08-13

Corrections a appliquer, issues de la revue 3 experts :

ADR 0019 : documenter que template_id est une etiquette de provenance, jamais relue comme format (decision tranchee), et que la garantie de completude du format vient du codec formatToRow/formatFromRow et de son test, pas d'un type compose.
Ajouter git add -f spec-decisions-import-csv-format.md spec-plan-import-csv-format.md a la checklist, AVANT d'ecrire la ligne Spec: de l'ADR — .gitignore:71-72 ignore ces deux patterns, et l'ADR 0016 a livre une ligne Spec: morte pour cette raison exacte (corrige par force-add en PR #295).
docs/architecture.md : mentionner les CHECK des deux colonnes d'enumeration et le module de dictionnaire lexical distinct de csvAutoDetect.ts.

Fichiers concernes

docs/architecture.md
docs/adr/0019-format-import-persiste.md — creer
docs/guide-utilisateur.md
src/i18n/locales/fr.json + en.json — cles docs.*
CHANGELOG.md + CHANGELOG.fr.md

Decisions prises en planification

Emplacement du code partage : le codec formatToRow/formatFromRow et mapRow vivent dans src/utils/importFormat.ts — meme dossier que amountParser, dateParser et csvAutoDetect, qui portent deja la logique pure du domaine. Les types restent dans src/shared/types/.
Aucune correction retroactive des transactions deja importees a l'envers : la voie de reparation est deleteImportWithTransactions puis re-import. Ne jamais muter des montants deja ecrits.
L'import reste entierement en edition Free — aucun gating a ajouter.
Les specs spec-decisions-import-csv-format.md et spec-plan-import-csv-format.md sont committees a la racine (force-add, precedent PR #295) : elles sont lisibles depuis un worktree.

Spec source

spec-plan-import-csv-format.md + spec-decisions-import-csv-format.md (racine du repo, committees).

Refs: `spec-decisions-import-csv-format.md` + `spec-plan-import-csv-format.md` (racine du repo). ## Contexte Dernier maillon de la pile. Le CHANGELOG est centralise ici plutot que reparti sur les neuf issues precedentes : chaque maillon touche les memes fichiers, et une entree par PR garantirait un conflit a chaque rebase. ## Taches - [ ] `docs/architecture.md` : migration v17 et les quatre colonnes, couche de detection lexicale, signatures de banques, nouvelle etape du wizard, sources et modeles dans le format SREF. Mettre a jour le compte de migrations (v1->v17) - [ ] `docs/adr/0019-format-import-persiste.md` — decision structurante : le format d'import est une donnee persistee integralement, jamais re-devinee. Documenter les trois voies de perte qui existaient (restauration en dur, derive d'en-tete, export de donnees) et pourquoi la composition d'un type `ImportFormat` unique les ferme structurellement. Inclure une ligne `Spec:` pointant les deux fichiers de spec **force-ajoutes a la racine** (precedent #295 : les specs sont gitignorees, une ligne `Spec:` non force-add donne un 404) - [ ] `docs/guide-utilisateur.md` : nouveau parcours d'import (detection automatique, score, apercu obligatoire, inversion des signes, formats de banques reconnus) - [ ] Cles `docs.*` FR et EN correspondantes - [ ] `CHANGELOG.md` et `CHANGELOG.fr.md` sous `[Unreleased]` — categories Added / Changed / Fixed, couvrant les neuf issues precedentes ## Criteres d'acceptation - [ ] `docs/architecture.md` decrit v17 et le compte de migrations est juste - [ ] ADR 0019 redige, statut Accepted, ligne `Spec:` valide - [ ] Les deux CHANGELOG portent les memes entrees, traduites Depends on #331 --- ## Revision /review-spec — 2026-08-13 Corrections a appliquer, issues de la revue 3 experts : - **ADR 0019** : documenter que `template_id` est une **etiquette de provenance**, jamais relue comme format (decision tranchee), et que la garantie de completude du format vient du codec `formatToRow`/`formatFromRow` et de son test, pas d'un type compose. - **Ajouter `git add -f spec-decisions-import-csv-format.md spec-plan-import-csv-format.md` a la checklist**, AVANT d'ecrire la ligne `Spec:` de l'ADR — `.gitignore:71-72` ignore ces deux patterns, et l'ADR 0016 a livre une ligne `Spec:` morte pour cette raison exacte (corrige par force-add en PR #295). - `docs/architecture.md` : mentionner les `CHECK` des deux colonnes d'enumeration et le module de dictionnaire lexical distinct de `csvAutoDetect.ts`. --- ## Fichiers concernes - `docs/architecture.md` - `docs/adr/0019-format-import-persiste.md` — **creer** - `docs/guide-utilisateur.md` - `src/i18n/locales/fr.json` + `en.json` — cles `docs.*` - `CHANGELOG.md` + `CHANGELOG.fr.md` ## Decisions prises en planification - **Emplacement du code partage** : le codec `formatToRow`/`formatFromRow` et `mapRow` vivent dans `src/utils/importFormat.ts` — meme dossier que `amountParser`, `dateParser` et `csvAutoDetect`, qui portent deja la logique pure du domaine. Les types restent dans `src/shared/types/`. - **Aucune correction retroactive** des transactions deja importees a l'envers : la voie de reparation est `deleteImportWithTransactions` puis re-import. Ne jamais muter des montants deja ecrits. - **L'import reste entierement en edition Free** — aucun gating a ajouter. - Les specs `spec-decisions-import-csv-format.md` et `spec-plan-import-csv-format.md` sont **committees a la racine** (force-add, precedent PR #295) : elles sont lisibles depuis un worktree. ## Spec source `spec-plan-import-csv-format.md` + `spec-decisions-import-csv-format.md` (racine du repo, committees).