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.