Simpl-Resultat/docs/architecture.md

Architecture technique — Simpl'Résultat

Document mis à jour le 2026-04-25 — Version 0.8.x (Bilan)

Stack technique

Couche	Technologie	Version
Framework desktop	Tauri	v2
Frontend	React	19.1
Langage frontend	TypeScript	5.8
Bundler	Vite	6.4
CSS	Tailwind CSS	v4
Backend	Rust (via Tauri)	stable
Base de données	SQLite (tauri-plugin-sql)	—
Graphiques	Recharts	3.7
Icônes	Lucide React	0.563
i18n	i18next + react-i18next	25.8 / 16.5
Drag & Drop	@dnd-kit	6.3 / 10.0
CSV	PapaParse	5.5
Chiffrement	aes-gcm (Rust)	0.10
Hachage PIN	Argon2 (Rust)	0.5

Structure du projet

simpl-resultat/
├── src/                          # Frontend React/TypeScript
│   ├── components/               # 58 composants organisés par domaine
│   │   ├── adjustments/          # 3 composants
│   │   ├── balance/              # 8 composants Bilan (AccountForm, BalanceAccountsTable, BalanceEvolutionChart, BalanceOnboardingCard, BalanceOverviewCard, LinkTransfersModal, SnapshotEditor, SnapshotLineRow)
│   │   ├── budget/               # 5 composants
│   │   ├── categories/           # 5 composants
│   │   ├── dashboard/            # 2 composants
│   │   ├── import/               # 13 composants (wizard d'import)
│   │   ├── layout/               # AppShell, Sidebar
│   │   ├── profile/              # 3 composants (PIN, formulaire, switcher)
│   │   ├── reports/              # ~25 composants (hub, faits saillants, tendances, comparables, zoom catégorie)
│   │   ├── settings/             # 5 composants (+ LogViewerCard, LicenseCard, AccountCard)
│   │   ├── shared/               # 6 composants réutilisables
│   │   └── transactions/         # 5 composants
│   ├── contexts/                 # ProfileContext (état global profil)
│   ├── hooks/                    # 18+ hooks custom (useReducer, 5 hooks rapports par domaine)
│   ├── pages/                    # 14 pages (dont 4 sous-pages rapports)
│   ├── services/                 # 14 services métier
│   ├── shared/                   # Types et constantes partagés
│   ├── utils/                    # 4 utilitaires (parsing, CSV, charts)
│   ├── i18n/                     # Config i18next + locales FR/EN
│   ├── App.tsx                   # Router principal
│   └── main.tsx                  # Point d'entrée
├── src-tauri/                    # Backend Rust
│   ├── src/
│   │   ├── commands/             # 6 modules de commandes Tauri
│   │   │   ├── fs_commands.rs
│   │   │   ├── export_import_commands.rs
│   │   │   ├── profile_commands.rs
│   │   │   ├── license_commands.rs
│   │   │   ├── auth_commands.rs
│   │   │   └── entitlements.rs
│   │   ├── database/             # Schémas SQL et migrations
│   │   │   ├── schema.sql
│   │   │   ├── seed_categories.sql
│   │   │   └── consolidated_schema.sql
│   │   ├── lib.rs                # Point d'entrée, migrations, plugins
│   │   └── main.rs
│   ├── capabilities/             # Permissions Tauri
│   └── Cargo.toml
├── .github/workflows/            # CI/CD
│   └── release.yml
├── docs/                         # Documentation technique
└── config/                       # Configuration

Base de données

Tables (20)

