30.03.26

modules/purchase_trade/AGENTS.md

@@ -0,0 +1,90 @@
+# AGENTS.md - Module `purchase_trade`
+
+Ce guide complete le `AGENTS.md` racine.
+Pour ce module, les regles locales ci-dessous priment.
+
+## 1) Perimetre metier
+
+Le module `purchase_trade` etend les flux achat/vente Tryton avec une logique
+de negoce physique:
+
+- contrats d'achat (`purchase.purchase`, `purchase.line`)
+- contrats de vente (`sale.sale`, `sale.line`)
+- lots physiques et virtuels
+- matching achat/vente
+- shipments et execution logistique
+- frais (`fee.fee`)
+- templates de documents metier et facture
+
+## 2) Fichiers pivots
+
+- Contrats achat:
+  - `modules/purchase_trade/purchase.py`
+- Contrats vente:
+  - `modules/purchase_trade/sale.py`
+- Lots / matching / invoicing:
+  - `modules/purchase_trade/lot.py`
+- Shipments / lien facture-lot:
+  - `modules/purchase_trade/stock.py`
+- Fees:
+  - `modules/purchase_trade/fee.py`
+- Bridge facture / templates:
+  - `modules/purchase_trade/invoice.py`
+- Vues:
+  - `modules/purchase_trade/view/*.xml`
+- Actions module:
+  - `modules/purchase_trade/*.xml`
+- Manifest:
+  - `modules/purchase_trade/tryton.cfg`
+
+## 3) Documentation locale a lire en priorite
+
+- Regles metier:
+  - `modules/purchase_trade/docs/business-rules.md`
+- Regles templates:
+  - `modules/purchase_trade/docs/template-rules.md`
+- Catalogue des proprietes templates:
+  - `modules/purchase_trade/docs/template-properties.md`
+
+## 4) Invariants metier a preserver
+
+- Un lot `virtual` est la reference d'ouverture de quantite pour une `purchase.line`.
+- Le lot physique est le pont principal entre:
+  - `purchase.line`
+  - `sale.line`
+  - shipment
+  - facture
+- Pour remonter d'une facture vers shipment / BL / controller / fret:
+  - privilegier le lot physique
+  - ne pas multiplier des chemins d'acces concurrents
+- Le `FREIGHT VALUE` d'un template facture vient du `fee.fee` du shipment
+  dont le produit est `Maritime freight`.
+
+## 5) Conventions de modification
+
+1. Modifier la logique metier dans le fichier pivot le plus proche.
+2. Si un template `.fodt` devient complexe, deplacer la logique dans une
+   propriete Python `report_*`.
+3. Pour une facture trade, preferer enrichir `modules/purchase_trade/invoice.py`
+   plutot que surcharger lourdement le `.fodt`.
+4. Si une regle metier durable change, mettre a jour
+   `docs/business-rules.md`.
+5. Si une convention de template change, mettre a jour
+   `docs/template-rules.md`.
+
+## 6) Pieges connus
+
+- Plusieurs actions de report `account.invoice` peuvent sembler rendre le meme
+  document a cause du cache `invoice_report_cache`.
+- Les reports alternatifs (`Final Invoice`, `Prepayment`, etc.) ne doivent pas
+  reutiliser le cache du report standard sans verification.
+- Pour les donnees achat/vente partagees, ne pas supposer qu'une facture de
+  vente doit lire directement sur la `sale.line`: souvent, la verite metier
+  passe par le lot physique et/ou la `account.invoice.line`.
+
+## 7) Definition of done (module `purchase_trade`)
+
+- Le flux achat/vente/lot cible reste coherent.
+- Les impacts templates/facture ont ete verifies conceptuellement.
+- Les docs locales ont ete mises a jour si une nouvelle regle durable a emerge.
+- Le patch reste minimal et local au domaine demande.

modules/purchase_trade/docs/template-properties.md

