diff --git a/modules/purchase_trade/AGENTS.md b/modules/purchase_trade/AGENTS.md new file mode 100644 index 0000000..e82b9c7 --- /dev/null +++ b/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. diff --git a/modules/purchase_trade/docs/template-properties.md b/modules/purchase_trade/docs/template-properties.md new file mode 100644 index 0000000..ea020d6 --- /dev/null +++ b/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 diff --git a/modules/purchase_trade/docs/template-rules.md b/modules/purchase_trade/docs/template-rules.md index 7fbd8f4..947a35b 100644 --- a/modules/purchase_trade/docs/template-rules.md +++ b/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 diff --git a/modules/purchase_trade/view/lot_report_list.xml b/modules/purchase_trade/view/lot_report_list.xml index 8722d2a..1fea232 100755 --- a/modules/purchase_trade/view/lot_report_list.xml +++ b/modules/purchase_trade/view/lot_report_list.xml @@ -1,4 +1,4 @@ - +