Table	Description
import_sources	Configuration des sources d'import CSV
imported_files	Suivi des fichiers importés (hash anti-doublons)
categories	Catégories hiérarchiques (dépenses/revenus)
suppliers	Fournisseurs avec auto-catégorisation
keywords	Mots-clés pour catégorisation automatique
transactions	Transactions individuelles
adjustments	Ajustements manuels (ponctuels ou récurrents)
adjustment_entries	Montants par catégorie pour chaque ajustement
budget_entries	Allocations budgétaires mensuelles par catégorie
budget_templates	Modèles de budget réutilisables
budget_template_entries	Catégories et montants dans les modèles
import_config_templates	Modèles prédéfinis de config d'import
user_preferences	Préférences applicatives (clé-valeur)
balance_categories	Taxonomie des classes d'actif (Liquidités, Fonds/FNB, Actions, Crypto, Autres) — kind ∈ {simple, priced} (défaut suggéré pour les nouveaux comptes), custom_label pour le renommage bilingue-safe (v12). Les ex-types véhicules (TFSA/RRSP) ont migré vers balance_accounts.vehicle_type (Étape 1, v12/v13, ADR 0014)
balance_accounts	Comptes de bilan (rattachés à une catégorie). currency hardcodée à CAD au MVP via CHECK. archived_at pour soft-delete. vehicle_type (enveloppe fiscale nullable, v12, ADR 0014). kind ∈ {simple, detailed} + detailed_since (pivot faisant autorité, v15, ADR 0015) — porte désormais l'axe simple/détaillé (auparavant dérivé de category.kind). Issue #179 : 4 comptes de départ seedés (consolidated_schema.sql) + proposés aux profils existants via StarterAccountsModal
balance_snapshots	Snapshots datés (snapshot_date UNIQUE) — éditer = mettre à jour les lignes, pas dupliquer
balance_snapshot_lines	Une ligne par (snapshot, compte) — source de vérité agrégée. simple : value seul. priced/detailed : la ligne porte la valeur totale (value = SUM(holdings.value), quantity/unit_price NULL pour un compte détaillé), le détail vit dans balance_snapshot_holdings. Les agrégateurs et Modified Dietz lisent uniquement cette value (ADR 0015)
balance_account_transfers	Liaison transactions ↔ balance_accounts avec direction ∈ {in, out}. Utilisée par le calcul Modified Dietz pour séparer apports et gains
balance_securities	Table normalisée et partagée des titres (v14, ADR 0015) : symbol UNIQUE COLLATE NOCASE (canonique upper/trim), currency (DEFAULT CAD, préparé multi-devise), asset_type ∈ {stock, crypto}, name?. Référencée en ON DELETE RESTRICT → un titre référencé est immortel (suppression masquée UI)
balance_snapshot_holdings	Détail par titre d'un compte détaillé, rattaché à sa ligne de snapshot agrégée (v14, ADR 0015) : snapshot_line_id (FK CASCADE), security_id (FK RESTRICT), quantity, unit_price, value (= qty × prix, arrondi cent), book_cost? (gain latent = value − book_cost), price_source?, price_fetched_at?. UNIQUE(snapshot_line_id, security_id)

Index (24)

Index existants (15) : transactions (date, category, supplier, source, file, parent), categories (parent, type), suppliers (category, normalized_name), keywords (category, keyword), budget_entries (year, month), adjustment_entries (adjustment_id), imported_files (source).

Index Bilan (9) — 7 ajoutés en v9 :

