docs(reports/cartes): document and surface savings-rate formula #102

New issue

Closed

opened 2026-04-19 00:27:01 +00:00 by maximus · 0 comments

maximus commented

2026-04-19 00:27:01 +00:00

Owner

Contexte

Suite à l'analyse post-sprint (2026-04-19), 3 des 5 tâches originales de cette issue ont été livrées dans #101 (tooltip, i18n savingsRateTooltip, fallback income=0 → "—"). Cette issue est re-scopée pour couvrir la décision produit restante et la documentation.

Les règles Saisonnalité et le bug Budget Adherence (#112) ont été identifiés pendant la même analyse.

Scope révisé

1. Toggle Mensuel / YTD sur les 4 KPI cards

Ajouter un toggle segmenté « Mensuel · YTD » en haut de /reports/cartes, juste à côté du CompareReferenceMonthPicker. Le toggle s'applique aux 4 KpiCard (Revenus, Dépenses, Solde net, Taux d'épargne) :

Mensuel (défaut, comportement actuel) : valeur = mois de référence.
YTD : valeur = cumul du 1er janvier de l'année du mois de référence jusqu'à la fin du mois de référence. Cela inclut le taux d'épargne YTD = (revenus YTD − dépenses YTD) / revenus YTD × 100.

En mode YTD, les deltas sont recalculés pour la cohérence avec /reports/compare (décision prise pour #104) :

MoM → YTD-vs-YTD-prev-month : cumul Jan→refMonth−1 de la même année.
YoY → YTD-vs-YTD-prev-year : cumul Jan→refMonth de l'année précédente.

Les sparklines restent 13 mois dans les deux modes (ce qui change, c'est le point "current" affiché).

2. Persistance du toggle

Dans localStorage sous la clé reports-cartes-period-mode. Valeurs acceptées : "month" | "ytd". Défaut : "month".

reports.cartes.savingsRateTooltip doit refléter les deux modes. Option :

reports.cartes.savingsRateTooltip.month = "Formule : (revenus − dépenses) ÷ revenus × 100, calculée sur le mois de référence."
reports.cartes.savingsRateTooltip.ytd = "Formule : (revenus YTD − dépenses YTD) ÷ revenus YTD × 100, cumul depuis le 1er janvier."

4. Documentation utilisateur

Ajouter une section « Cartes (KPI) » dans docs/guide-utilisateur.md sous la section Rapports. Doit couvrir :

Les 4 KPI principaux et leurs formules (inclut taux d'épargne mensuel ET YTD)
Le toggle Mensuel / YTD
Les règles de Saisonnalité : comparaison au même mois civil des 2 années précédentes, moyenne historique, écart %
Top mouvements : plus grosses variations mensuelles MoM par catégorie
Budget Adherence : ratio catégories-en-cible / catégories-avec-budget, top dépassements (une fois #112 fixé)

Fichiers concernés

src/pages/ReportsCartesPage.tsx — insérer le toggle, passer le mode au hook
src/hooks/useCartes.ts — state du mode, persistance localStorage, relecture au mount
src/services/reportService.ts — getCartesSnapshot accepte un paramètre mode: "month" | "ytd", calcule les agrégats YTD côté serveur (réutiliser la logique éprouvée de getCompareMonthOverMonth pour les fenêtres cumulatives)
src/shared/types/index.ts — CartesKpiPeriodMode type, pas de changement à CartesKpi (la sémantique de current absorbe simplement la valeur choisie)
src/components/reports/cards/KpiCard.tsx — accepter un tooltip dynamique par mode
src/i18n/locales/{fr,en}.json — clés reports.cartes.periodMode.* + tooltip par mode
docs/guide-utilisateur.md — nouvelle section Cartes
CHANGELOG.md + CHANGELOG.fr.md — entrée Added / Ajouté
Tests : src/services/reportService.cartes.test.ts — ajouter des fixtures YTD

Surface de test

Tests existants : src/services/reportService.cartes.test.ts (13 tests), src/hooks/useCartes.test.ts (3 tests).
Nouveaux tests requis :
- Calcul YTD correct pour chaque KPI (Jan → refMonth inclus)
- Deltas YTD-MoM et YTD-YoY
- Taux d'épargne YTD = null si revenusYTD = 0
- Persistance localStorage (round-trip)

Critères d'acceptation

Toggle Mensuel · YTD visible à côté du CompareReferenceMonthPicker dans /reports/cartes.
Basculer entre les modes recalcule les 4 KPI cards et leurs deltas.
La préférence est persistée dans localStorage et relue au mount.
Le tooltip du taux d'épargne affiche la formule correspondant au mode courant.
La section "Cartes (KPI)" est ajoutée à docs/guide-utilisateur.md avec les règles de Saisonnalité et les formules.
Traductions FR/EN pour toutes les nouvelles clés.
CHANGELOG mis à jour dans les deux langues.
npm run build et npm test -- --run passent.

Complexité

Medium — un peu de SQL pour les agrégats YTD, mais les patterns existent déjà dans getCompareMonthOverMonth (fenêtres Jan→refMonth). Le reste est du plumbing UI + docs.

Hors scope

Budget Adherence reste mensuel quel que soit le toggle (son unité naturelle est le budget mensuel).
Top Movers reste mensuel (MoM).
Saisonnalité reste mensuel.
Bug du filtre monthBudget > 0 → traité séparément dans #112.

## Contexte Suite à l'analyse post-sprint (2026-04-19), 3 des 5 tâches originales de cette issue ont été livrées dans #101 (tooltip, i18n `savingsRateTooltip`, fallback `income=0` → "—"). Cette issue est re-scopée pour couvrir la **décision produit restante** et la documentation. Les règles Saisonnalité et le bug Budget Adherence (`#112`) ont été identifiés pendant la même analyse. ## Scope révisé ### 1. Toggle Mensuel / YTD sur les 4 KPI cards Ajouter un toggle segmenté **« Mensuel · YTD »** en haut de `/reports/cartes`, juste à côté du `CompareReferenceMonthPicker`. Le toggle s'applique aux **4 KpiCard** (Revenus, Dépenses, Solde net, Taux d'épargne) : - **Mensuel** (défaut, comportement actuel) : valeur = mois de référence. - **YTD** : valeur = cumul du 1er janvier de l'année du mois de référence jusqu'à la fin du mois de référence. Cela inclut le **taux d'épargne YTD** = `(revenus YTD − dépenses YTD) / revenus YTD × 100`. En mode YTD, les deltas sont recalculés pour la cohérence avec `/reports/compare` (décision prise pour #104) : - **MoM → YTD-vs-YTD-prev-month** : cumul Jan→refMonth−1 de la même année. - **YoY → YTD-vs-YTD-prev-year** : cumul Jan→refMonth de l'année précédente. Les sparklines restent 13 mois dans les deux modes (ce qui change, c'est le point "current" affiché). ### 2. Persistance du toggle Dans `localStorage` sous la clé `reports-cartes-period-mode`. Valeurs acceptées : `"month"` | `"ytd"`. Défaut : `"month"`. ### 3. Mise à jour du tooltip i18n `reports.cartes.savingsRateTooltip` doit refléter les deux modes. Option : - `reports.cartes.savingsRateTooltip.month` = "Formule : (revenus − dépenses) ÷ revenus × 100, calculée sur le mois de référence." - `reports.cartes.savingsRateTooltip.ytd` = "Formule : (revenus YTD − dépenses YTD) ÷ revenus YTD × 100, cumul depuis le 1er janvier." ### 4. Documentation utilisateur Ajouter une section **« Cartes (KPI) »** dans `docs/guide-utilisateur.md` sous la section Rapports. Doit couvrir : - Les 4 KPI principaux et leurs formules (inclut taux d'épargne mensuel ET YTD) - Le toggle Mensuel / YTD - Les règles de **Saisonnalité** : comparaison au même mois civil des 2 années précédentes, moyenne historique, écart % - **Top mouvements** : plus grosses variations mensuelles MoM par catégorie - **Budget Adherence** : ratio catégories-en-cible / catégories-avec-budget, top dépassements (une fois #112 fixé) ## Fichiers concernés - `src/pages/ReportsCartesPage.tsx` — insérer le toggle, passer le mode au hook - `src/hooks/useCartes.ts` — state du mode, persistance localStorage, relecture au mount - `src/services/reportService.ts` — `getCartesSnapshot` accepte un paramètre `mode: "month" | "ytd"`, calcule les agrégats YTD côté serveur (réutiliser la logique éprouvée de `getCompareMonthOverMonth` pour les fenêtres cumulatives) - `src/shared/types/index.ts` — `CartesKpiPeriodMode` type, pas de changement à `CartesKpi` (la sémantique de `current` absorbe simplement la valeur choisie) - `src/components/reports/cards/KpiCard.tsx` — accepter un tooltip dynamique par mode - `src/i18n/locales/{fr,en}.json` — clés `reports.cartes.periodMode.*` + tooltip par mode - `docs/guide-utilisateur.md` — nouvelle section Cartes - `CHANGELOG.md` + `CHANGELOG.fr.md` — entrée `Added` / `Ajouté` - Tests : `src/services/reportService.cartes.test.ts` — ajouter des fixtures YTD ## Surface de test - Tests existants : `src/services/reportService.cartes.test.ts` (13 tests), `src/hooks/useCartes.test.ts` (3 tests). - Nouveaux tests requis : - Calcul YTD correct pour chaque KPI (Jan → refMonth inclus) - Deltas YTD-MoM et YTD-YoY - Taux d'épargne YTD = `null` si `revenusYTD = 0` - Persistance localStorage (round-trip) ## Critères d'acceptation - [ ] Toggle `Mensuel · YTD` visible à côté du `CompareReferenceMonthPicker` dans `/reports/cartes`. - [ ] Basculer entre les modes recalcule les 4 KPI cards et leurs deltas. - [ ] La préférence est persistée dans `localStorage` et relue au mount. - [ ] Le tooltip du taux d'épargne affiche la formule correspondant au mode courant. - [ ] La section "Cartes (KPI)" est ajoutée à `docs/guide-utilisateur.md` avec les règles de Saisonnalité et les formules. - [ ] Traductions FR/EN pour toutes les nouvelles clés. - [ ] CHANGELOG mis à jour dans les deux langues. - [ ] `npm run build` et `npm test -- --run` passent. ## Complexité Medium — un peu de SQL pour les agrégats YTD, mais les patterns existent déjà dans `getCompareMonthOverMonth` (fenêtres Jan→refMonth). Le reste est du plumbing UI + docs. ## Hors scope - Budget Adherence reste **mensuel** quel que soit le toggle (son unité naturelle est le budget mensuel). - Top Movers reste **mensuel** (MoM). - Saisonnalité reste **mensuel**. - Bug du filtre `monthBudget > 0` → traité séparément dans #112.