# 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. Pour les vues XML Tryton de ce module, utiliser `editable="1"` sur les
   `<tree>` editables; ne pas utiliser `editable="bottom"`.

## 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.