# 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`.
- Une `sale.line` doit aussi avoir au minimum un lot `virtual`; une valuation
  cote sale ne doit donc pas disparaitre juste parce que le lot est `open`.
- 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
- Pour les champs de colis (`NB BALES`) dans les templates facture:
  - la source de verite est `line.lot.lot_qt`
  - sur une facture, sommer les `lot_qt` des lignes de facture
  - tenir compte du signe de la ligne de facture pour les notes finales
  - ne pas proratiser depuis le poids (`net` / `gross`)
- Le `FREIGHT VALUE` d'un template facture vient du `fee.fee` du shipment
  dont le produit est `Maritime freight`.
- Pour `stock/insurance.fodt`, le `Amount insured` doit venir en priorite de
  `110%` du total des `incoming_moves` (fallback fee `Insurance` si aucun
  montant incoming calculable).
- Pour le surveyor du certificat d'assurance shipment, la priorite est:
  `shipment.surveyor` -> `shipment.controller` -> fournisseur du fee
  `Insurance`.
- Pour `payment_order.fodt`, utiliser des proprietes
  `invoice.report_payment_order_*` plutot que des tokens legacy `<...>`.
- Ajouter un champ de template dans `Document Templates` ne rend pas le report
  visible dans la fiche: il faut aussi l'action `ir.action.report` +
  `ir.action.keyword` (`form_print`) cote `account.invoice`.
- Le wizard `Create contracts` en mode `matched` peut maintenant partir de
  plusieurs `lot.qt`, mais doit conserver un matching par lot source et laisser
  `created_by_code = True` sur les lignes creees pour ne pas declencher les
  creations automatiques de lots dans les validations.
- En valuation / PnL:
  - la valeur stockee dans `type` est la cle technique (`pur. priced`,
    `sale priced`, `pur. fee`, etc.), pas le label affiche dans l'UI
  - les references doivent rester coherentes avec le type de lot:
    `Purchase/Open`, `Purchase/Physic`, `Sale/Open`, `Sale/Physic`
  - pour une sale matchee, les lignes de valuation purchase generees sur un lot
    physique doivent aussi renseigner `sale` et `sale_line` afin de remonter
    dans l'onglet PnL de la sale
  - une sale non matchee doit etre valorisable "sale-first" et alimenter
    `valuation.valuation` / `valuation.valuation.line`
  - si une `sale.line` `basis` n'a ni `price_summary` ni `lot_price_sale`,
    creer quand meme une ligne `sale priced` avec `price = 0` et `amount = 0`
    plutot que de ne rien generer
  - le MTM ne doit etre renseigne que pour `pur. priced`, `sale priced` et
    `derivative`; jamais pour les fees
  - `mtm_price` doit afficher le prix brut de valorisation (sans ratio), alors
    que `mtm` reste le montant calcule selon la logique de strategie
- En pricing:
  - le `unit_price` doit rester un prix de base, hors `premium`
  - le `premium` doit impacter le prix total economique et donc le `amount`,
    aussi bien en `priced` qu'en `basis`
  - dans `pricing.pricing` en saisie manuelle, l'utilisateur renseigne
    seulement `quantity` et `settl_price`
  - `fixed_qt`, `fixed_qt_price`, `unfixed_qt`, `unfixed_qt_price` et
    `eod_price` sont des valeurs derivees et ne doivent pas etre saisies a la
    main
  - en manuel, `fixed_qt` = cumul des `quantity` du groupe trie par
    `pricing_date`
  - en manuel, `fixed_qt_price` = moyenne ponderee cumulee des `settl_price`
  - en manuel, `unfixed_qt_price` = `settl_price` de la ligne
  - pour les documents commerciaux / facture, une ligne `basis` affiche le
    `premium` comme prix visible, pas le prix economique total
  - si `linked currency` est active, le `premium` est saisi dans la devise /
    unite liee (ex: `USC/LB`) puis converti vers le repere de la ligne pour le
    calcul du `amount`
  - en `basis + linked currency`, le `linked_price` doit representer le prix
    basis brut (hors premium) dans la devise liee; le `unit_price` reste ce
    prix brut converti, et le `premium` converti est ajoute seulement dans
    l'`amount`
  - si `linked currency` est cochee, `linked_price`, `linked_currency` et
    `linked_unit` sont requis
  - dans les forms, presenter le bloc prix dans l'ordre:
    `price_type` -> linked fields -> `premium` -> `unit_price` -> `amount`
  - en valuation `basis`, le premium s'applique a chaque composant, pas
    uniquement a une ligne de resume
  - pour une ligne `basis` sans `price_summary`, la valuation fallback doit
    utiliser `unit_price + premium` (et pas `unit_price` seul)
  - a la validation d'une `sale.line`, si un lot virtuel est cree et qu'aucun
    matching purchase n'existe, il faut lancer `generate_from_sale_line()` pour
    alimenter le PnL sale-first

## 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"`.
7. Si une regle de texte par defaut durable est demandee sur achat/vente,
   preferer un singleton de configuration expose dans un menu fonctionnel
   existant plutot qu'un menu technique `purchase_trade`.

## 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`.
- Les templates `invoice_ict*` peuvent partager les memes proprietes Python;
  si une regle doit valoir pour provisional et final, la mettre dans
  `modules/purchase_trade/invoice.py` plutot que dupliquer dans les `.fodt`.
- Dans les ecrans PnL, le label `Sale price` correspond au type stocke
  `sale priced`; idem pour `Pur. price` / `pur. priced`.
- Une ligne `basis` sans resume de pricing peut sinon disparaitre de la
  valuation si aucun fallback explicite a `0` n'est prevu.
- Le calcul du prix peut diverger entre `unit_price`, `linked_price`,
  `lot_price` et valuation si le premium n'est pas traite explicitement dans
  chaque maillon.
- Sur `account.invoice`, le workflow `Validate` doit maintenant aligner
  fournisseur et client pour:
  - creation du `account.move`
  - attribution du `number`
  - `Post` ne doit pas reintroduire une difference de session/fresh login cote
    client

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