Définition du projet#
Rapport de synthèse — conception du backend, juin 2026.
1. Vision et périmètre#
Application personnelle de suivi de patrimoine avec valorisation automatique quotidienne, couvrant trois classes d’actifs : monétaire (comptes courants, Livret A, PEL…), titres (actions, ETF…) et crypto.
Principes directeurs retenus au fil de la conception :
Tout est instrument, y compris la monnaie (modèle inspiré de Beancount/Ledger). L’euro est un instrument dont le prix vaut toujours 1. Un compte courant est un compte ne contenant qu’une position EUR ; un PEA contient une position EUR (espèces) et des positions ETF ; un wallet contient des positions crypto. Bonus : les devises étrangères sont gérées nativement (USD = instrument coté en EUR via
price_history).Pré-calcul systématique : la valeur de chaque position et de chaque compte est calculée et stockée jour par jour en base (snapshots). Toute lecture (graphique, historique) est un simple SELECT, jamais de recalcul à la volée.
Projection vers le futur : les comptes sont aussi valorisés sur un horizon de J+X jours grâce aux transactions futures, pour anticiper les échéances.
Pas de table d’état à maintenir : les positions (quantités, PRU) sont entièrement dérivées des transactions et figées dans les snapshots.
2. Modèle de transaction#
Une transaction est un échange atomique sur une seule ligne, modèle source/dest généralisé aux instruments :
transaction(
id,
date,
account_source_id, -- nullable
instrument_source_id,
quantite_source,
account_dest_id, -- nullable
instrument_dest_id,
quantite_dest,
tiers, -- nullable, pour les flux externes
label,
categorie,
envelope_id, -- nullable
validated, -- booléen
recurring_rule_id -- nullable, lien vers la règle génératrice
)
Cas couverts par ce modèle unique :
Virement : instrument source = instrument dest = EUR, mêmes quantités, deux comptes renseignés.
Flux externe (salaire, dépense) : un seul côté renseigné, l’autre entièrement null, champ
tiersrempli.Achat de titres : source = (compte, EUR, 950), dest = (compte, ETF, 10). Le prix unitaire est implicite (quantite_source / quantite_dest). L’atomicité est structurelle : impossible d’avoir une jambe orpheline.
Swap crypto : source = (wallet, BTC, 0.01), dest = (wallet, ETH, 0.15).
Frais : pas de gestion dédiée. Les frais sont absorbés dans les quantités échangées, donc dans le PRU — cohérent avec la convention fiscale française.
Contrainte CHECK : si les deux comptes sont renseignés, les deux triplets (instrument, quantité) le sont aussi ; si un seul côté existe, l’autre est entièrement null.
Les quantités sont en NUMERIC à précision généreuse (crypto : 8+
décimales, parts fractionnées), jamais de float pour des valeurs
financières.
3. Cycle de vie des transactions : le flag validated#
Mécanisme central de l’application, type pointage bancaire :
Une saisie manuelle d’une opération passée naît avec
validated = true.Le moteur de récurrence matérialise réellement les occurrences futures en base avec
validated = false. Chaque occurrence a une identité propre : elle peut être modifiée (date, montant), supprimée, puis validée individuellement selon les événements réels.Une seule colonne
date, modifiable tant que la transaction n’est pas validée (pas de distinction date prévue / date effective — l’objectif est l’historique du compte, pas le suivi des écarts).Une transaction non validée dont la date est dépassée ne disparaît pas : elle reste comptée dans la projection et remonte dans une liste « à traiter » jusqu’à validation ou suppression. Cette liste constituera l’écran de pointage quotidien côté frontend.
Règle de calcul des snapshots :
Snapshots passés et du jour : transactions
validated = trueuniquement.Snapshots projetés (J+1 → J+X) : transactions validées et non validées.
4. Récurrences#
recurring_rule(
id,
account_source_id, instrument_source_id, quantite_source,
account_dest_id, instrument_dest_id, quantite_dest,
tiers, label, categorie, envelope_id,
frequence, -- idéalement RRULE (RFC 5545) : couvre hebdo, bimensuel,
-- mensuel, trimestriel, semestriel, annuel, fins de mois...
date_debut, date_fin,
generated_until -- curseur d'idempotence
)
Le job de génération maintient un horizon : il s’assure qu’il existe
toujours des transactions générées jusqu’à J+X, et ne crée que les
occurrences au-delà de generated_until. Ce curseur garantit
l’idempotence sans jamais regarder les transactions existantes : une
fois générées, elles vivent leur vie (modifiables, supprimables) sans
que le job s’en soucie.
Conséquence assumée : modifier une règle ne régénère pas automatiquement les occurrences déjà créées. Prévoir une action explicite « régénérer les occurrences futures non validées de cette règle » (suppression + recréation). Comportement prévisible, pas de magie.
5. Comptes et enveloppes#
account(id, nom, type, devise_reference, plafond?, taux?)
envelope(id, account_id, nom, objectif, montant_alloue)
Un compte ne porte aucun solde : c’est un pur conteneur de positions, sa valeur est entièrement dérivée.
Les enveloppes sont strictement monétaires : ventilation logique de la position EUR d’un compte pour préparer des projets. Jamais de positions titres/crypto en enveloppe (ventiler des parts fluctuantes serait un cauchemar comptable). Validation applicative : la somme des enveloppes ne dépasse pas le solde du compte.
Pas de contrainte
allowed_instrument_typespour l’instant (YAGNI) : usage mono-utilisateur, garde-fou ajoutable plus tard par migration triviale si besoin. Si elle est ajoutée un jour, ce sera une liste de types par type de compte (un PEA autorise {devise, action, ETF}) — l’euro dans un compte titres reste toujours possible.
6. Instruments et prix#
instrument(id, type, code, devise_cotation)
-- type : devise, action, etf, crypto...
-- code : EUR, ISIN, ticker...
price_history(instrument_id, date, prix)
Pipeline de prix (réutilise l’existant du projet de portfolio) :
Résolution ISIN → ticker via OpenFIGI, avec cache (les mappings ne changent pas).
Cours actions/ETF via Yahoo Finance.
Cours crypto via une API type CoinGecko.
EUR : prix = 1, en dur ou ligne fixe.
Jours sans cotation (week-ends, fériés) : jours normaux sans
mouvement. Le job de snapshot tourne tous les jours et utilise le
dernier prix connu
(SELECT prix WHERE date <= jour ORDER BY date DESC LIMIT 1, ou
window function en backfill). Les quantités, elles, suivent normalement
les transactions (un virement ou un trade crypto peut exister un
dimanche).
7. Snapshots à deux niveaux#
position_snapshot(date, account_id, instrument_id, quantite, pru, prix_cloture, valeur)
account_snapshot(date, account_id, valeur) -- Σ des position_snapshots du jour
Le grain fin (
position_snapshot) donne l’historique de chaque ligne par construction : quantité de BTC, valeur de la ligne MSCI World jour par jour.Stocker quantité et valeur est volontairement redondant avec
price_history: la valorisation du jour est figée, insensible aux corrections ultérieures de prix, et lisible sans jointure.account_snapshotrend la lecture des graphiques et de l’agrégat patrimoine total triviale.Pour la projection (J+1 → J+X), le prix utilisé pour les titres/crypto est simplement le dernier connu.
PRU#
Historisé jour par jour dans position_snapshot → la plus-value
latente quotidienne s’obtient sans jointure :
valeur − quantite × pru.
Calcul en moyenne pondérée :
À chaque achat :
PRU = (qte_avant × PRU_avant + qte_achetee × prix_implicite) / qte_totale, avec prix implicite = quantite_source / quantite_dest de la transaction.À chaque vente : le PRU ne bouge pas, seule la quantité diminue.
Position revenue à zéro puis rachetée : le PRU repart de zéro (pas de moyenne avec l’historique mort).
Moteur de recalcul unique#
Le PRU et les quantités étant des états cumulatifs, toute modification
(INSERT/UPDATE/DELETE) d’une transaction validée antidatée invalide les
snapshots de la position concernée depuis la date de la transaction
modifiée. Une fonction unique
recompute_position(account_id, instrument_id, from_date) rejoue les
transactions chronologiquement, réécrit les position_snapshot puis
les account_snapshot en cascade. Le même moteur sert au backfill
initial et aux corrections. Les snapshots projetés sont invalidés et
recalculés à chaque changement de règle ou de transaction future.
8. Job quotidien (pipeline en trois passes)#
Ingestion des prix de clôture dans
price_history.Calcul des positions : quantités et PRU par compte/instrument depuis les transactions validées → écriture des
position_snapshotdu jour, puis recalcul de la fenêtre de projection J+1 → J+X (transactions validées + non validées).Agrégation en
account_snapshot.
Plus le job de génération des récurrences (maintien de l’horizon
generated_until) et la matérialisation déjà couverte par le modèle
validated.
9. Schéma final : 8 tables#
instrument, price_history, account, envelope,
transaction, recurring_rule, position_snapshot,
account_snapshot.
Chaîne logique : recurring_rule → transaction (échange
source/dest, cycle validated) → positions calculées →
position_snapshot (valorisé via price_history) →
account_snapshot.
10. Stack et étapes de mise en place#
Socle : PostgreSQL (TimescaleDB prématuré pour du quotidien mono-utilisateur), API REST ou GraphQL (FastAPI, Go, NestJS… au choix), docker-compose dès le départ, outil de migration (Alembic, Flyway…).
Ordre de réalisation recommandé :
Socle : repo, docker-compose, base PostgreSQL, framework, migrations.
Schéma et migrations : les 8 tables, contraintes CHECK (règle source/dest),
NUMERICpartout pour les montants, index sur (account_id, instrument_id, date) des snapshots et sur la date des transactions.CRUD comptes, instruments, transactions, enveloppes + validations applicatives (enveloppes ≤ solde, cohérence source/dest). → À ce stade, base fonctionnelle en saisie manuelle.
Pipeline de prix : OpenFIGI (cache) + Yahoo Finance + CoinGecko →
price_history.Moteur de snapshots : fonction
recompute_position, job quotidien trois passes, mode backfill, gestion du dernier prix connu.Moteur de récurrence : génération idempotente via
generated_until, RRULE (lib typedateutil.rrule), action de régénération explicite, liste « à traiter » des transactions échues non validées.Endpoints de restitution : historique par compte/position/agrégé, projection, détail enveloppes — de simples SELECT sur les snapshots.
Tests et durcissement : tests prioritaires sur le moteur de récurrence (idempotence, bimensuel, fins de mois, années bissextiles, préservation des occurrences éditées) et sur les recalculs rétroactifs (PRU, position à zéro puis rachat, transaction antidatée). Sécurité : données financières personnelles → authentification dès le backend même mono-utilisateur, pas de clés API en dur (architecture Bitwarden/Vault existante), chiffrement au repos si hébergement externe.
Le frontend sera traité ultérieurement ; le modèle validated fournit
déjà nativement le futur écran de pointage.
11. Décisions actées et questions ouvertes#
Acté : modèle échange source/dest une ligne ; pas de gestion des
frais ; une seule colonne date ; PRU historisé dans les snapshots avec
recalcul sur correction ; pas de contrainte de types d’instruments par
compte ; jours sans cotation = jours normaux, dernier prix connu ;
enveloppes strictement monétaires ; idempotence par generated_until.
À trancher au démarrage : choix du framework backend ; valeur de l’horizon X de projection ; format exact des fréquences (RRULE complet vs enum simple) ; politique de purge éventuelle des snapshots projetés.