26.03.26

modules/purchase_trade/docs/template-rules.md

@@ -0,0 +1,109 @@
+# Template Rules - Purchase Trade
+
+Statut: `draft`
+Version: `v0.1`
+Derniere mise a jour: `2026-03-26`
+
+## 1) Scope
+
+- Domaine: `templates Relatorio .fodt`
+- Modules concernes:
+  - `purchase_trade`
+  - `sale`
+  - `account_invoice`
+
+## 2) Objectif
+
+- 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.
+
+## 3) Regles pratiques
+
+### TR-001 - Toujours partir du template standard voisin
+
+- Avant de modifier un template metier (`invoice_ict.fodt`, `sale_ict.fodt`, etc.), comparer avec le template standard du module source:
+  - `modules/account_invoice/invoice.fodt`
+  - `modules/sale/sale.fodt`
+- Reprendre en priorite la syntaxe Relatorio deja validee dans ces templates.
+
+### TR-002 - Eviter les expressions Genshi trop complexes dans le `.fodt`
+
+- Preferer des proprietes Python simples exposees par le modele.
+- Le template doit consommer au maximum des champs ou proprietes du type:
+  - `record.report_address`
+  - `record.report_price`
+  - `record.report_payment_date`
+- Si un template a besoin de donnees issues d'un autre modele lie, creer un petit pont Python.
+
+### TR-003 - Regles de syntaxe XML/Relatorio dans les placeholders
+
+- Dans un `text:placeholder`, utiliser:
+  - `"..."` pour les guillemets doubles
+  - `'...'` pour les apostrophes
+- Eviter les formes avec antislashs:
+  - interdit: `\'\'`
+  - interdit: `\'value\'`
+- Exemples corrects:
+  - `<replace text:p="set_lang(invoice.party.lang)">`
+  - `<if test="invoice.report_payment_description">`
+  - `<tax.description or ''>`
+
+### TR-004 - Pour une facture issue d'une vente, preferer un pont `account.invoice -> sale`
+
+- Si le template facture doit reutiliser la logique de la pro forma vente, ne pas dupliquer les calculs directement dans le `.fodt`.
+- Ajouter plutot dans `purchase_trade` une extension `account.invoice` avec des proprietes `report_*` qui relaient vers `invoice.sales[0]`.
+- Exemple de proprietes utiles:
+  - `report_address`
+  - `report_contract_number`
+  - `report_shipment`
+  - `report_product_description`
+  - `report_crop_name`
+  - `report_attributes_name`
+  - `report_price`
+  - `report_payment_date`
+  - `report_nb_bale`
+  - `report_gross`
+  - `report_net`
+  - `report_lbs`
+
+### TR-005 - Reutiliser les proprietes existantes du module `purchase_trade.sale`
+
+- Avant d'ajouter une nouvelle logique pour un template vente ou facture issue d'une vente, verifier si une propriete existe deja sur `sale.sale`.
+- Proprietes deja utiles:
+  - `report_terms`
+  - `report_gross`
+  - `report_net`
+  - `report_qt`
+  - `report_nb_bale`
+  - `report_deal`
+  - `report_packing`
+  - `report_price`
+  - `report_delivery`
+  - `report_payment_date`
+  - `report_shipment`
+
+## 4) Workflow recommande pour corriger un template en erreur
+
+1. Identifier le placeholder exact qui provoque l'erreur Relatorio.
+2. Comparer sa syntaxe avec le template standard equivalent.
+3. Remplacer les guillemets/quotes non valides par `"` / `'`.
+4. Si l'expression devient trop longue, la deplacer dans une propriete Python `report_*`.
+5. Ne modifier que les placeholders necessaires.
+6. Regenerer le document pour verifier la prochaine erreur eventuelle.
+
+## 5) Cas documentes dans ce repo
+
+### Invoice ICT
+
+- Fichier: `modules/account_invoice/invoice_ict.fodt`
+- Strategie retenue:
+  - aligner la syntaxe sur `modules/account_invoice/invoice.fodt`
+  - reutiliser au maximum les proprietes de `sale.sale`
+  - exposer dans `modules/purchase_trade/invoice.py` des proprietes de pont `account.invoice -> sale`
+
+### Sale ICT
+
+- Fichier: `modules/sale/sale_ict.fodt`
+- Usage:
+  - reference principale pour les champs metier proches d'une pro forma / facture commerciale
+  - source de verite pratique pour les placeholders `report_*` issus de `purchase_trade.sale`