Simpl-Resultat/docs/guide-utilisateur.md

# Guide d'utilisation — Simpl'Résultat

---

## 1. Premiers pas

Simpl'Résultat vous aide à suivre vos finances personnelles en important des relevés bancaires, en catégorisant les transactions, en planifiant des budgets et en générant des rapports. L'application est disponible sur Windows et Linux.

### Fonctionnalités

- Importation de relevés bancaires CSV depuis plusieurs sources
- Catégorisation automatique et manuelle des transactions
- Répartition (split) d'une transaction sur plusieurs catégories
- Planification budgétaire avec vues mensuelles et annuelles
- Rapports visuels et graphiques interactifs avec menu contextuel
- Profils multiples avec bases de données séparées et NIP optionnel
- Mode sombre avec palette gris chaud
- Export et import de données avec chiffrement AES-256 optionnel

### Démarrage rapide

1. Au premier lancement, choisissez ou créez un profil — chaque profil a sa propre base de données
2. Allez dans Paramètres et définissez votre dossier d'import — créez un sous-dossier par compte bancaire
3. Placez vos relevés bancaires CSV dans le sous-dossier correspondant
4. Ouvrez la page Import et configurez votre source (mapping des colonnes, délimiteur, format de date)
5. Importez vos transactions, puis allez dans Catégories pour configurer les règles de mots-clés
6. Utilisez l'auto-catégorisation sur la page Transactions pour appliquer vos règles en masse
7. Configurez votre Budget et suivez votre progression via les Rapports

### Astuces

- Vous pouvez basculer entre le français et l'anglais via le sélecteur de langue dans la barre latérale
- Activez le mode sombre via le bouton dans la barre latérale
- Chaque page a une icône d'aide (?) dans l'en-tête avec des astuces rapides
- Vos données sont stockées localement sur votre ordinateur — rien n'est envoyé vers le cloud

---

## 2. Profils

Gérez plusieurs profils indépendants, chacun avec sa propre base de données. Idéal pour séparer les finances personnelles et professionnelles, ou pour plusieurs utilisateurs sur un même ordinateur.

### Fonctionnalités

- Création de profils multiples avec noms et couleurs personnalisés
- Chaque profil possède sa propre base de données séparée
- Protection optionnelle par NIP (code numérique)
- Changement de profil rapide depuis la barre latérale
- Suppression de profil avec toutes ses données

### Comment faire

1. Cliquez sur le sélecteur de profil dans la barre latérale pour voir les profils disponibles
2. Cliquez sur Gérer les profils pour créer, modifier ou supprimer des profils
3. Créez un nouveau profil en choisissant un nom, une couleur et un NIP optionnel
4. Basculez entre les profils en cliquant sur celui de votre choix dans le sélecteur

### Astuces

- Un profil par défaut est créé automatiquement au premier lancement
- Le NIP est demandé à chaque fois que vous accédez à un profil protégé
- La suppression d'un profil supprime définitivement toutes ses données — cette action est irréversible

---

## 3. Tableau de bord

Le tableau de bord vous donne un aperçu rapide de votre situation financière pour une période sélectionnée.

### Fonctionnalités

- Cartes résumées du solde, des revenus et des dépenses
- Répartition des dépenses par catégorie (graphique circulaire avec motifs SVG)
- Tableau Budget vs Réel du mois courant (écart en $ et %)
- Histogramme empilé des dépenses par catégorie et par mois
- Sélecteur de période ajustable (par défaut : année à ce jour)
- Menu contextuel (clic droit) pour masquer une catégorie ou voir ses transactions

### Comment faire

1. Utilisez le sélecteur de période en haut à droite pour choisir une plage de temps (mois, 3 mois, année, etc.)
2. Consultez les cartes résumées pour votre solde, revenus totaux et dépenses totales
3. Vérifiez le graphique circulaire pour voir comment vos dépenses sont réparties par catégorie
4. Consultez le tableau Budget vs Réel pour comparer vos dépenses au budget du mois courant
5. Analysez l'histogramme en bas de page pour voir l'évolution de vos dépenses par catégorie dans le temps
6. Cliquez droit sur une catégorie dans un graphique pour la masquer ou voir le détail de ses transactions

### Astuces

