Parcours de démarrage : cartes des étapes Catégories et Rapports #432

New issue

Closed

opened 2026-10-12 23:23:21 +00:00 by maximus · 0 comments

maximus commented

2026-10-12 23:23:21 +00:00

Owner

Les deux étapes de visite ajoutées par #425 (« Parcourir les catégories et les mots-clés », « Parcourir les rapports ») reçoivent leur carte sur /categories et /reports : explication, mise en évidence d'un contrôle, « J'ai compris ». Retours de Max sur la v0.17.1 (#422) ; textes validés par Max le 2026-10-12.

Planifié le 2026-10-12 (/plan-run, jalon planned-2026-10-12-retours-onboarding-v0171), après /analyze et une revue /review-spec (sécurité, architecture, technique) dont les constats sont intégrés ci-dessous. Corps autosuffisant : la spec (spec-plan-retours-onboarding-v0171.md) est locale et ignorée par git.

Préalable : ce jalon s'exécute après le merge de planned-2026-10-10-fiabilite-tests (#408, #409, #395, #389). Les numéros de ligne cités sont lus sur main à 8b5b3b1 et ont pu bouger : se fier aux noms de fonctions, aux clés et aux textes cités.

Travail à faire

src/utils/onboardingPath.ts : CARD_PAGES ajoute /categories et /reports ; PAGE_STEPS ajoute "/categories": ["categories"] et "/reports": ["reports"].
categoriesCardModel(checklist) : étape faite → { text: null, done: true, target: null } ; sinon phrase onboarding.card.categories avec labels: { allKeywords: "categories.allKeywords" }, cible "allKeywords".
reportsCardModel(checklist, advancedLocked) : étape faite → fait ; sinon onboarding.card.reports.locked si advancedLocked, onboarding.card.reports.all sinon, avec labels: { trends: "reports.hub.trends" }, cible "trendsCard". advancedLocked est celui de la page (src/pages/ReportsPage.tsx:17-18 : licenseReady && !advancedAllowed).
CategoriesPage : <OnboardingStepCard model={…} /> en tête de contenu, comme TransactionsPage.tsx:91 ; le bouton « Tous les mots-clés » (src/pages/CategoriesPage.tsx:47-57) reçoit onboardingTargetAttributes("categories-all-keywords", …) quand la carte s'affiche (showsStepCard). Jamais « Réinitialiser » : il supprime les mots-clés, déclasse toutes les transactions et recrée l'ancienne taxonomie (reinitializeCategories, src/services/categoryService.ts:215).
ReportsPage : la carte en tête ; HubReportNavCard (src/components/reports/HubReportNavCard.tsx) reçoit deux props optionnelles, onboardingTarget?: boolean (attributs onboardingTargetAttributes("reports-trends-card", …) sur son lien) et onNavigate?: () => void (appelée au clic, avant la navigation). Seule la carte Tendances les reçoit, et seulement tant que la carte d'étape s'affiche et que l'étape n'est pas faite : onNavigate={() => acknowledge("reports")} (acknowledge vient de useOnboarding(), ajouté par #425).
Après « J'ai compris » : « Fait. », puis « Étape suivante : Classer une transaction à la main → » sur Catégories, et le message de fin sur Rapports (logique cardNext existante ; ACKNOWLEDGE garde la carte, #425).
Textes et docs ci-dessous.

Textes (FR | EN)

Clé	FR	EN
`onboarding.card.categories`	Un mot-clé classe d'office, dès l'import, chaque transaction dont la description le contient ; quand deux mots-clés s'appliquent, le plus prioritaire l'emporte. « {{allKeywords}} » les liste tous, avec leur catégorie. À l'étape suivante, vous en ajouterez un depuis une transaction.	A keyword categorizes, as soon as it is imported, every transaction whose description contains it; when two keywords apply, the one with the higher priority wins. “{{allKeywords}}” lists them all, with their category. In the next step, you will add one from a transaction.
`onboarding.card.reports.all`	Choisissez la période en haut de la page : le panneau des faits saillants résume votre solde et vos plus gros mouvements. Chaque carte du bas ouvre un rapport détaillé ; commencez par « {{trends}} ».	Pick the period at the top of the page: the highlights panel sums up your balance and your biggest moves. Each card below opens a detailed report; start with “{{trends}}”.
`onboarding.card.reports.locked`	Choisissez la période en haut de la page : le panneau des faits saillants résume votre solde et vos plus gros mouvements. Chaque carte du bas ouvre un rapport détaillé ; commencez par « {{trends}} ». Les cartes à cadenas demandent l'édition Base.	Pick the period at the top of the page: the highlights panel sums up your balance and your biggest moves. Each card below opens a detailed report; start with “{{trends}}”. Cards with a padlock require the Base edition.

Docs.

Guide Markdown §1, la puce « Sur les pages Import, Transactions et Budget, quand l'étape suivante s'y fait… », et docs.gettingStarted.subsections[0].steps[2] (FR et EN) : « Sur les pages Import, Catégories, Transactions, Budget et Rapports » ; ajouter que, sur Catégories et Rapports, la carte se ferme par « J'ai compris », et que sur Rapports l'ouverture de la carte Tendances compte aussi.
docs/architecture.md, section Onboarding : pages à carte.
Liste QA docs/qa-onboarding.html : les deux cartes, leur cible, la variante Gratuite, « J'ai compris » puis l'étape suivante ou la fin, le clic sur Tendances.

Fichiers concernés

src/utils/onboardingPath.ts, src/utils/onboardingPath.test.ts
src/pages/CategoriesPage.tsx, src/pages/ReportsPage.tsx
src/components/reports/HubReportNavCard.tsx, src/components/reports/HubReportNavCard.render.test.tsx (nouveau)
src/i18n/locales/fr.json, src/i18n/locales/en.json
docs/guide-utilisateur.md, docs/architecture.md, docs/qa-onboarding.html
CHANGELOG.md, CHANGELOG.fr.md

Depends on

#425
#430

#425 apporte les étapes, acknowledge et le bouton « J'ai compris » ; #430 écrit la carte Transactions que la carte Catégories annonce.

Tests

stepsOfPage, cardStep sur /categories (5 sur 8 en Base+) et /reports (8 sur 8 ; 7 sur 7 en Gratuite) ; cardNext : après Catégories, l'étape suivante est manualCategory ; après Rapports, la fin.
categoriesCardModel et reportsCardModel : fait, variante all, variante locked, cibles.
HubReportNavCard : attributs de mise en évidence présents seulement avec onboardingTarget ; en appelant le composant comme une fonction, le onClick de son lien appelle onNavigate quand il est fourni.

Critères d'acceptation

Après l'import, « Étape suivante » mène à /categories ; la carte explique les mots-clés, entoure « Tous les mots-clés » et annonce l'ajout d'un mot-clé à l'étape suivante.
« J'ai compris » coche l'étape ; la carte annonce « Fait. » et mène à « Classer une transaction à la main ».
Sur /reports, la carte entoure la carte Tendances ; en Gratuite, elle mentionne le cadenas ; « J'ai compris » ou l'ouverture de la carte Tendances cochent l'étape ; si c'était la dernière à faire, le bandeau annonce « Démarrage terminé ».
Ouvrir /categories ou /reports sans cliquer ne coche rien.
FR et EN complets ; npm run build et npm test verts.

Review caveats

🟡 Architecture, résolu par décision : la carte Tendances est un lien vers /reports/trends et le verrou de carte se libère au changement de route ; qui suivait l'anneau quittait la page sans cocher l'étape. Max a retenu que l'ouverture de la carte Tendances mise en évidence reconnaisse l'étape.

Décisions prises en planification

Étape Catégories en 5ᵉ (avant le classement), Rapports en 8ᵉ ; validation par « J'ai compris », « Passer cette étape » gardé (Max, 2026-10-12).
Cibles : « Tous les mots-clés » sur Catégories, la carte Tendances sur Rapports ; ouvrir Tendances reconnaît l'étape (Max, 2026-10-12).
Textes des cartes validés par Max le 2026-10-12.

Conventions

Toute chaîne en FR et en EN (src/i18n/locales/fr.json, en.json) ; les textes de ce corps s'écrivent mot pour mot (FR validé par Max le 2026-10-12, EN rédigé sur le même contenu).
Phrase de carte : un contrôle cité passe par StepCardText.labels (src/utils/onboardingPath.ts), traduit par StepCard ; jamais recopié dans la phrase. Guillemets « » en FR et “ ” en EN autour de chaque libellé de contrôle interpolé ; {{filter, lowercase}} sans guillemets.
CHANGELOG : une entrée sous ## [Unreleased] dans CHANGELOG.md et CHANGELOG.fr.md.
Tests de rendu : renderToStaticMarkup (pas de jsdom) et le faux t partagé livré par #389.
Aucune migration ; npm run build (il vérifie aussi les types des fichiers de test) et npm test verts.
Guide Markdown (docs/guide-utilisateur.md) : repérer une ligne par son texte cité, pas par son numéro.

CHANGELOG

Compléter l'entrée Added écrite par #425 : FR « … ; leurs cartes, sur les pages Catégories et Rapports, expliquent les mots-clés et le hub des rapports. » EN "…; their cards, on the Categories and Reports pages, explain keywords and the reports hub."

Spec source

spec-plan-retours-onboarding-v0171.md (local, ignoré par git) ; décisions dans spec-decisions-retours-onboarding-v0171.md.

Les deux étapes de visite ajoutées par #425 (« Parcourir les catégories et les mots-clés », « Parcourir les rapports ») reçoivent leur carte sur `/categories` et `/reports` : explication, mise en évidence d'un contrôle, « J'ai compris ». Retours de Max sur la v0.17.1 (#422) ; textes validés par Max le 2026-10-12. > Planifié le 2026-10-12 (`/plan-run`, jalon `planned-2026-10-12-retours-onboarding-v0171`), après `/analyze` et une revue `/review-spec` (sécurité, architecture, technique) dont les constats sont intégrés ci-dessous. Corps autosuffisant : la spec (`spec-plan-retours-onboarding-v0171.md`) est locale et ignorée par git. > > **Préalable :** ce jalon s'exécute après le merge de `planned-2026-10-10-fiabilite-tests` (#408, #409, #395, #389). Les numéros de ligne cités sont lus sur `main` à `8b5b3b1` et ont pu bouger : se fier aux noms de fonctions, aux clés et aux textes cités. ## Travail à faire - [ ] `src/utils/onboardingPath.ts` : `CARD_PAGES` ajoute `/categories` et `/reports` ; `PAGE_STEPS` ajoute `"/categories": ["categories"]` et `"/reports": ["reports"]`. - [ ] `categoriesCardModel(checklist)` : étape faite → `{ text: null, done: true, target: null }` ; sinon phrase `onboarding.card.categories` avec `labels: { allKeywords: "categories.allKeywords" }`, cible `"allKeywords"`. - [ ] `reportsCardModel(checklist, advancedLocked)` : étape faite → fait ; sinon `onboarding.card.reports.locked` si `advancedLocked`, `onboarding.card.reports.all` sinon, avec `labels: { trends: "reports.hub.trends" }`, cible `"trendsCard"`. `advancedLocked` est celui de la page (`src/pages/ReportsPage.tsx:17-18` : `licenseReady && !advancedAllowed`). - [ ] `CategoriesPage` : `<OnboardingStepCard model={…} />` en tête de contenu, comme `TransactionsPage.tsx:91` ; le bouton « Tous les mots-clés » (`src/pages/CategoriesPage.tsx:47-57`) reçoit `onboardingTargetAttributes("categories-all-keywords", …)` quand la carte s'affiche (`showsStepCard`). Jamais « Réinitialiser » : il supprime les mots-clés, déclasse toutes les transactions et recrée l'ancienne taxonomie (`reinitializeCategories`, `src/services/categoryService.ts:215`). - [ ] `ReportsPage` : la carte en tête ; `HubReportNavCard` (`src/components/reports/HubReportNavCard.tsx`) reçoit deux props optionnelles, `onboardingTarget?: boolean` (attributs `onboardingTargetAttributes("reports-trends-card", …)` sur son lien) et `onNavigate?: () => void` (appelée au clic, avant la navigation). Seule la carte Tendances les reçoit, et seulement tant que la carte d'étape s'affiche et que l'étape n'est pas faite : `onNavigate={() => acknowledge("reports")}` (`acknowledge` vient de `useOnboarding()`, ajouté par #425). - [ ] Après « J'ai compris » : « Fait. », puis « Étape suivante : Classer une transaction à la main → » sur Catégories, et le message de fin sur Rapports (logique `cardNext` existante ; `ACKNOWLEDGE` garde la carte, #425). - [ ] Textes et docs ci-dessous. ## Textes (FR | EN) | Clé | FR | EN | |---|---|---| | `onboarding.card.categories` | Un mot-clé classe d'office, dès l'import, chaque transaction dont la description le contient ; quand deux mots-clés s'appliquent, le plus prioritaire l'emporte. « {{allKeywords}} » les liste tous, avec leur catégorie. À l'étape suivante, vous en ajouterez un depuis une transaction. | A keyword categorizes, as soon as it is imported, every transaction whose description contains it; when two keywords apply, the one with the higher priority wins. “{{allKeywords}}” lists them all, with their category. In the next step, you will add one from a transaction. | | `onboarding.card.reports.all` | Choisissez la période en haut de la page : le panneau des faits saillants résume votre solde et vos plus gros mouvements. Chaque carte du bas ouvre un rapport détaillé ; commencez par « {{trends}} ». | Pick the period at the top of the page: the highlights panel sums up your balance and your biggest moves. Each card below opens a detailed report; start with “{{trends}}”. | | `onboarding.card.reports.locked` | Choisissez la période en haut de la page : le panneau des faits saillants résume votre solde et vos plus gros mouvements. Chaque carte du bas ouvre un rapport détaillé ; commencez par « {{trends}} ». Les cartes à cadenas demandent l'édition Base. | Pick the period at the top of the page: the highlights panel sums up your balance and your biggest moves. Each card below opens a detailed report; start with “{{trends}}”. Cards with a padlock require the Base edition. | **Docs.** - Guide Markdown §1, la puce « Sur les pages Import, Transactions et Budget, quand l'étape suivante s'y fait… », et `docs.gettingStarted.subsections[0].steps[2]` (FR et EN) : « Sur les pages Import, Catégories, Transactions, Budget et Rapports » ; ajouter que, sur Catégories et Rapports, la carte se ferme par « J'ai compris », et que sur Rapports l'ouverture de la carte Tendances compte aussi. - `docs/architecture.md`, section Onboarding : pages à carte. - Liste QA `docs/qa-onboarding.html` : les deux cartes, leur cible, la variante Gratuite, « J'ai compris » puis l'étape suivante ou la fin, le clic sur Tendances. ## Fichiers concernés - `src/utils/onboardingPath.ts`, `src/utils/onboardingPath.test.ts` - `src/pages/CategoriesPage.tsx`, `src/pages/ReportsPage.tsx` - `src/components/reports/HubReportNavCard.tsx`, `src/components/reports/HubReportNavCard.render.test.tsx` (nouveau) - `src/i18n/locales/fr.json`, `src/i18n/locales/en.json` - `docs/guide-utilisateur.md`, `docs/architecture.md`, `docs/qa-onboarding.html` - `CHANGELOG.md`, `CHANGELOG.fr.md` ## Depends on - #425 - #430 > #425 apporte les étapes, `acknowledge` et le bouton « J'ai compris » ; #430 écrit la carte Transactions que la carte Catégories annonce. ## Tests - `stepsOfPage`, `cardStep` sur `/categories` (5 sur 8 en Base+) et `/reports` (8 sur 8 ; 7 sur 7 en Gratuite) ; `cardNext` : après Catégories, l'étape suivante est `manualCategory` ; après Rapports, la fin. - `categoriesCardModel` et `reportsCardModel` : fait, variante `all`, variante `locked`, cibles. - `HubReportNavCard` : attributs de mise en évidence présents seulement avec `onboardingTarget` ; en appelant le composant comme une fonction, le `onClick` de son lien appelle `onNavigate` quand il est fourni. ## Critères d'acceptation - [ ] Après l'import, « Étape suivante » mène à `/categories` ; la carte explique les mots-clés, entoure « Tous les mots-clés » et annonce l'ajout d'un mot-clé à l'étape suivante. - [ ] « J'ai compris » coche l'étape ; la carte annonce « Fait. » et mène à « Classer une transaction à la main ». - [ ] Sur `/reports`, la carte entoure la carte Tendances ; en Gratuite, elle mentionne le cadenas ; « J'ai compris » ou l'ouverture de la carte Tendances cochent l'étape ; si c'était la dernière à faire, le bandeau annonce « Démarrage terminé ». - [ ] Ouvrir `/categories` ou `/reports` sans cliquer ne coche rien. - [ ] FR et EN complets ; `npm run build` et `npm test` verts. ## Review caveats - 🟡 Architecture, résolu par décision : la carte Tendances est un lien vers `/reports/trends` et le verrou de carte se libère au changement de route ; qui suivait l'anneau quittait la page sans cocher l'étape. Max a retenu que l'ouverture de la carte Tendances mise en évidence reconnaisse l'étape. ## Décisions prises en planification - Étape Catégories en 5ᵉ (avant le classement), Rapports en 8ᵉ ; validation par « J'ai compris », « Passer cette étape » gardé (Max, 2026-10-12). - Cibles : « Tous les mots-clés » sur Catégories, la carte Tendances sur Rapports ; ouvrir Tendances reconnaît l'étape (Max, 2026-10-12). - Textes des cartes validés par Max le 2026-10-12. ## Conventions - Toute chaîne en FR et en EN (`src/i18n/locales/fr.json`, `en.json`) ; les textes de ce corps s'écrivent mot pour mot (FR validé par Max le 2026-10-12, EN rédigé sur le même contenu). - Phrase de carte : un contrôle cité passe par `StepCardText.labels` (`src/utils/onboardingPath.ts`), traduit par `StepCard` ; jamais recopié dans la phrase. Guillemets « » en FR et “ ” en EN autour de chaque libellé de contrôle interpolé ; `{{filter, lowercase}}` sans guillemets. - CHANGELOG : une entrée sous `## [Unreleased]` dans `CHANGELOG.md` et `CHANGELOG.fr.md`. - Tests de rendu : `renderToStaticMarkup` (pas de jsdom) et le faux `t` partagé livré par #389. - Aucune migration ; `npm run build` (il vérifie aussi les types des fichiers de test) et `npm test` verts. - Guide Markdown (`docs/guide-utilisateur.md`) : repérer une ligne par son texte cité, pas par son numéro. ## CHANGELOG Compléter l'entrée Added écrite par #425 : FR « … ; leurs cartes, sur les pages Catégories et Rapports, expliquent les mots-clés et le hub des rapports. » EN "…; their cards, on the Categories and Reports pages, explain keywords and the reports hub." ## Spec source `spec-plan-retours-onboarding-v0171.md` (local, ignoré par git) ; décisions dans `spec-decisions-retours-onboarding-v0171.md`.