From bef330affb3e59762d6d1837153325f7ffce9fea Mon Sep 17 00:00:00 2001 From: le king fu Date: Sat, 25 Apr 2026 17:06:46 -0400 Subject: [PATCH] docs(guide): add user guide section for Bilan New section 10 "Bilan" walks through: - the 3 routes (/balance, /balance/snapshot, /balance/accounts) - snapshot entry (simple + priced kinds, prefill button) - transfer linking with auto-suggested direction - multi-horizon Modified Dietz returns (3M / 1Y / since inception) read alongside the unadjusted return for comparison - the FK RESTRICT user-facing message on linked-transaction deletion - price-fetching premium flagged "coming Phase 5" Renumbers Settings to section 11. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/guide-utilisateur.md | 69 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-) diff --git a/docs/guide-utilisateur.md b/docs/guide-utilisateur.md index 589f11d..5c3e9a6 100644 --- a/docs/guide-utilisateur.md +++ b/docs/guide-utilisateur.md @@ -355,7 +355,74 @@ L'application est atomique : soit toutes les transactions cochées sont recatég --- -## 10. Paramètres +## 10. Bilan + +Le **Bilan** est une vue patrimoniale : vous saisissez périodiquement un *snapshot* daté de l'ensemble de vos comptes (encaisse, REER, CELI, fonds, actions, crypto, autres), vous suivez leur évolution dans le temps, et vous calculez le **vrai rendement** de chaque compte d'investissement en liant les transferts (apports / retraits) aux comptes correspondants. + +Trois pages composent le module Bilan : +- `/balance` — vue d'ensemble (graphique + tableau des comptes) +- `/balance/snapshot` — saisie / édition d'un snapshot daté +- `/balance/accounts` — CRUD des comptes et catégories + +L'entrée **Bilan** dans la barre latérale (icône portefeuille) donne accès à `/balance` ; les deux autres pages s'ouvrent depuis là. + +### Fonctionnalités + +- 7 catégories standard pré-installées : Encaisse, CELI, REER, Fonds, Actions, Crypto, Autres — renommables, non-supprimables +- Création de catégories personnalisées (ex. FERR, RPDB) avec choix `simple` (montant direct) ou `priced` (quantité × prix unitaire) +- Comptes par catégorie : nom, symbole optionnel, devise (CAD au MVP), notes +- Snapshots datés avec contrainte UNIQUE par date — éditer = revenir sur la même date, jamais dupliquer +- Saisie groupée par catégorie ; pour les catégories `priced`, le `value` est calculé automatiquement (`quantity × unit_price`) +- Bouton **Pré-remplir depuis le snapshot précédent** : copie les valeurs simples + les quantités priced (vous remplissez juste les nouveaux prix) +- Liaison de transactions existantes à un compte de bilan (modal avec filtres par période / catégorie / recherche, sens auto-proposé selon le signe) +- Icône d'attribution dans la page Transactions pour les transactions liées à un transfert +- Graphique d'évolution du bilan (mode courbe simple ou aire empilée par catégorie) avec marqueurs verticaux pour les transferts taggés (vert = in, rouge = out) +- Tableau des comptes avec **3 colonnes de rendement Modified Dietz** (3 mois / 1 an / depuis création) + colonne rendement non-ajusté côte-à-côte +- Avertissement si le dernier snapshot remonte à plus de 60 jours +- Soft-delete des comptes (`Archiver`) : masqués des nouveaux snapshots, conservés dans l'historique +- Suppression d'un snapshot avec double-confirmation (re-saisie de la date) +- Privacy-first : tout est local, aucun appel sortant au MVP + +### Comment faire + +1. Allez dans `/balance/accounts` → onglet Catégories pour créer si besoin une catégorie supplémentaire (ex. "FERR" en `simple`, ou "Stocks Wealthsimple" en `priced`) +2. Allez dans l'onglet Comptes pour créer chaque compte (ex. "TFSA Tangerine" rattaché à CELI, "BTC Ledger" rattaché à Crypto avec symbole `BTC`) +3. Cliquez **+ Nouveau snapshot** depuis `/balance` pour ouvrir `/balance/snapshot` à la date du jour +4. Remplissez les valeurs par compte (groupées par catégorie). Pour les comptes priced, saisissez la quantité et le prix unitaire — la valeur est calculée +5. Enregistrez. Le graphique sur `/balance` s'actualise immédiatement +6. Pour calculer le rendement réel d'un compte d'investissement, ouvrez le menu actions du compte → **Lier transferts** → cochez les transactions qui correspondent à des apports / retraits (un dépôt CELI, un achat d'actions, etc.). Le sens (in/out) est proposé automatiquement selon le signe de la transaction +7. Le tableau des comptes affiche maintenant les rendements Modified Dietz sur 3M / 1A / depuis création. Le rendement non-ajusté à droite vous permet de comparer "valeur du compte" et "vraie performance" +8. Pour éditer un snapshot existant, cliquez sur son point dans le graphique ou utilisez le sélecteur de date — la page s'ouvre en mode édition (la date est immutable) +9. Pour supprimer un snapshot, cliquez **Supprimer** dans son éditeur et re-saisissez la date pour confirmer + +### Lecture des rendements multi-horizons + +- **3 mois** : performance courte, sensible aux mouvements récents +- **1 an** : horizon de référence pour la plupart des décisions d'allocation +- **Depuis création** : performance totale du compte depuis le premier snapshot +- **Non-ajusté (côte-à-côte)** : `(V_fin − V_début) / V_début` brut, sans soustraction des apports — utile pour voir la croissance totale (gains + apports). La différence entre les deux colonnes vous montre la part qui vient des apports plutôt que de la performance + +Avertissements affichés : +- *Période partielle* — un snapshot manque au début ou à la fin de la période +- *Aucun transfert lié* — le rendement est calculé sans apports identifiés (équivaut au non-ajusté) +- *Performance non significative* — le compte a été vidé puis rechargé, le calcul Modified Dietz produit un résultat instable + +### Que faire si je supprime une transaction liée ? + +C'est intentionnellement bloqué : si vous tentez de supprimer une transaction qui est liée à un compte de bilan, vous voyez le message **"Cette transaction est liée au compte de bilan __"** avec un lien direct vers le compte. Ouvrez le compte → Lier transferts → décochez la transaction → revenez la supprimer. Cette friction préserve la reproductibilité de vos rendements passés (un rendement calculé hier ne peut pas changer aujourd'hui à cause d'une suppression silencieuse). + +### Astuces + +- Saisissez vos snapshots à un rythme régulier (mensuel ou trimestriel) — la qualité des rendements dépend directement de la régularité +- Utilisez le bouton **Pré-remplir** : ça copie tout, vous mettez juste à jour ce qui a changé +- Le mode **graphique empilé par catégorie** raconte une histoire différente du mode ligne : il montre la composition de votre patrimoine, pas seulement son total +- Les marqueurs verticaux du graphique (transferts taggés) aident à lire les sauts de valeur — un saut suivi d'un marqueur vert n'est pas une "performance", c'est juste un dépôt +- L'avertissement "bilan pas à jour" apparaît si votre dernier snapshot remonte à plus de 60 jours — c'est le signe qu'il est temps d'en saisir un nouveau +- (À venir Phase 5) **Récupération automatique des prix** pour les comptes Actions / Crypto via un proxy privé (premium-only). Le service interroge un serveur Maximus dédié qui anonymise votre requête (votre IP n'est jamais exposée à Yahoo / CoinGecko). La saisie manuelle reste toujours disponible. + +--- + +## 11. Paramètres Configurez les préférences de l'application, vérifiez les mises à jour, accédez au guide utilisateur et gérez vos données avec les outils d'export/import.