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