01.04.26

modules/purchase_trade/docs/business-rules.md

@@ -1,8 +1,8 @@
 # Business Rules - Purchase Trade
 
 Statut: `draft`
-Version: `v0.2`
-Derniere mise a jour: `2026-03-27`
+Version: `v0.3`
+Derniere mise a jour: `2026-04-01`
 Owner metier: `a completer`
 Owner technique: `a completer`
 
@@ -100,6 +100,153 @@ Owner technique: `a completer`
 - Priorite:
   - `importante`
 
+### BR-PT-004 - La valuation doit couvrir les flux purchase et sale, y compris les sales non matchees
+
+- Intent: obtenir un PnL coherent cote achat et cote vente, meme lorsqu'une
+  sale n'est pas encore matchee a une purchase.
+- Description:
+  - Le flux historique de valuation part de `purchase.line` puis remonte vers
+    les ventes via les lots/lots matchants.
+  - Le systeme doit egalement savoir valoriser directement une `sale.line`
+    non matchee ("sale-first").
+  - Une sale non matchee doit creer des lignes dans
+    `valuation.valuation` et `valuation.valuation.line` afin d'apparaitre dans
+    l'onglet PnL de la sale.
+- Resultat attendu:
+  - pour une `sale.line` non matchee, generer au minimum les types:
+    - `sale priced`
+    - `sale fee`
+    - `derivative` si la ligne porte des derives
+  - si la sale est matchee via un lot physique, les lignes purchase portees par
+    ce lot physique doivent aussi renseigner `sale` et `sale_line`
+  - une sale matchee doit donc voir:
+    - ses lignes `sale *`
+    - les lignes purchase portees par le lot physique partage
+- Priorite:
+  - `structurante`
+
+### BR-PT-005 - Les references de valuation doivent decrire la nature du lot de la ligne
+
+- Intent: eviter les ambiguïtes dans les ecrans PnL entre lots `open` et lots
+  `physic`.
+- Description:
+  - La reference affichee dans la valuation doit decrire la ligne elle-meme,
+    pas son vis-a-vis.
+  - Les references autorisees pour les lignes de prix sont:
+    - `Purchase/Open`
+    - `Purchase/Physic`
+    - `Sale/Open`
+    - `Sale/Physic`
+- Resultat attendu:
+  - un lot `virtual` cote purchase ne doit jamais sortir avec la reference
+    `Purchase/Physic`
+  - un lot `virtual` cote sale ne doit jamais sortir avec la reference
+    `Sale/Physic`
+  - un lot physique matche peut produire:
+    - une ligne purchase en `Purchase/Physic`
+    - une ligne sale en `Sale/Physic`
+  - un open sale matche a un open purchase peut produire des quantites egales
+    tout en gardant des references differentes (`Purchase/Open` vs `Sale/Open`)
+- Priorite:
+  - `importante`
+
+### BR-PT-006 - Une sale basis sans prix detaille doit quand meme apparaitre en valuation
+
+- Intent: ne pas perdre les lignes de PnL lorsque le detail de pricing n'est
+  pas encore renseigne.
+- Description:
+  - Une `sale.line` de type `basis` peut exister avec un lot `virtual`, sans
+    `price_summary` et sans `lot_price_sale`.
+  - Dans ce cas, la valuation doit quand meme creer une ligne `sale priced`.
+- Resultat attendu:
+  - si `price_summary` est vide:
+    - creer une ligne `sale priced`
+    - avec `price = 0`
+    - avec `amount = 0`
+    - avec un `state` de type `unfixed`
+  - si `lot_price_sale` est vide sur un lot sale, utiliser `sale_line.unit_price`
+    comme fallback quand il existe
+- Priorite:
+  - `importante`
+
+### BR-PT-007 - Le MTM de valuation ne s'applique pas aux fees
+
+- Intent: distinguer les lignes de prix marquables au marche des lignes de
+  frais qui ne doivent pas etre mark-to-market.
+- Description:
+  - Le systeme peut renseigner `mtm_price`, `mtm` et `strategy` uniquement pour:
+    - `pur. priced`
+    - `sale priced`
+    - `derivative`
+  - Les fees (`pur. fee`, `sale fee`, `shipment fee`, `line fee`) ne doivent
+    jamais porter de valorisation MTM.
+- Resultat attendu:
+  - les lignes de fee doivent conserver:
+    - `mtm_price = NULL`
+    - `mtm = NULL`
+    - `strategy = NULL`
+  - `mtm_price` doit representer le prix brut de valorisation sans appliquer le
+    ratio de composant
+  - `mtm` reste le montant calcule selon la logique de strategie
+- Priorite:
+  - `structurante`
+
+### BR-PT-008 - Le premium fait partie du prix contractuel en `priced` et en `basis`
+
+- Intent: garantir que le montant total valorise et facture reflete toujours le
+  premium/discount saisi sur la ligne.
+- Description:
+  - Le `premium` d'une `purchase.line` ou `sale.line` doit impacter le prix
+    total quelle que soit la `price_type`.
+  - Cette regle vaut pour:
+    - le `unit_price`
+    - les calculs de `amount`
+    - la valuation / PnL
+- Resultat attendu:
+  - en `priced`, le prix total = prix de base + premium
+  - en `basis`, le premium s'ajoute aussi au prix total
+  - en valuation `basis`, le premium s'applique a chaque composant valorise
+    (ex: meme premium repete sur chaque bloc ICE)
+- Exemple metier:
+  - `8.30 USC/LB 500 TONS ON ICE MCH'26`
+  - `8.30 USC/LB 500 TONS ON ICE MAY 26`
+  - le premium `8.30 USC/LB` s'applique a chaque composant
+- Priorite:
+  - `structurante`
+
+### BR-PT-009 - En linked currency, le premium est exprime dans la devise/unite liee
+
+- Intent: respecter la facon dont les traders saisissent les prix sur certains
+  produits (ex: coton en `USC/LB`).
+- Description:
+  - Quand `enable_linked_currency` est coche, le `premium` est saisi dans la
+    devise / unite liee, pas dans la devise / unite native de la ligne.
+  - Le systeme doit convertir ce premium vers le `unit_price` de la ligne pour
+    les calculs internes.
+- Resultat attendu:
+  - `premium` est interprete dans le repere `linked_currency` / `linked_unit`
+  - le `unit_price` converti integre ce premium
+  - les `amount` et valuations bases sur `unit_price` reflectent donc ce
+    premium converti
+- Priorite:
+  - `structurante`
+
+### BR-PT-010 - En `basis + linked currency`, le linked price suit le basis brut
+
+- Intent: rendre lisible la decomposition entre prix basis de marche et premium.
+- Description:
+  - Quand une ligne est en `basis` et `linked currency`, le bloc
+    `linked_price` doit etre recalcule automatiquement.
+  - Ce `linked_price` doit representer le prix basis brut, hors premium.
+  - Le `unit_price` final de la ligne est ensuite obtenu en ajoutant le premium
+    converti.
+- Resultat attendu:
+  - modification du basis -> mise a jour automatique du `linked_price`
+  - `linked_price` = base market / basis
+  - `unit_price` = `linked_price` converti + premium converti
+- Priorite:
+  - `importante`
+
 ## 4) Exemples concrets
 
 ### Exemple E1 - Augmentation simple
