tradon/modules/purchase_trade/docs/template-rules.md

# Template Rules - Purchase Trade

Statut: `draft`
Version: `v0.2`
Derniere mise a jour: `2026-03-27`

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

### TR-006 - Penser au cache des reports facture avant d'accuser le `.fodt`

- Les actions de report `account.invoice` peuvent partager le meme moteur de rendu.
- Dans `modules/account_invoice/invoice.py`, le champ `invoice_report_cache` peut reutiliser un document deja genere.
- Symptome typique:
  - plusieurs actions differentes (`Provisional Invoice`, `Final Invoice`, `Prepayment`, etc.) semblent ouvrir le meme template ou le meme rendu
- Reflexe a avoir:
  - verifier si le probleme vient du cache avant de modifier le `.fodt`
  - pour un report alternatif, ne pas reutiliser le cache du report standard `account_invoice/invoice.fodt`
  - si besoin, bypasser la lecture/ecriture du cache pour les templates alternatifs

### TR-007 - Pour une facture trade, privilegier le lot physique comme chemin de navigation

- Pour remonter d'une facture vers des donnees logistiques ou metier, ne pas dupliquer de chemins differents selon achat/vente.
- Regle pratique:
  - partir de la ligne metier (`purchase.line` ou `sale.line`)
  - retrouver le lot physique associe
  - utiliser ce lot comme pont vers le shipment et les autres objets lies
- Ce chemin doit etre privilegie pour exposer des proprietes `report_*` comme:
  - `report_bl_date`
  - `report_loading_port`
  - `report_discharge_port`
  - `report_controller_name`
  - `report_si_number`
  - `report_proforma_invoice_number`
  - `report_proforma_invoice_date`

### TR-008 - Le freight amount d'un template facture vient du fee de shipment

- Ne pas lire le fret directement sur `account.invoice`.
- Pour les templates `invoice_ict*`, le `FREIGHT VALUE` doit etre expose par une propriete Python du type `invoice.report_freight_amount`.
- La logique attendue est:
  - retrouver le lot physique pertinent
  - retrouver son shipment
  - chercher le `fee.fee` du shipment avec `product.name = 'Maritime freight'`
  - utiliser `fee.get_amount()`
- Si le fee a sa propre devise, preferer aussi exposer le symbole de devise depuis le fee plutot que depuis la facture.

## 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.
7. Si plusieurs actions affichent le meme rendu, verifier ensuite le cache `invoice_report_cache`.

## 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 metier deja exposees
  - exposer dans `modules/purchase_trade/invoice.py` des proprietes de pont `account.invoice -> sale/purchase`
  - pour les donnees shipment et freight, passer par le lot physique comme pont achat/vente

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