@@ -0,0 +1,285 @@
+# Template Properties - Purchase Trade
+
+Statut: `draft`
+Version: `v0.1`
+Derniere mise a jour: `2026-03-27`
+
+## 1) Objectif
+
+- Lister les proprietes Python exposees pour alimenter les templates Relatorio.
+- Donner un point d'entree rapide aux createurs de templates.
+- Eviter de reparser tout `modules/purchase_trade/invoice.py`, `sale.py` ou `purchase.py`.
+
+## 2) Fichiers sources
+
+- Bridge facture:
+  - `modules/purchase_trade/invoice.py`
+- Proprietes de vente reutilisables:
+  - `modules/purchase_trade/sale.py`
+- Proprietes d'achat reutilisables:
+  - `modules/purchase_trade/purchase.py`
+
+## 3) Principes de lecture
+
+- Pour une facture:
+  - preferer les proprietes `report_*` exposees sur `account.invoice`
+  - pour une facture finale detaillee, utiliser aussi les proprietes `report_*`
+    exposees sur `account.invoice.line`
+- Pour une vente:
+  - reutiliser si possible les proprietes `report_*` deja presentes sur `sale.sale`
+- Pour un achat:
+  - reutiliser si possible les proprietes `report_*` deja presentes sur `purchase.purchase`
+
+## 4) Propriete disponibles sur `account.invoice`
+
+Source code: `modules/purchase_trade/invoice.py`
+
+### Identite du document / parties
+
+- `report_address`
+  - Usage: adresse d'affichage de la facture
+  - Source de verite: `sale.report_address` ou `purchase.report_address`, fallback `invoice.invoice_address.full_address`
+
+- `report_contract_number`
+  - Usage: numero de contrat
+  - Source de verite: `sale.full_number` ou `purchase.full_number`
+
+- `report_trader_initial`
+  - Usage: initiales trader dans les templates
+  - Source de verite: contrat lie
+
+- `report_operator_initial`
+  - Usage: initiales operator dans les templates
+  - Source de verite: contrat lie
+
+### Produit / contrat / quantites
+
+- `report_origin`
+  - Usage: origine produit
+  - Source de verite: `sale.product_origin` ou `purchase.product_origin`
+
+- `report_product_description`
+  - Usage: description produit principale
+  - Source de verite: premiere ligne metier liee a la facture
+
+- `report_description_upper`
+  - Usage: description de ligne en majuscules
+  - Source de verite: premiere `account.invoice.line`
+
+- `report_crop_name`
+  - Usage: campagne / crop
+  - Source de verite: contrat lie
+
+- `report_attributes_name`
+  - Usage: attributs produit
+  - Source de verite: premiere ligne metier liee a la facture
+
+- `report_price`
+  - Usage: prix en toutes lettres
+  - Source de verite: `sale.report_price` ou `purchase.report_price`
+
+- `report_nb_bale`
+  - Usage: nombre de balles
+  - Source de verite: `sale.report_nb_bale` ou recalcul sur les lots physiques
+
+- `report_gross`
+  - Usage: poids brut
+  - Source de verite: `sale.report_gross` ou recalcul sur les lots physiques
+
+- `report_net`
+  - Usage: poids net
+  - Source de verite: `sale.report_net` ou `purchase.report_net` ou recalcul sur les lots physiques
+
+- `report_lbs`
+  - Usage: poids net converti en LBS
+  - Source de verite: conversion de `report_net`
+
+### Bloc prix type `sale_ict`
+
+- `report_rate_currency_upper`
+  - Usage: devise du bloc `At ... PER ...`
+  - Source de verite: premiere `account.invoice.line` de type `line`
+
+- `report_rate_value`
+  - Usage: prix numerique du bloc `At ... PER ...`
+  - Source de verite: premiere `account.invoice.line` de type `line`
+
+- `report_rate_unit_upper`
+  - Usage: unite du bloc `At ... PER ...`
+  - Source de verite: premiere `account.invoice.line` de type `line`
+
+- `report_rate_price_words`
+  - Usage: prix en toutes lettres dans le bloc `At ... PER ...`
+  - Source de verite: premiere `account.invoice.line` de type `line`, fallback `report_price`
+
+- `report_rate_pricing_text`
+  - Usage: texte de pricing additionnel
+  - Source de verite: premiere `account.invoice.line` de type `line`
+
+### Logistique / shipment
+
+- `report_shipment`
+  - Usage: resume vessel / BL / shipment
+  - Source de verite: contrat lie
+
+- `report_bl_date`
+  - Usage: date de BL
+  - Source de verite: shipment du lot physique
+
+- `report_bl_nb`
+  - Usage: numero de BL
+  - Source de verite: shipment du lot physique
+
+- `report_vessel`
+  - Usage: nom du vessel
+  - Source de verite: shipment du lot physique
+
+- `report_loading_port`
+  - Usage: port of loading
+  - Source de verite: shipment du lot physique
+
+- `report_discharge_port`
+  - Usage: port of discharge
+  - Source de verite: shipment du lot physique
+
+- `report_controller_name`
+  - Usage: nom du controller
+  - Source de verite: shipment du lot physique
+
+- `report_si_number`
+  - Usage: S/I number
+  - Source de verite: shipment du lot physique
+
+### Conditions commerciales
+
+- `report_incoterm`
+  - Usage: incoterm + location
+  - Source de verite: contrat lie
+
+- `report_payment_date`
+  - Usage: date de paiement
+  - Source de verite: contrat lie
+
+- `report_payment_description`
+  - Usage: description des conditions de paiement
+  - Source de verite: payment term du contrat ou de la facture
+
+### Pro forma / freight
+
+- `report_proforma_invoice_number`
+  - Usage: numero de facture provisoire
+  - Source de verite: lot physique via `invoice_line_prov` ou `sale_invoice_line_prov`
+
+- `report_proforma_invoice_date`
+  - Usage: date de facture provisoire
+  - Source de verite: lot physique via `invoice_line_prov` ou `sale_invoice_line_prov`
+
+- `report_freight_amount`
+  - Usage: `FREIGHT VALUE`
+  - Source de verite:
+    - lot physique
+    - shipment du lot
+    - `fee.fee` avec `product.name = 'Maritime freight'`
+    - montant = `fee.get_amount()`
+
+- `report_freight_currency_symbol`
+  - Usage: devise du `FREIGHT VALUE`
+  - Source de verite: devise du fee `Maritime freight`, fallback devise facture
+
+## 5) Proprietes disponibles sur `account.invoice.line`
+
+Source code: `modules/purchase_trade/invoice.py`
+
+- `report_product_description`
+  - Usage: description produit de la ligne
+  - Source de verite: `invoice_line.product` ou `origin.product`
+
+- `report_description_upper`
+  - Usage: description de ligne en uppercase
+  - Source de verite: `invoice_line.description`
+
+- `report_crop_name`
+  - Usage: crop de la ligne
+  - Source de verite: contrat relie via `origin`
+
+- `report_attributes_name`
+  - Usage: attributs de la ligne
+  - Source de verite: `origin.attributes_name`
+
+- `report_net`
+  - Usage: quantite nette de la ligne
+  - Source de verite: `invoice_line.quantity`
+
+- `report_lbs`
+  - Usage: quantite convertie en LBS
+  - Source de verite: conversion de `report_net`
+
+- `report_rate_currency_upper`
+  - Usage: devise de prix de la ligne
+  - Source de verite: `origin.linked_currency` ou `invoice_line.currency`
+
+- `report_rate_value`
+  - Usage: prix numerique de la ligne
+  - Source de verite: `invoice_line.unit_price`
+
+- `report_rate_unit_upper`
+  - Usage: unite de prix de la ligne
+  - Source de verite: `origin.linked_unit` ou `invoice_line.unit`
+
+- `report_rate_price_words`
+  - Usage: prix en toutes lettres de la ligne
+  - Source de verite: contrat relie via `trade.report_price`
+
+- `report_rate_pricing_text`
+  - Usage: texte de pricing de la ligne
+  - Source de verite: `origin.get_pricing_text`
+
+## 6) Proprietes utiles deja presentes sur `sale.sale`
+
+Source code: `modules/purchase_trade/sale.py`
+
+- `report_terms`
+- `report_gross`
+- `report_net`
+- `report_qt`
+- `report_nb_bale`
+- `report_deal`
+- `report_packing`
+- `report_price`
+- `report_delivery`
+- `report_payment_date`
+- `report_shipment`
+
+Usage typique:
+- base de travail pour les templates de type `sale_ict.fodt`
+- source de verite de plusieurs proprietes du bridge facture
+
+## 7) Proprietes utiles deja presentes sur `purchase.purchase`
+
+Source code: `modules/purchase_trade/purchase.py`
+
+- `report_terms`
+- `report_qt`
+- `report_price`
+- `report_delivery`
+- `report_payment_date`
+- `report_shipment`
+
+Usage typique:
+- templates et bridges pour facturation fournisseur
+- fallback achat quand une facture n'est pas liee a une vente
+
+## 8) Templates connus qui utilisent ces proprietes
+
+- `modules/account_invoice/invoice_ict.fodt`
+- `modules/account_invoice/invoice_ict_final.fodt`
+- `modules/sale/sale_ict.fodt`
+
+## 9) Recommandations
+
+- Avant d'ajouter une nouvelle expression dans un `.fodt`, verifier si une
+  propriete `report_*` existe deja ici.
+- Si une nouvelle propriete est ajoutee pour un template, la documenter dans ce
+  fichier.
+- Pour les donnees logistiques facture, privilegier toujours:
+  - facture -> ligne metier -> lot physique -> shipment / fee

modules/purchase_trade/docs/template-rules.md

@@ -16,6 +16,12 @@ Derniere mise a jour: `2026-03-27`
 
 - Eviter les erreurs de parsing Relatorio/Genshi lors de la generation des documents.
 - Standardiser la maniere d'alimenter les templates metier a partir du code Python.
+- Centraliser les proprietes `report_*` dans une documentation reutilisable.
+
+## 2.1) Index de reference
+
+- Catalogue des proprietes templates:
+  - `modules/purchase_trade/docs/template-properties.md`
 
 ## 3) Regles pratiques
 

modules/purchase_trade/view/lot_report_list.xml

@@ -1,4 +1,4 @@
-<tree editable="1">
+<tree>
     <field name="r_lot_type" width="80">
         <prefix name="qt_icon"/>
     </field>