• idx_balance_accounts_category (FK lookup catégorie → comptes)
• idx_balance_accounts_active partiel WHERE is_active = 1 (filtre liste active)
• idx_balance_snapshot_lines_snapshot (chargement d'un snapshot)
• idx_balance_snapshot_lines_account (historique par compte)
• idx_balance_account_transfers_account (cash flows Modified Dietz par compte)
• idx_balance_account_transfers_transaction (lookup icône d'attribution dans TransactionTable)
• idx_balance_snapshots_date (sélecteur de période + agrégation chronologique)

2 ajoutés en v14 (Étape 2 — détail par titre) :

• idx_balance_snapshot_holdings_line (chargement des positions d'une ligne de snapshot)
• idx_balance_snapshot_holdings_security (FK lookup titre → positions, garde ON DELETE RESTRICT)

Invariants Bilan (CHECK + FK)

• balance_categories.kind ∈ ('simple','priced') (défaut suggéré pour les nouveaux comptes ; l'axe agrégé/détaillé est désormais porté par balance_accounts.kind)
• balance_accounts.currency = 'CAD' (verrou MVP — v2 lèvera ce CHECK avec table de taux)
• balance_accounts.vehicle_type ∈ ('unregistered','tfsa','rrsp','rrif','fhsa','resp') ou NULL (enveloppe fiscale, v12, ADR 0014)
• balance_accounts.kind ∈ ('simple','detailed') (v15, ADR 0015) — un compte detailed à/après detailed_since doit porter des holdings (validation TS validateDetailedSnapshot, pivot faisant autorité)
• balance_snapshot_lines : (quantity, unit_price) doivent être tous deux NULL (kind simple) OU tous deux NOT NULL (kind priced) ; pour un compte detailed, la ligne agrégée porte value = SUM(holdings.value) (comparaison exacte au cent), quantity/unit_price NULL
• balance_securities.symbol UNIQUE COLLATE NOCASE ; asset_type ∈ ('stock','crypto')
• balance_snapshot_holdings : UNIQUE (snapshot_line_id, security_id) (un titre une seule fois par ligne)
• balance_account_transfers.direction ∈ ('in','out') ; UNIQUE (transaction_id, account_id) (une transaction ne peut pas être liée deux fois au même compte)
• FK balance_accounts.balance_category_id → balance_categories(id) ON DELETE RESTRICT (empêche suppression de catégorie avec comptes liés)
• FK balance_snapshot_lines.snapshot_id → balance_snapshots(id) ON DELETE CASCADE (supprimer un snapshot supprime ses lignes)
• FK balance_snapshot_lines.account_id → balance_accounts(id) ON DELETE RESTRICT (préserve l'historique)
• FK balance_snapshot_holdings.snapshot_line_id → balance_snapshot_lines(id) ON DELETE CASCADE (supprimer une ligne/snapshot emporte ses holdings)
• FK balance_snapshot_holdings.security_id → balance_securities(id) ON DELETE RESTRICT — un titre référencé est immortel (préserve l'historique, miroir de la règle transferts), voir ADR 0015
• FK balance_account_transfers.account_id → balance_accounts(id) ON DELETE CASCADE
• FK balance_account_transfers.transaction_id → transactions(id) ON DELETE RESTRICT — décision structurante pour la reproductibilité Modified Dietz, voir ADR 0010

Système de migrations

Les migrations sont définies inline dans src-tauri/src/lib.rs via tauri_plugin_sql::Migration :

#	Version	Description
1	v1	Schéma initial (13 tables)
2	v2	Seed des catégories et mots-clés
3	v3	Ajout has_header sur import_sources
4	v4	Ajout is_inputable sur categories
5	v5	Création de import_config_templates
6	v6	Changement contrainte unique imported_files (hash → filename)
7	v7	Ajout sous-catégories d'assurance (niveau 3)
8	v8	Migration de catégories (cf. release 0.8.x)
9	v9	Schéma Bilan : 5 tables + 7 index + seed des 7 catégories standard (cash, TFSA, RRSP, fund, stock, crypto, other)
10	v10	Ajout asset_type sur balance_categories (stock/crypto) + backfill des 2 catégories cotées
11	v11	Nettoyage des snapshots Bilan orphelins
12	v12	Étape 1 : balance_accounts.vehicle_type (+ CHECK, backfill ex-CELI/REER) + balance_categories.custom_label (+ backfill défensif du bug i18n) — ADR 0014
13	v13	Étape 1 : reclasse les comptes ex-tfsa/rrsp vers « Autres », désactive les seeds enveloppes (idempotente) — ADR 0014
14	v14	Étape 2 : balance_securities + balance_snapshot_holdings + 2 index (additive) — ADR 0015
15	v15	Étape 2 : balance_accounts.kind (simple/detailed) + detailed_since + backfill depuis category.kind (priced → detailed) — ADR 0015
16	v16	Étape 2 : conversion des comptes cotés existants en détaillés 1-position (security + holding miroir, gardée anti-perte, idempotente) — ADR 0015

Pour les nouveaux profils, le fichier consolidated_schema.sql contient le schéma complet avec toutes les migrations pré-appliquées (pas besoin de rejouer les migrations).

Services TypeScript (18)

Service	Responsabilité
db.ts	Wrapper de connexion (tauri-plugin-sql)
profileService.ts	Gestion des profils
categoryService.ts	CRUD catégories hiérarchiques
transactionService.ts	CRUD et filtrage des transactions ; détection d'erreurs FK RESTRICT pour transactions liées à un compte de bilan (typed TransactionLinkedToBalanceError)
importSourceService.ts	Configuration des sources d'import
importedFileService.ts	Suivi des fichiers importés
importConfigTemplateService.ts	Modèles de configuration d'import
categorizationService.ts	Catégorisation automatique + helpers édition de mot-clé (validateKeyword, previewKeywordMatches, applyKeywordWithReassignment)
adjustmentService.ts	Gestion des ajustements
budgetService.ts	Gestion budgétaire
dashboardService.ts	Agrégation données tableau de bord
reportService.ts	Génération de rapports : getMonthlyTrends, getCategoryOverTime, getHighlights, getCompareMonthOverMonth, getCompareYearOverYear, getCategoryZoom (CTE récursive bornée anti-cycle), getCartesSnapshot (snapshot dashboard Cartes, requêtes parallèles)
dataExportService.ts	Export de données (chiffré)
userPreferenceService.ts	Stockage préférences utilisateur
logService.ts	Capture des logs console (buffer circulaire, sessionStorage)
licenseService.ts	Validation et gestion de la clé de licence (appels commandes Tauri)
authService.ts	OAuth2 PKCE / Compte Maximus (appels commandes Tauri auth_*)
balance.service.ts	Domaine Bilan — service unique avec 4 sections logiques (voir détail ci-dessous)

Service Bilan — balance.service.ts

Un seul service par convention projet (1 service par domaine, splitter seulement > ~400 lignes). Quatre sections logiques distinctes :

1. CRUD catégories + comptes + titres — listBalanceCategories, createBalanceCategory, updateBalanceCategory, archiveBalanceCategory (refus si comptes liés via FK RESTRICT, refus si is_seed = 1), listBalanceAccounts, createBalanceAccount, updateBalanceAccount (garde detailed → simple refusée si des holdings existent, erreur typée), archiveBalanceAccount. Securities (Étape 2) : listSecurities, getSecurity, findOrCreateSecurity (UPSERT sur symbol normalisé upper/trim, asset_type requis), updateSecurity. Le service garde une BalanceServiceError typée (BalanceErrorCode) pour des messages i18n distincts (currency_unsupported, category_seed_protected, category_has_accounts, account_kind_detailed_has_holdings, etc.).
2. Snapshots + lines + holdings — listBalanceSnapshots, getBalanceSnapshotByDate, upsertSnapshot (création + édition par date), upsertSnapshotLines (rewrite-all : DELETE WHERE snapshot_id puis INSERT par ligne). Save détaillé (Étape 2) : pour un compte detailed, la ligne agrégée (value = somme des holdings) et ses holdings sont écrits dans la même transaction (BEGIN/COMMIT), value recalculée = SUM(holdings.value) (chaque holding arrondi au cent, comparaison exacte). validateLineKindInvariants (simple, inchangé, tolérance PRICED_VALUE_TOLERANCE = 0.01) + nouvelle passe validateDetailedSnapshot(account.kind, line, holdings) (detailed + holdings ⇒ ligne agrégée ET value = SUM ; detailed pré-pivot ⇒ agrégé toléré). getHoldingsForLatestSnapshot (pré-remplissage : titres + qty + book_cost reportés, qty-0 exclus), listHoldingsBySnapshotLine (drill-down), computeUnrealizedGain (gain latent value − book_cost en valeur + %, garde-fou book_cost = 0/NULL → « N/A », agrégeable par classe/enveloppe). deleteSnapshot.
3. Returns + transfers — linkTransfer, unlinkTransfer, listAccountTransfers, listAllLinkedTransfersForTooltip (un coup pour la Map.has(txId) consommée par l'icône d'attribution dans TransactionTable), computeAccountReturn (wrapper sur la commande Tauri compute_account_return qui lit db_filename du profil actif via loadProfiles()).
4. Prices — (Phase 5, livraison reportée à l'Issue #143). La forme prévue : fetchPrice(symbol, date) invoquant fetch_price (Tauri), avec rate-limit client (1/2s), backoff exponentiel et dedup in-flight. Voir ADR 0009 pour l'architecture proxy.

Le CRUD passe par getDb() + tauri-plugin-sql direct, jamais via une commande Tauri — convention projet. Les commandes Rust sont réservées au filesystem, OAuth, license, profils, feedback et au seul calcul Modified Dietz (qui a besoin d'arithmétique de dates chrono).

Hooks (17+)

Chaque hook encapsule la logique d'état via useReducer :

Hook	Domaine
useCategories	Catégories avec hiérarchie
useTransactions	Transactions et filtrage
useDataImport	Import de données
useImportWizard	Assistant d'import multi-étapes
useImportHistory	Historique des imports
useAdjustments	Ajustements
useBudget	Budget
useDashboard	Métriques du tableau de bord
useReportsPeriod	Période de reporting synchronisée via query string (bookmarkable)
useHighlights	Panneau de faits saillants du hub rapports
useTrends	Rapport Tendances (sous-vue flux global / par catégorie)
useCompare	Rapport Comparables (mode actual/budget, sous-toggle MoM ↔ YoY, mois de référence explicite avec wrap-around janvier)
useCategoryZoom	Rapport Zoom catégorie avec rollup sous-catégories
useCartes	Rapport Cartes (snapshot KPI + sparklines + top movers + budget + saisonnalité via getCartesSnapshot)
useBalanceAccounts	Bilan — état de la page /balance/accounts : CRUD comptes ET catégories (un seul hook pour les deux onglets, aligné sur la convention "1 hook par page")
useSnapshotEditor	Bilan — cycle de vie d'un snapshot unique (/balance/snapshot) : valeurs simple (string) + valeurs priced ({quantity, unit_price} strings), prefill depuis snapshot précédent, save (rewrite-all), delete avec double-confirmation par re-saisie de la date
useBalanceOverview	Bilan — page /balance : sélecteur de période (3M / 6M / 1A / 3A / Tout), série temporelle agrégée, mode chart (line / stacked), tableau des comptes avec valeurs courantes et Δ% sur la période. Les rendements multi-horizons sont chargés lazily dans BalanceAccountsTable (un appel compute_account_return par cellule)
useDataExport	Export de données
useTheme	Thème clair/sombre
useUpdater	Mise à jour de l'application (gated par entitlement licence)
useLicense	État de la licence et entitlements
useAuth	Authentification Compte Maximus (OAuth2 PKCE, subscription status)

Commandes Tauri (36)

fs_commands.rs — Système de fichiers (6)

• scan_import_folder — Scan récursif de dossier pour fichiers CSV/TXT
• read_file_content — Lecture avec gestion de l'encodage
• hash_file — Hash SHA-256 (détection de doublons)
• detect_encoding — Détection auto (UTF-8, Windows-1252, ISO-8859-15)
• get_file_preview — Aperçu des N premières lignes
• pick_folder — Dialogue de sélection de dossier

export_import_commands.rs — Export/Import de données (5)

• pick_save_file — Dialogue de sauvegarde
• pick_import_file — Dialogue de sélection de fichier
• write_export_file — Écriture fichier chiffré (format SREF)
• read_import_file — Lecture fichier chiffré
• is_file_encrypted — Vérification magic SREF

profile_commands.rs — Gestion des profils (7)

• load_profiles — Chargement depuis profiles.json
• save_profiles — Sauvegarde de la configuration
• delete_profile_db — Suppression du fichier de base de données
• get_new_profile_init_sql — Récupération du schéma consolidé
• hash_pin — Hachage Argon2id du PIN (format argon2id:salt:hash)
• verify_pin — Vérification du PIN (supporte Argon2id et legacy SHA-256 pour rétrocompatibilité)
• repair_migrations — Réparation des checksums de migration (rusqlite)

license_commands.rs — Licence et activation machine (10)

• validate_license_key — Validation offline d'une clé de licence (JWT Ed25519)
• store_license — Stockage de la clé dans le répertoire app data
• store_activation_token — Stockage du token d'activation
• read_license — Lecture de la licence stockée
• get_edition — Détection de l'édition active (free/base/premium)
• get_machine_id — Génération d'un identifiant machine unique
• activate_machine — Activation en ligne (appel API serveur de licences, issue #49)
• deactivate_machine — Désactivation d'une machine enregistrée
• list_activated_machines — Liste des machines activées pour la licence
• get_activation_status — État d'activation de la machine courante

auth_commands.rs — Compte Maximus / OAuth2 PKCE (5)

• start_oauth — Génère un code verifier PKCE et retourne l'URL d'authentification Logto
• refresh_auth_token — Rafraîchit l'access token via le refresh token
• get_account_info — Lecture du cache d'affichage (via account_cache::load_unverified, accepte les payloads legacy)
• check_subscription_status — Vérifie l'abonnement (max 1×/jour, fallback cache gracieux). Déclenche aussi la migration tokens.json → keychain via token_store::load
• logout — Efface tokens (token_store) + cache signé (account_cache) + clé HMAC du keychain

Note : handle_auth_callback n'est PAS exposée comme commande — elle est appelée depuis le handler deep-link on_open_url dans lib.rs. Voir section "OAuth2 et deep-link" plus bas.

token_store.rs — Stockage des tokens OAuth (1)

• get_token_store_mode — Retourne "keychain", "file" ou null. Utilisé par la bannière de sécurité TokenStoreFallbackBanner dans Settings pour alerter l'utilisateur quand les tokens sont dans le fallback fichier.

Module non-command : save, load, delete, store_mode — toute la logique de persistance passe par ce module, auth_commands.rs ne touche jamais directement tokens.json. Voir l'ADR 0006 pour la conception complète.

account_cache.rs — Cache d'abonnement signé (aucune commande)

Module privé appelé uniquement par auth_commands.rs et license_commands.rs. Expose :

• save(app, &AccountInfo) — écrit l'enveloppe signée {data, sig} dans account.json, avec clé HMAC-SHA256 stockée dans le keychain.
• load_unverified(app) — lecture pour affichage UI (accepte legacy et signé).
• load_verified(app) — lecture pour gating licence (refuse legacy, tampering, absence de clé). Utilisé par license_commands::check_account_edition.
• delete(app) — efface le fichier et la clé HMAC du keychain.

entitlements.rs — Entitlements (1)

• check_entitlement — Vérifie si une feature est autorisée selon l'édition
  • Source de vérité : FEATURE_TIERS dans entitlements.rs. Modifier cette constante pour changer les gates, jamais ailleurs dans le code
  • Temporaire : auto-update est ouvert à free en attendant le serveur de licences (issue #49). À re-gater à [base, premium] quand l'activation payante sera live

balance_commands.rs — Bilan (1)

• compute_account_return(account_id, period_start, period_end, db_filename) — Calcul Modified Dietz d'un compte sur une période. Ouvre une connexion rusqlite courte sur le fichier DB du profil actif, lit le snapshot ≤ period_start, le snapshot ≥ period_end et tous les balance_account_transfers JOIN transactions dans la fenêtre, puis appelle return_calculator::modified_dietz. Retourne AccountReturn { value_start, value_end, net_contributions, return_pct, annualized_pct, is_partial, has_no_transfers_warning }. Voir ADR 0008.

Le module privé return_calculator.rs (déclaré dans commands/mod.rs mais non exposé comme commande) contient la logique pure Modified Dietz et ses tests #[cfg(test)] mod tests co-localisés (TDD, 7 cas : nominal / pas de snapshot début / partial / créé en cours / vidé / sans transferts / annualisation).

À venir Phase 5 (Issue #143, BLOCKED par maximus-api Phase 2) : commande fetch_price(symbol, date) pour le price-fetching premium via proxy maximus-api. L'architecture est documentée dans l'ADR 0009 ; la livraison est différée jusqu'à ce que le serveur de licences (maximus-api) expose l'endpoint GET /v1/prices.

Plugins Tauri

Ordre d'initialisation dans lib.rs (certains plugins ont des contraintes d'ordre) :

Plugin	Rôle	Contrainte
tauri-plugin-single-instance	Empêche les doubles lancements et forwarde les URLs deep-link au processus existant	Doit être le premier plugin ; feature deep-link requise pour le forwarding d'URL
tauri-plugin-opener	Ouverture d'URLs externes et de fichiers	—
tauri-plugin-dialog	Dialogues de sélection de fichier/dossier	—
tauri-plugin-process	Relaunch après mise à jour	—
tauri-plugin-deep-link	Gère le scheme custom simpl-resultat://	Doit être initialisé avant setup() pour que on_open_url soit disponible
tauri-plugin-updater	Mise à jour auto (gated par entitlement auto-update)	Initialisé dans setup() derrière #[cfg(desktop)]
tauri-plugin-sql	SQLite + migrations	Doit être initialisé avec les migrations pour que le schéma soit prêt

OAuth2 et deep-link (Compte Maximus)

Flow complet (v0.7.3+) :

1. Frontend appelle start_oauth → génère un code verifier PKCE (64 chars), le stocke dans OAuthState (Mutex en mémoire du processus), retourne l'URL Logto
2. Frontend ouvre l'URL via tauri-plugin-opener → le navigateur système affiche la page Logto
3. L'utilisateur s'authentifie (ou Logto auto-consent si session existante) → redirection 303 vers simpl-resultat://auth/callback?code=...
4. L'OS route le custom scheme vers une nouvelle instance de l'app → tauri-plugin-single-instance (feature deep-link) détecte l'instance existante, ne démarre PAS un nouveau processus, et forwarde l'URL à l'instance vivante
5. Le callback app.deep_link().on_open_url(...) enregistré via DeepLinkExt reçoit les URLs. Pour chaque URL :
   • Si un param code est présent → appelle handle_auth_callback (token exchange vers /oidc/token, fetch /oidc/me, écriture des tokens via token_store::save (keychain OS, fallback fichier 0600) + cache signé via account_cache::save (HMAC-SHA256), émission de l'event auth-callback-success)
   • Si un param error est présent → émission de l'event auth-callback-error avec error: error_description
6. Le hook useAuth (frontend) écoute auth-callback-success / auth-callback-error et met à jour l'état

Pourquoi cet enchaînement est critique :

• Sans tauri-plugin-single-instance : une nouvelle instance démarre à chaque callback, le OAuthState est vide (pas de verifier), le token exchange échoue
• Sans on_open_url : l'ancien listener app.listen("deep-link://new-url", ...) ne recevait pas les URLs forwardées par single-instance. L'API canonique v2 via DeepLinkExt est nécessaire
• Sans gestion des erreurs : un callback ?error=... laissait l'UI bloquée en état "loading" infini

Fichiers : src-tauri/src/lib.rs (wiring), src-tauri/src/commands/auth_commands.rs (PKCE + token exchange), src-tauri/src/commands/token_store.rs (persistance keychain + fallback), src-tauri/src/commands/account_cache.rs (cache signé HMAC), src/hooks/useAuth.ts (frontend), src/components/settings/TokenStoreFallbackBanner.tsx (UI de l'état dégradé).

Pages et routing

Le routing est défini dans App.tsx. Toutes les pages sont englobées par AppShell (sidebar + layout). L'accès est contrôlé par ProfileContext (gate).

Gestion d'erreurs

• ErrorBoundary (class component) : wrape <App /> dans main.tsx, attrape les crashs React et affiche ErrorPage en fallback
• ErrorPage : page d'erreur réutilisable avec détails techniques (collapsible), bouton "Actualiser", vérification de mises à jour, et liens de contact/issues
• Timeout au démarrage : App.tsx applique un timeout de 10 secondes sur connectActiveProfile() — affiche ErrorPage au lieu d'un spinner infini si la connexion DB échoue
• Retry au démarrage : connectActiveProfile() réessaie jusqu'à 3 fois avec 1s de délai avant d'afficher l'erreur
• Réparation de migrations : repair_migrations (Rust/rusqlite) supprime les checksums invalides de _sqlx_migrations avant le chargement de la DB
• Log viewer : logService.ts capture les console.log/warn/error dans un buffer circulaire (500 entrées, persisté en sessionStorage), affiché dans la page Paramètres via LogViewerCard

Route	Page	Description
/	DashboardPage	Tableau de bord (résumé, pie chart, budget vs réel, dépenses dans le temps)
/import	ImportPage	Assistant d'import CSV
/transactions	TransactionsPage	Liste avec filtres
/categories	CategoriesPage	Gestion hiérarchique
/adjustments	AdjustmentsPage	Ajustements manuels
/budget	BudgetPage	Planification budgétaire
/reports	ReportsPage	Hub des rapports : panneau faits saillants + 4 cartes de navigation
/reports/highlights	ReportsHighlightsPage	Faits saillants détaillés (soldes, top mouvements, top transactions)
/reports/trends	ReportsTrendsPage	Tendances (flux global + par catégorie)
/reports/compare	ReportsComparePage	Comparables (MoM / YoY / Réel vs budget)
/reports/category	ReportsCategoryPage	Zoom catégorie avec rollup + édition contextuelle de mots-clés
/reports/cartes	ReportsCartesPage	Tableau de bord KPI avec sparklines, top movers, budget et saisonnalité
/balance	BalancePage	Bilan — vue d'ensemble : carte "Aujourd'hui" + Δ% + avertissement bilan pas à jour > 60j, graphique d'évolution (toggle ligne / aire empilée par catégorie), tableau des comptes avec rendements multi-horizons (3M / 1A / depuis création — Modified Dietz) côte-à-côte avec rendement non-ajusté
/balance/snapshot	SnapshotEditPage	Saisie / édition d'un snapshot daté. Mode ?date=today (création) ou ?date=YYYY-MM-DD (édition, date immutable). Lignes groupées par catégorie : simple = champ valeur, priced = quantity × unit_price (value calculé read-only). Bouton "Pré-remplir depuis le snapshot précédent". Suppression à double-confirmation par re-saisie de la date
/balance/accounts	AccountsPage	CRUD comptes + catégories de bilan (deux onglets). Catégories seedées (is_seed = 1) renommables mais non-supprimables ; refus de suppression d'une catégorie avec comptes liés (FK RESTRICT)
/settings	SettingsLayout (layout) + SettingsHomePage (index)	Hub des paramètres : 3 cards-cluster vers les sous-pages. Le layout monte TokenStoreFallbackBanner une seule fois, partagé par les 4 routes principales
/settings/users	UsersSettingsPage	Comptes (Maximus), licences et guide d'utilisation (rendu inline depuis DocsContent)
/settings/data	DataSettingsPage	Catégories (avec liens vers /settings/categories/standard et /settings/categories/migrate), backup chiffré et confidentialité de la récupération de prix
/settings/systems	SystemsSettingsPage	Version, mise à jour (UpdateCard), historique des versions (ChangelogContent), journaux + commentaires (LogViewerCard)
/settings/categories/standard	CategoriesStandardGuidePage	Guide imprimable de la structure de catégories standard (route flat, hors SettingsLayout)
/settings/categories/migrate	CategoriesMigrationPage	Flux de migration v1→v2 (route flat, hors SettingsLayout)
/docs	DocsPage	Redirige vers /settings/users (rétrocompatibilité bookmarks)
/changelog	ChangelogPage	Redirige vers /settings/systems (rétrocompatibilité release notes)

Page spéciale : ProfileSelectionPage (affichée quand aucun profil n'est actif).

Internationalisation

• Librairie : i18next + react-i18next
• Langue par défaut : Français (fr)
• Langue de fallback : Anglais (en)
• Fichiers : src/i18n/locales/fr.json, src/i18n/locales/en.json
• Clés organisées hiérarchiquement par domaine (nav.*, dashboard.*, import.*, etc.)

CI/CD

Deux workflows Forgejo Actions (avec miroir GitHub) dans .forgejo/workflows/ :

check.yml — Vérifications sur branches et PR

Déclenché sur chaque push de branche (sauf main) et chaque PR vers main. Lance en parallèle :

• cargo check + cargo test (Rust)
• npm run build (tsc + vite)
• npm test (vitest)

Doit être vert avant tout merge. Évite de découvrir des régressions au moment du tag de release.

release.yml — Build et publication

Déclenché par les tags v*. Deux jobs :

1. build-windows (windows-latest) → Installeur .exe (NSIS)
2. build-linux (ubuntu-22.04) → .deb + .rpm

Fonctionnalités :

• Signature des binaires (clés TAURI_SIGNING_PRIVATE_KEY)
• JSON d'updater publié sur https://git.lacompagniemaximus.com/api/packages/maximus/generic/simpl-resultat/latest/latest.json
• Release Forgejo automatique avec assets et release notes extraites du CHANGELOG.md

Architecture Decision Records (ADRs)

Les ADRs documentent les décisions techniques structurantes. Ils vivent dans docs/adr/.

#	Titre	Date	Statut
0001	Choix de Tauri v2 comme framework desktop	2024-01-01	Accepted
0002	useReducer plutôt que Redux	2024-01-01	Accepted
0003	Migrations SQL inline via tauri-plugin-sql	2024-01-01	Accepted
0004	Chiffrement AES-256-GCM pour l'export	2024-01-01	Accepted
0005	Multi-profils avec bases SQLite séparées	2024-01-01	Accepted
0006	Stockage des tokens OAuth via keychain	2024-01-01	Accepted
0007	Refactorisation du hub de rapports	2024-01-01	Accepted
0008	Modified Dietz pour le calcul de rendement	2025-01-01	Accepted
0009	Proxy price-fetching via maximus-api	2025-01-01	Accepted
0010	FK RESTRICT sur balance_account_transfers	2025-01-01	Accepted
0011	Providers best-effort Yahoo	2026-04-26	Accepted
0012	Modèle à deux niveaux pour le Bilan (véhicules × compositions)	2026-05-01	Rejected
0013	Évaluation provider stocks : Alpha Vantage retenu comme cible	2026-05-09	Accepted
0014	Bilan : le véhicule fiscal est un attribut du compte (Étape 1)	2026-06-01	Accepted
0015	Bilan : détail par titre (holdings par snapshot, Étape 2)	2026-06-06	Accepted