- La période par défaut est « année à ce jour » pour un aperçu annuel dès l'ouverture
- Le solde est calculé comme les revenus moins les dépenses pour la période sélectionnée
- Les catégories masquées apparaissent sous forme de pastilles au-dessus du graphique — cliquez sur Tout afficher pour les restaurer
- Les motifs SVG (lignes, points, hachures) aident à distinguer les catégories au-delà des couleurs

---

## 4. Import

Importez des relevés bancaires à partir de fichiers CSV à l'aide d'un assistant étape par étape. Chaque compte bancaire est représenté par un dossier source.

### Fonctionnalités

- Assistant d'import multi-étapes avec aperçu des données
- Mapping de colonnes configurable, délimiteur et format de date
- Détection automatique des doublons (dans le lot et contre les données existantes)
- Modèles d'import pour sauvegarder et réutiliser les configurations
- Historique des imports avec possibilité de supprimer les imports précédents

### Comment faire

1. Définissez votre dossier d'import via le sélecteur de dossier en haut de la page
2. Créez un sous-dossier pour chaque banque/source et placez-y les fichiers CSV
3. Cliquez sur une source pour ouvrir l'assistant d'import
4. Configurez le délimiteur, l'encodage, le format de date et le mapping des colonnes
5. Sélectionnez les fichiers à importer et prévisualisez les données analysées
6. Vérifiez les doublons, examinez le résumé, puis confirmez l'import

### Astuces

- Sauvegardez votre configuration comme modèle pour ne pas avoir à reconfigurer à chaque fois
- Les fichiers déjà importés sont marqués d'un badge — les ré-importer déclenchera la détection de doublons
- Vous pouvez supprimer un import de l'historique pour retirer toutes ses transactions

---

## 5. Transactions

Parcourez, filtrez, triez et catégorisez toutes vos transactions importées. C'est ici que vous organisez vos données financières.

### Fonctionnalités

- Recherche et filtre par description, catégorie, source ou plage de dates
- Sélecteurs de période rapides (ce mois, mois dernier, cette année, etc.)
- Colonnes triables (date, description, montant, catégorie)
- Assignation de catégorie en ligne via menu déroulant
- Auto-catégorisation basée sur les règles de mots-clés
- Ajout de mots-clés directement depuis une transaction
- Répartition (split) d'une transaction sur plusieurs catégories
- Notes sur les transactions

### Comment faire

1. Utilisez la barre de filtres pour affiner les transactions par texte, catégorie, source ou date
2. Cliquez sur un en-tête de colonne pour trier par ordre croissant ou décroissant
3. Pour catégoriser une transaction, cliquez sur son menu déroulant de catégorie et sélectionnez une catégorie
4. Pour auto-catégoriser toutes les transactions non catégorisées, cliquez sur le bouton Auto-catégoriser
5. Pour ajouter une règle de mot-clé depuis une transaction, cliquez sur l'icône + et entrez le mot-clé
6. Pour répartir une transaction sur plusieurs catégories, utilisez le bouton Répartition et ajoutez les montants par catégorie

### Astuces

- Utilisez les boutons de période rapide (Ce mois, Mois dernier, etc.) pour filtrer rapidement par date
- L'auto-catégorisation n'affecte que les transactions non catégorisées — elle n'écrase pas les assignations manuelles
- Ajouter un mot-clé depuis une transaction pré-remplit la catégorie pour construire rapidement vos règles
- Les transactions réparties affichent un indicateur visuel et le détail de la répartition

---

## 6. Catégories

Gérez votre arbre de catégories avec des sous-catégories, des règles de mots-clés pour l'auto-catégorisation et des couleurs personnalisées.

### Fonctionnalités

- Catégories hiérarchiques avec relations parent/enfant
- Trois types de catégories : Dépense, Revenu, Transfert
- Règles de mots-clés avec niveaux de priorité pour l'auto-catégorisation
- Couleurs personnalisées pour l'affichage des graphiques
- Glisser-déposer pour réordonner les catégories ou changer leur parent
- Basculer les catégories en saisissable ou non-saisissable
- Vue « Tous les mots-clés » pour voir l'ensemble des règles
- Réinitialiser les catégories aux valeurs par défaut

### Comment faire

