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

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

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

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