Definition 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 tiers rempli.

• 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 = true uniquement.

• 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_types`` pour 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) :

1. Résolution ISIN → ticker via OpenFIGI, avec cache (les mappings ne changent pas).

2. Cours actions/ETF via Yahoo Finance.

3. Cours crypto via une API type CoinGecko.

4. 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_snapshot rend 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)

1. Ingestion des prix de clôture dans price_history.

2. Calcul des positions : quantités et PRU par compte/instrument depuis les transactions validées → écriture des position_snapshot du jour, puis recalcul de la fenêtre de projection J+1 → J+X (transactions validées + non validées).

3. 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é :

1. Socle : repo, docker-compose, base PostgreSQL, framework, migrations.

2. Schéma et migrations : les 8 tables, contraintes CHECK (règle source/dest), NUMERIC partout pour les montants, index sur (account_id, instrument_id, date) des snapshots et sur la date des transactions.

3. CRUD comptes, instruments, transactions, enveloppes + validations applicatives (enveloppes ≤ solde, cohérence source/dest). → À ce stade, base fonctionnelle en saisie manuelle.

4. Pipeline de prix : OpenFIGI (cache) + Yahoo Finance + CoinGecko → price_history.

5. Moteur de snapshots : fonction recompute_position, job quotidien trois passes, mode backfill, gestion du dernier prix connu.

6. Moteur de récurrence : génération idempotente via generated_until, RRULE (lib type dateutil.rrule), action de régénération explicite, liste « à traiter » des transactions échues non validées.

7. Endpoints de restitution : historique par compte/position/agrégé, projection, détail enveloppes — de simples SELECT sur les snapshots.

8. 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.