1. Cliquez sur Ajouter une catégorie pour créer une nouvelle catégorie — choisissez un nom, un type et un parent optionnel
2. Sélectionnez une catégorie dans l'arbre pour voir ses détails et sa liste de mots-clés
3. Glissez-déposez une catégorie dans l'arbre pour la réordonner ou la déplacer sous un autre parent
4. Ajoutez des mots-clés correspondant aux descriptions des transactions pour l'auto-catégorisation
5. Définissez la priorité des mots-clés pour résoudre les conflits quand plusieurs catégories correspondent
6. Utilisez le sélecteur de couleur pour assigner une couleur personnalisée pour les graphiques

### Astuces

- Les catégories non-saisissables sont masquées du budget et des menus déroulants mais restent visibles dans les rapports
- Les mots-clés de priorité supérieure l'emportent quand plusieurs catégories correspondent à la même transaction
- Utilisez la vue Tous les mots-clés pour avoir un aperçu global de vos règles de catégorisation
- Utilisez Réinitialiser pour revenir aux catégories par défaut — cela dissociera toutes les catégories des transactions

---

## 7. Ajustements

Ajoutez des entrées manuelles non issues de vos relevés bancaires, et consultez les répartitions de transactions créées depuis la page Transactions.

### Fonctionnalités

- Créer des groupes d'ajustement nommés avec plusieurs entrées
- Assigner une catégorie à chaque entrée
- Marquer des ajustements comme récurrents
- Consultation des répartitions (splits) de transactions dans une section dédiée

### Comment faire

1. Cliquez sur Nouvel ajustement pour créer un groupe d'ajustement
2. Ajoutez des entrées avec une description, un montant, une date et une catégorie
3. Activez le drapeau récurrent si l'ajustement doit se répéter à chaque période
4. Consultez la section Répartitions de transactions pour voir les splits créés depuis la page Transactions

### Astuces

- Les ajustements apparaissent dans vos réels de budget aux côtés des transactions importées
- Utilisez les ajustements pour les dépenses prévues qui n'ont pas encore été débitées de votre compte
- Les répartitions de transactions sont créées depuis la page Transactions et apparaissent automatiquement ici

---

## 8. Budget

Planifiez votre budget mensuel pour chaque catégorie et suivez le prévu par rapport au réel tout au long de l'année.

### Fonctionnalités

- Grille budgétaire mensuelle pour toutes les catégories
- Colonne annuelle avec totaux automatiques
- Répartition égale du montant annuel sur 12 mois
- Modèles de budget pour sauvegarder et appliquer des configurations
- Sous-totaux par catégorie parente
- En-têtes de colonnes fixes au défilement vertical

### Comment faire

1. Utilisez le navigateur d'année pour sélectionner l'année du budget
2. Cliquez sur une cellule de mois pour entrer un montant prévu
3. Appuyez sur Entrée pour sauvegarder, Échap pour annuler, ou Tab pour passer au mois suivant
4. Utilisez le bouton de répartition (sur la colonne Annuel) pour distribuer également sur tous les mois
5. Sauvegardez votre budget comme modèle pour le réutiliser les années suivantes

### Astuces

- La colonne Annuel additionne automatiquement les 12 mois — un avertissement apparaît si les totaux mensuels ne correspondent pas
- Les modèles peuvent être appliqués à des mois spécifiques ou aux 12 mois d'un coup
- Les catégories parentes affichent les sous-totaux agrégés de leurs enfants

---

## 9. Rapports

`/reports` est un **hub** qui répond à quatre questions : *qu'est-ce qui a bougé ce mois ?*, *où je vais sur 12 mois ?*, *comment je me situe vs période précédente ou vs budget ?*, *que se passe-t-il dans cette catégorie ?*

### Le hub

En haut, un **panneau de faits saillants** condensé : solde net du mois courant + solde cumul annuel (YTD) avec sparkline 12 mois, top mouvements vs mois précédent et top 5 des plus grosses transactions récentes. En bas, quatre cartes mènent aux quatre sous-rapports dédiés.

Le sélecteur de période en haut à droite est **partagé** entre toutes les pages via l'URL : `?from=YYYY-MM-DD&to=YYYY-MM-DD`. Copiez l'URL pour revenir plus tard au même état ou la partager.

### Rapport Faits saillants (`/reports/highlights`)

- Tuiles de soldes mois courant + YTD avec sparklines 12 mois
- Tableau triable des **top mouvements** (catégories avec la plus forte variation vs mois précédent), ou graphique en barres divergentes centré sur zéro (toggle graphique/tableau)
- Liste des **plus grosses transactions récentes** avec fenêtre configurable 30 / 60 / 90 jours

