Bug pnl fee

2026-05-14 14:31:23 +02:00
parent 82a30f246d
commit 20a4e20e91
8 changed files with 603 additions and 36 deletions
--- a/modules/purchase_trade/docs_source/business/INDEX.md
+++ b/modules/purchase_trade/docs_source/business/INDEX.md
@@ -10,7 +10,7 @@ Statut: `migration partielle`
 - Shipments, controllers, SLA, weight reports: [shipments-execution.md](shipments-execution.md)
 - Pricing manuel, basis, premium, linked currency: [pricing.md](pricing.md)
 - Fees, freight, lots effectifs, `% rate`: [fees.md](fees.md)
- Valuation, PnL, MTM, derivatives: [valuation-pnl-mtm.md](valuation-pnl-mtm.md)
+- Valuation, PnL, MTM, derivatives: [FR](valuation-pnl-mtm.md) / [EN](valuation-pnl-mtm.en.md)
 - Factures provisoires/finales, padding: [invoicing.md](invoicing.md)
 - Impacts `account.move`, validate/post: [accounting-bridge.md](accounting-bridge.md)
 - Comptes bancaires, payment terms, payment orders: [payments-banking.md](payments-banking.md)
@@ -41,6 +41,7 @@ Statut: `migration partielle`
 - `BR-PT-VAL-001`: valuation achat/vente et sale-first.
 - `BR-PT-VAL-002`: references de valuation.
 - `BR-PT-VAL-003`: MTM hors fees.
+- `BR-PT-VAL-004`: snapshot courant PnL et identite economique.
 - `BR-PT-INV-001`: padding facture provisoire vente.
 - `BR-PT-ACC-001`: Validate facture client attribue le numero.
 - `BR-PT-PAY-001`: comptes bancaires tiers vs compagnie.
--- a/modules/purchase_trade/docs_source/business/valuation-pnl-mtm.en.md
+++ b/modules/purchase_trade/docs_source/business/valuation-pnl-mtm.en.md
@@ -0,0 +1,95 @@
+# Valuation, PnL, MTM
+
+Status: `partial migration`
+
+Language: `en`<br>
+Mirror page: [valuation-pnl-mtm.md](valuation-pnl-mtm.md)
+
+## BR-PT-VAL-001 - Valuation covers purchase, sale, and sale-first flows
+
+Source: `BR-PT-004`, `BR-PT-006`, `BR-PT-011`
+
+### Consultant Rule
+
+PnL must exist for purchases and for sales, even when a sale is not yet matched
+to a purchase.
+
+### Developer Notes
+
+- An unmatched `sale.line` must generate at least `sale priced`, `sale fee`,
+  and `derivative` when applicable.
+- A basis sale with no price detail must still produce a zero line or the
+  economic fallback price according to the applicable rule.
+- Do not arbitrarily attach a single sale when several sales are matched to the
+  same open balance.
+
+## BR-PT-VAL-002 - Valuation references
+
+Source: `BR-PT-005`
+
+### Consultant Rule
+
+The PnL reference must describe the nature of the valued line: purchase or sale,
+open or physical.
+
+### Developer Notes
+
+- Allowed references: `Purchase/Open`, `Purchase/Physic`, `Sale/Open`,
+  `Sale/Physic`.
+- A virtual lot must not be output with a physical reference.
+
+## BR-PT-VAL-003 - MTM excludes fees
+
+Source: `BR-PT-007`
+
+### Consultant Rule
+
+Mark-to-market applies to prices and derivatives, not to fees.
+
+### Developer Notes
+
+- MTM is allowed for `pur. priced`, `sale priced`, `derivative`.
+- Fees are outside MTM: `pur. fee`, `sale fee`, `shipment fee`, `line fee`.
+- For fees: `mtm_price`, `mtm`, `strategy` must stay empty.
+
+## BR-PT-VAL-004 - Current snapshot and economic identity
+
+Source: session `2026-05-14`
+
+### Consultant Rule
+
+`valuation_valuation_line` represents the latest known PnL image.
+It is not a history table.
+
+- A new generation replaces the previous generation for the same economic
+  reality.
+- An unmatched sale owns its own PnL.
+- A matched sale is owned by the linked purchase line.
+- The PnL of a matched sale must not be generated twice: once from the sale
+  side and once from the purchase side.
+
+### Developer Notes
+
+- Before creating rows in `valuation.valuation.line`, delete the current
+  snapshot with the same economic identity.
+- Economic identity:
+  - `sale_line` when present, otherwise `line`;
+  - `lot`;
+  - `type`;
+  - `reference`;
+  - `counterparty`;
+  - `product`;
+  - `state`;
+  - `strategy`.
+- Do not include in the identity:
+  - `date`;
+  - `price`;
+  - `quantity`;
+  - `amount`;
+  - `mtm_price`;
+  - `mtm`.
+- These fields are recalculated results and must be replaced by the latest
+  generation.
+- `generate_from_sale_line()` does not create a sale snapshot when the
+  `sale.line` is already matched to a `purchase.line`; it redirects to the
+  owner purchase line generation.
--- a/modules/purchase_trade/docs_source/business/valuation-pnl-mtm.md
+++ b/modules/purchase_trade/docs_source/business/valuation-pnl-mtm.md
@@ -2,36 +2,39 @@

 Statut: `migration partielle`