@@ -146,6 +293,8 @@ Owner technique: `a completer`
 - Fichiers Python concernes:
   - `modules/purchase_trade/purchase.py`
   - `modules/purchase_trade/lot.py`
+  - `modules/purchase_trade/valuation.py`
+  - `modules/purchase_trade/sale.py`
 
 ## 6) Strategie de tests
 
@@ -155,3 +304,11 @@ Pour cette regle, couvrir au minimum:
 - augmentation sans `lot.qt` ouvert
 - diminution possible
 - diminution impossible avec erreur
+- valuation purchase/sale sur lot physique matche
+- valuation sale-first sur sale non matchee avec lot virtual
+- valuation sale `basis` sans `price_summary`
+- absence de MTM sur les fees
+- premium en `priced`
+- premium en `basis`
+- premium en `linked currency`
+- synchro `basis` -> `linked_price` -> `unit_price`

modules/purchase_trade/docs/template-rules.md

@@ -126,6 +126,18 @@ Derniere mise a jour: `2026-03-27`
   - utiliser `fee.get_amount()`
 - Si le fee a sa propre devise, preferer aussi exposer le symbole de devise depuis le fee plutot que depuis la facture.
 
+### TR-009 - Ne pas dereferencer directement `del_period.description` dans les templates
+
+- Eviter les expressions du type:
+  - `sale.lines[0].del_period.description`
+  - `purchase.lines[0].del_period.description`
+- Meme avec un `if ... else`, ces acces sont fragiles dans un `.fodt` et
+  rendent le debug plus difficile.
+- Preferer une propriete Python stable:
+  - `sale.report_delivery_period_description`
+  - `purchase.report_delivery_period_description`
+  - `invoice.report_delivery_period_description`
+
 ## 4) Workflow recommande pour corriger un template en erreur
 
 1. Identifier le placeholder exact qui provoque l'erreur Relatorio.