### Rapport Cartes (`/reports/cartes`)

Un tableau de bord condensé qui résume un mois de référence en quatre KPIs, une sparkline 13 mois, les plus gros mouvements de catégories, l'adhésion budgétaire et la saisonnalité. Deux contrôles en en-tête : le **sélecteur de mois de référence** et le **toggle Mensuel / Cumul annuel (YTD)**.

#### Les 4 cartes KPI et leurs formules

- **Revenus** = somme des transactions positives
- **Dépenses** = valeur absolue de la somme des transactions négatives
- **Solde net** = `revenus − dépenses`
- **Taux d'épargne** = `(revenus − dépenses) ÷ revenus × 100`. Affiché comme « — » quand les revenus sont à zéro (évite la division par zéro et le « 0 % » trompeur)

Chaque carte affiche la valeur courante, deux deltas (vs mois précédent, vs l'an dernier) et une sparkline 13 mois. Le delta est vert si la variation est favorable au KPI (hausse pour Revenus, baisse pour Dépenses), rouge dans le cas contraire.

#### Toggle Mensuel / Cumul annuel (YTD)

Placé à côté du sélecteur de mois, il bascule les 4 cartes entre deux vues :

- **Mensuel** (par défaut) — la valeur courante est celle du mois de référence. Les deltas comparent ce mois à son précédent (MoM) et au même mois de l'an dernier (YoY)
- **Cumul annuel (YTD)** — la valeur courante est la somme depuis le 1er janvier de l'année de référence jusqu'à la fin du mois de référence inclus. Les deltas deviennent :
  - **MoM YTD** = cumul actuel (Jan→mois de réf) vs cumul précédent (Jan→mois de réf−1) de la même année. **Null en janvier** (pas de fenêtre antérieure dans la même année) — affiché comme « — »
  - **YoY YTD** = cumul actuel vs le même cumul (Jan→mois de réf) de l'année précédente
  - **Taux d'épargne YTD** = `(revenus YTD − dépenses YTD) ÷ revenus YTD × 100`, null si les revenus YTD sont à zéro

Le choix du mode est **persisté** (clé locale `reports-cartes-period-mode`) et restauré au redémarrage. La sparkline 13 mois, elle, reste toujours mensuelle — elle donne le contexte temporel indépendamment du toggle.

#### Sparkline 13 mois

Chaque KPI inclut une mini-courbe des 13 derniers mois (mois de référence + 12 précédents). Les mois sans données comptent comme zéro pour que la courbe reste continue. Non affectée par le toggle Mensuel / YTD.

#### Top mouvements (MoM)

Deux listes : les 5 catégories avec la plus forte **hausse** de dépenses vs mois précédent et les 5 avec la plus forte **baisse**. Triées par variation absolue en dollars, avec la variation en pourcentage à droite. Toujours mensuelles, indépendamment du toggle.

#### Saisonnalité

Compare les dépenses du mois de référence à la **moyenne du même mois calendaire sur les 2 années précédentes**.

- Écart en pourcentage : `(dépenses du mois − moyenne historique) ÷ moyenne historique × 100`
- Affiché comme « pas assez d'historique pour ce mois » s'il n'y a aucune donnée historique ou si la moyenne est à zéro

Toujours basée sur le mois de référence, indépendamment du toggle Mensuel / YTD.

#### Adhésion budgétaire

Score `N/M` des catégories dont les dépenses restent sous le budget mensuel (comparaison en valeur absolue pour gérer correctement les budgets de dépenses stockés signés négatifs).

- Seules les catégories de type **dépense** avec un budget non nul sont comptées, feuilles uniquement (les catégories parentes sont ignorées pour éviter le double comptage)
- Suivi des **3 pires dépassements** avec le montant et le pourcentage de dépassement

Toujours mensuelle, indépendamment du toggle.

#### À savoir

- Le sélecteur de période générique (utilisé par les autres rapports) est volontairement absent ici : la Cartes pivote autour d'un mois unique avec comparaisons automatiques, donc seul le sélecteur de mois de référence est exposé
- Le taux d'épargne affiche « — » (pas « 0 % ») quand les revenus sont à zéro, pour distinguer « pas de revenus » de « revenus = dépenses »

### Rapport Tendances (`/reports/trends`)

- **Flux global** : revenus vs dépenses vs solde net sur la période, en graphique d'aires ou tableau
- **Par catégorie** : évolution de chaque catégorie, en lignes ou tableau pivot

### Rapport Comparables (`/reports/compare`)

Trois modes accessibles via un tab bar :

- **Mois vs mois précédent** — tableau catégories × 2 colonnes + écart $ et %
- **Année vs année précédente** — même logique sur 12 mois vs 12 mois
- **Réel vs budget** — reprend la vue Budget vs Réel avec ses totaux mensuels et cumul annuel

### Rapport Zoom catégorie (`/reports/category`)

Choisissez une catégorie dans la combobox en haut. Par défaut le rapport inclut automatiquement les sous-catégories (toggle *Directe seulement* pour les exclure). Vous voyez :

- Un **donut chart** de la répartition par sous-catégorie avec le total au centre
- Un graphique d'évolution mensuelle de la catégorie
- Un tableau triable des transactions

### Édition contextuelle des mots-clés

**Clic droit** sur n'importe quelle transaction (dans le zoom catégorie, la liste des faits saillants, ou la page Transactions) ouvre un menu *Ajouter comme mot-clé*. Un dialog affiche :

1. Une **prévisualisation** des transactions qui seront recatégorisées (jusqu'à 50 visibles avec cases à cocher individuelles — les matches au-delà de 50 peuvent être appliqués via une case explicite)
2. Un sélecteur de catégorie cible
3. Un bouton **Appliquer et recatégoriser**

L'application est atomique : soit toutes les transactions cochées sont recatégorisées et le mot-clé enregistré, soit rien n'est fait. Si le mot-clé existait déjà pour une autre catégorie, un prompt vous demande si vous voulez le réassigner — cela ne touche **pas** l'historique, seulement les transactions visibles cochées.

### Astuces

- Le toggle **graphique / tableau** est mémorisé par sous-rapport (vos préférences restent même après redémarrage)
- Les mots-clés doivent faire entre 2 et 64 caractères (protection contre les regex explosives)
- Le zoom catégorie est **protégé contre les arborescences cycliques** : un éventuel `parent_id` malformé ne fait pas planter l'app

---

## 10. 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.

### Fonctionnalités

- Affichage de la version de l'application
- Guide d'utilisation complet accessible directement depuis les paramètres
- Vérification automatique des mises à jour avec installation en un clic
- Journaux de l'application (logs) consultables avec filtres par niveau, copie et effacement
- Envoi de feedback optionnel vers `feedback.lacompagniemaximus.com` (exception explicite au fonctionnement 100 % local — déclenche une demande de consentement avant le premier envoi)
- Export des données (transactions, catégories, ou les deux) en format JSON ou CSV
- Import des données depuis un fichier exporté précédemment
- Chiffrement AES-256-GCM optionnel pour les fichiers exportés

### Comment faire

1. Cliquez sur Guide d'utilisation pour accéder à la documentation complète
2. Cliquez sur Vérifier les mises à jour pour voir si une nouvelle version est disponible
3. Consultez la section Journaux pour voir les logs de l'application — filtrez par niveau (Tout, Error, Warn, Info), copiez ou effacez
4. Pour partager une suggestion ou signaler un problème, cliquez sur Envoyer un feedback dans la carte Journaux ; les cases d'identification et d'ajout du contexte/logs sont décochées par défaut
5. Utilisez la section Gestion des données pour exporter ou importer vos données
6. Lors de l'export, choisissez ce qu'il faut inclure et définissez optionnellement un mot de passe pour le chiffrement
7. Lors de l'import, sélectionnez un fichier exporté précédemment — les fichiers chiffrés demanderont le mot de passe

### Astuces

- Les mises à jour ne remplacent que le programme — votre base de données n'est jamais modifiée
- Changez la langue de l'application via le sélecteur de langue dans la barre latérale
- Exportez régulièrement pour garder une sauvegarde de vos données
- Le guide d'utilisation peut être imprimé ou exporté en PDF via le bouton Imprimer
- Les journaux persistent pendant la session — ils survivent à un rafraîchissement de la page
- Le feedback est la seule fonctionnalité qui communique avec un serveur en dehors des mises à jour et de la connexion Maximus — chaque envoi est explicite, aucune télémétrie automatique
- En cas de problème, cliquez Envoyer un feedback et cochez « Inclure les derniers logs d'erreur » pour joindre les journaux récents automatiquement