Aller au contenu

Proposition d'architecture des regles business CTRM

Statut: proposal Date: 2026-05-11 Scope: documentation metier purchase_trade / CTRM

Objectif

Cette note garde la proposition de structure documentaire pour les regles business trading. L'objectif est de pouvoir s'appuyer sur une source de verite exhaustive sans charger trop de contexte quand une demande concerne seulement un theme precis.

Etat des lieux

  • modules/AGENTS.md porte les regles courtes communes aux modules.
  • modules/purchase_trade/AGENTS.md porte les invariants critiques du module trading et les fichiers pivots.
  • modules/purchase_trade/docs/business-rules.md est la base metier la plus riche, mais elle melange regles canoniques, notes de session et quelques doublons de numerotation.
  • notes/business_rules.md sert de journal transverse de sessions.
  • notes/accounting/ documente plutot le standard comptable Tryton, les gaps de reporting et les extensions comptables purchase_trade.
  • Les fichiers specialises comme fees.md, padding-invoice-accounting.md, template-rules.md et template-properties.md sont de bons exemples de documentation ciblee.

Principe recommande

Garder purchase_trade comme source de verite canonique pour le metier CTRM, mais decouper les regles par theme.

AGENTS.md doit rester court et servir de routeur:

  • charger seulement les invariants toujours utiles;
  • indiquer quel fichier thematique lire selon la demande;
  • eviter d'embarquer toute la documentation business a chaque intervention.

Les notes de session doivent rester historiques. Une decision devient canonique seulement quand elle est promue dans un fichier thematique.

Structure cible proposee

modules/purchase_trade/docs/business/
  README.md
  INDEX.md
  glossary.md
  invariants.md
  sessions.md

  contracts.md
  lots-and-quantities.md
  matching.md
  shipments-execution.md
  pricing.md
  fees.md
  valuation-pnl-mtm.md
  invoicing.md
  accounting-bridge.md
  payments-banking.md
  reports-templates.md
  risk-credit-forex.md
  lots-management.md

Role des fichiers

  • README.md: explique la convention documentaire et le statut des fichiers.
  • INDEX.md: routeur par theme, avec les fichiers a lire selon le sujet.
  • glossary.md: vocabulaire stable du CTRM Tradon.
  • invariants.md: principes structurants toujours vrais.
  • sessions.md: journal historique non canonique.
  • fichiers thematiques: source canonique exhaustive pour chaque domaine.

Grands themes metier

  • contracts.md: achats, ventes, lignes, dates, lieux, banques, counterparties, quantite contractuelle, statut finished.
  • lots-and-quantities.md: lots virtuels/physiques, lot.qt, historique, weighing, split/merge, suppression de lot physique, solde ouvert.
  • matching.md: matching purchase/sale, open matching via lot.qt, wizard Create contracts, back-to-back, multi-lots.
  • shipments-execution.md: shipments, dropship/inbound, controller, SLA, locations, surveyor, weight reports, BL.
  • pricing.md: priced, basis, components, manual pricing, summary, linked currency, premium, settlement price.
  • fees.md: fees ligne/shipment, lots effectifs, % rate, ppack, maritime freight, insurance, declencheurs PnL.
  • valuation-pnl-mtm.md: valuation achat/vente, sale-first, references, MTM strategies, derivatives, exclusions fees.
  • invoicing.md: provisional/final, facture achat/vente, padding, quantites facturees, liens lot/facture, templates invoice.
  • accounting-bridge.md: effets sur account_invoice, account.move, taxes, devises, additional moves, validate/post.
  • payments-banking.md: payment terms, echeances, comptes bancaires party/company, payment order.
  • reports-templates.md: Relatorio, proprietes report_*, documents trade, regles XML, cache report.
  • risk-credit-forex.md: credit risk, forex, FX revaluation, exposition.
  • lots-management.md: rapports operationnels, filtres matching/side/shipping, dimension, strategy.

Format conseille pour une regle

### BR-PT-VAL-007 - Le MTM ne s'applique pas aux fees

Theme: valuation-pnl-mtm
Status: active
Scope: purchase_trade
Code: valuation.py, fee.py
Depends on: BR-PT-FEE-002

Summary: Les lignes de fee ne portent jamais mtm, mtm_price ou strategy.

Rule:
- MTM autorise seulement pour `pur. priced`, `sale priced`, `derivative`.
- Fees: `pur. fee`, `sale fee`, `shipment fee`, `line fee` restent hors MTM.

Tests:
- valuation fee sans mtm
- valuation priced avec mtm

Les identifiants devraient encoder le theme (LOT, MAT, PRI, FEE, VAL, INV, ACC, etc.) plutot qu'une numerotation globale unique. Cela evite les collisions quand les regles sont ajoutees au fil des sessions.

Routeur de contexte a ajouter plus tard dans AGENTS.md

Si la demande concerne:
- lots, quantites, matching: lire `docs/business/lots-and-quantities.md` et
  `docs/business/matching.md`
- pricing, premium, basis: lire `docs/business/pricing.md`
- fees, freight, insurance: lire `docs/business/fees.md`
- valuation, PnL, MTM: lire `docs/business/valuation-pnl-mtm.md`
- facture, padding, payment order: lire `docs/business/invoicing.md` et
  `docs/business/accounting-bridge.md`
- templates `.fodt`: lire `docs/business/reports-templates.md` et
  `docs/template-rules.md`

Migration proposee

  1. Creer docs/business/INDEX.md, invariants.md et glossary.md.
  2. Decouper docs/business-rules.md par theme, sans changer le fond.
  3. Deplacer les notes de session dans sessions.md.
  4. Promouvoir uniquement les decisions durables dans les fichiers thematiques.
  5. Reduire modules/purchase_trade/AGENTS.md a un memo court + routeur.
  6. Garder notes/accounting/ comme documentation comptable Tryton et comme vue specialisee des extensions comptables purchase_trade.

Risque actuel a traiter lors de la migration

Le risque principal n'est pas le manque de regles, mais leur dilution entre plusieurs fichiers. Certaines decisions existent a la fois dans AGENTS.md, notes/business_rules.md, business-rules.md, fees.md et les notes accounting. La migration devra designer une source canonique par theme et laisser les autres fichiers jouer leur role d'index, de journal ou de vue specialisee.