Skip to content

Entity Map

Context

This page defines the main data entities used by the project and clarifies who reads and writes each one.

Details

Core entities and ownership: - Raw market input (data/tipranks_raw.csv): source-level input used by import workflows. - Fixture datasets (data_fixtures/*.csv): controlled test data for regression and scenario validation. - Portfolio holdings (titres): reference records whose portfolio currency is derived from the ticker (TSE: => CAD, otherwise USD). an_haut and an_bas remain raw source thresholds; the legacy _cad columns are schema-compatible copies, not converted thresholds. - Daily history (historique): one record per holding and date. valeur and devise are the native display price and currency. cad_value is the persisted CAD equivalent used only by the consolidated total, portfolio chart, and consolidated performance. fx_rate_used records a rate applied to a divergent current price and supplies the latest-snapshot rate shown on the dashboard. - Transactions du titre (transactions) : registre administratif distinct des relevés de marché, avec une référence au titre et un identifiant source conservé lors de l'amorçage. Les quantités et prix importés gardent jusqu'à quatre décimales ; les nouvelles saisies restent à deux décimales et le montant enregistré à deux décimales (ROUND_HALF_UP). Les règles du premier BUY, des ventes antidatées et des suppressions d'achats nécessaires aux ventes restent applicables. Le registre ne réécrit pas les snapshots. Un POST validé actualise également la position courante et les trois totaux courants du dashboard, sans modifier les graphiques ni les indicateurs historiques. - Demo transaction session: a short-lived copy of deterministic demo transactions and temporarily removed holding tickers. Deleting a holding's last BUY requires confirmation after all SELL transactions are gone, hides that holding from the dashboard, and blocks its detail page for the operation result. The next page refresh restores the complete baseline; the state is never written to the secure database, and 30 minutes of inactivity also triggers a fallback reset. - Quota state (logs/marketstack_quota_usage.json): current quota usage and mode transitions. - FX state (logs/fx_rate_state.json): last successful USD-to-CAD rate and retrieval timestamp, reused before a new exchange-rate API call. - Issue bridge state (logs/github_issue_bridge_state.json): current state for issue automation continuity. - Issue bridge audit trail (logs/github_issue_audit.jsonl): append-only operational trace for issue events.

These entities fall into three categories according to their source and lifecycle:

Entity classes: - Reference inputs: stable inputs used to run workflows. - Operational state: mutable files updated by runtime automation. - Audit evidence: append-only logs used for troubleshooting and traceability.

Registre, position et relevés

The distinction between transaction records and market snapshots determines how current holdings and their values are calculated.

Le registre des transactions détermine la position du titre. Référence métier : chapitre 4.

Objet Propriétaire et rôle
transaction_totals Résumé calculé pour un titre : net_shares, average_unit_cost, sell_average_price, net_cash_flow. Le coût moyen est celui de la position restante au registre; le flux est SELL moins BUY.
Titre.current_shares Colonne titres.current_shares NUMERIC(18,4) nullable, cache recalculé depuis le registre après mutation réussie. NULL signifie cache non initialisé ; zéro est un net nul. Ni ce cache ni les snapshots ne font autorité sur les actions détenues.
Historique Relevés de marché inchangés. _current_portfolio_totals utilise le dernier cours de chaque titre et une quantité strictement issue de l'agrégation SQL des transactions. valeur sert aux totaux natifs, cad_value persisté au consolidé CAD.

Le coût moyen est pondéré par le nombre d'actions. Dix achats à 20 $ et trente à 40 $ donnent 1 400 $ de coût pour 40 actions, soit 35 $ par action. Après la vente de dix actions, les trente actions au registre représentent 1 050 $ de coût (30 × 35 $), soit toujours 35 $ par action. Une vente complète laisse une position nulle; un nouvel achat établit son propre coût moyen. Le prix moyen des ventes est pondéré par le nombre d'actions vendues.

Le flux net décrit les paiements et encaissements du titre, indépendamment du coût moyen et de la valeur de marché. Les totaux CAD/USD utilisent la position du registre et les derniers cours disponibles; le consolidé utilise les équivalents CAD des relevés.

Les nouvelles opérations sont validées sur le registre complet pour empêcher une vente supérieure aux actions disponibles à sa date. Une opération réussie met à jour la projection de quantité et la transaction ensemble. Les relevés de marché ne servent jamais de solde d'ouverture.

Exemple : BUY 10 à 20 + BUY 30 à 40 donnent coût moyen 35 ; SELL 10 à 50 laisse quantité 30 et coût moyen 35 ; BUY 10 à 25 donne quantité 40 et coût moyen 32,50. Après liquidation, la moyenne gauche est NA. Même si un snapshot indique 40 actions, un registre 30 puis SELL 30 donne zéro et un registre 50 puis SELL 40 donne 10. À 120 CAD, les valeurs sont zéro et 1 200 CAD.

Les imports de cours et leurs UPSERT préservent current_shares ; les GET ne corrigent pas ce cache et ne reprennent pas la quantité snapshot. Le chargement initial reste idempotent. Les relevés conservent leurs quantités et prix passés. Le retrait des titres absents du CSV reste inchangé ; une vente ramenant le net à zéro ne crée aucune nouvelle règle de suppression. La démo calcule le même résumé depuis sa session, affiche le résultat une fois, puis revient au jeu initial au GET suivant ou après 30 minutes d'inactivité, sans écriture SQL sécurisée.