+Langue: `fr`<br>
+Page miroir: [valuation-pnl-mtm.en.md](valuation-pnl-mtm.en.md)
+
 ## BR-PT-VAL-001 - La valuation couvre achat, vente et sale-first

 Source: `BR-PT-004`, `BR-PT-006`, `BR-PT-011`

-### Regle consultant
+### Règle consultant

-Le PnL doit exister pour les achats et pour les ventes, meme quand une vente
-n'est pas encore matchee a un achat.
+Le PnL doit exister pour les achats et pour les ventes, même quand une vente
+n'est pas encore matchée à un achat.

-### Notes developpeur
+### Notes développeur

- Une `sale.line` non matchee doit generer au minimum `sale priced`, `sale fee`
+- Une `sale.line` non matchée doit générer au minimum `sale priced`, `sale fee`
  et `derivative` si applicable.
- Une sale basis sans detail de prix doit quand meme produire une ligne a zero
-  ou au prix economique fallback selon la regle applicable.
+- Une sale basis sans détail de prix doit quand même produire une ligne à zéro
+  ou au prix économique fallback selon la règle applicable.
 - Ne pas attacher arbitrairement une sale unique si plusieurs sales sont
-  matchees au meme ouvert.
+  matchées au même ouvert.

-## BR-PT-VAL-002 - References de valuation
+## BR-PT-VAL-002 - Références de valuation

 Source: `BR-PT-005`

-### Regle consultant
+### Règle consultant

-La reference de PnL doit decrire la nature de la ligne valorisee: achat ou
+La référence de PnL doit décrire la nature de la ligne valorisée: achat ou
 vente, ouverte ou physique.

-### Notes developpeur
+### Notes développeur

- References autorisees: `Purchase/Open`, `Purchase/Physic`, `Sale/Open`,
+- Références autorisées: `Purchase/Open`, `Purchase/Physic`, `Sale/Open`,
  `Sale/Physic`.
 - Un lot virtuel ne doit pas sortir avec une reference physique.

@@ -39,13 +42,54 @@ vente, ouverte ou physique.

 Source: `BR-PT-007`

-### Regle consultant
+### Règle consultant

-Le mark-to-market s'applique aux prix et aux derives, pas aux frais.
+Le mark-to-market s'applique aux prix et aux dérivés, pas aux frais.

-### Notes developpeur
+### Notes développeur

- MTM autorise pour `pur. priced`, `sale priced`, `derivative`.
+- MTM autorisé pour `pur. priced`, `sale priced`, `derivative`.
 - Fees hors MTM: `pur. fee`, `sale fee`, `shipment fee`, `line fee`.
 - Pour les fees: `mtm_price`, `mtm`, `strategy` doivent rester vides.

+## BR-PT-VAL-004 - Snapshot courant et identité économique
+
+Source: session `2026-05-14`
+
+### Règle consultant
+
+`valuation_valuation_line` représente la dernière image connue du PnL.
+Elle n'est pas un historique.
+
+- Une nouvelle génération remplace la génération précédente pour la même
+  réalité économique.
+- Une vente non matchée porte son propre PnL.
+- Une vente matchée est portée par la ligne d'achat liée.
+- Le PnL d'une vente matchée ne doit pas être généré deux fois: une fois côté
+  vente et une fois côté achat.
+
+### Notes développeur
+
+- Avant création dans `valuation.valuation.line`, supprimer le snapshot courant
+  ayant la même identité économique.
+- Identité économique:
+  - `sale_line` si elle existe, sinon `line`;
+  - `lot`;
+  - `type`;
+  - `reference`;
+  - `counterparty`;
+  - `product`;
+  - `state`;
+  - `strategy`.
+- Ne pas inclure dans l'identité:
+  - `date`;
+  - `price`;
+  - `quantity`;
+  - `amount`;
+  - `mtm_price`;
+  - `mtm`.
+- Ces champs sont des résultats recalculés et doivent être remplacés par la
+  dernière génération.
+- `generate_from_sale_line()` ne crée pas de snapshot vente si la `sale.line`
+  est déjà matchée à une `purchase.line`; il redirige vers la génération de la
+  ligne d'achat propriétaire.