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

# 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`
- Pour un shipment entrant:
  - reutiliser si possible les proprietes `report_*` exposees sur `stock.shipment.in`

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

- `report_quantity_lines`
  - Usage: detail quantite multi-lignes pour les templates facture
  - Source de verite: `sale.report_quantity_lines` si vente source, sinon aggregation des `account.invoice.line`

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

- `report_rate_lines`
  - Usage: detail multi-lignes du bloc `At ... PER ...`
  - Source de verite: `sale.report_price_lines` si vente source, sinon aggregation des `account.invoice.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_crop_name`
- `report_gross`
- `report_net`
- `report_qt`
- `report_total_quantity`
- `report_quantity_unit_upper`
- `report_quantity_lines`
- `report_nb_bale`
- `report_deal`
- `report_packing`
- `report_price`
- `report_price_lines`
- `report_delivery`
- `report_payment_date`
- `report_shipment`
- `report_shipment_periods`

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`
- `modules/stock/insurance.fodt`

## 9) Proprietes utiles deja presentes sur `stock.shipment.in`

Source code: `modules/purchase_trade/stock.py`

- `report_product_name`
- `report_product_description`
- `report_insurance_footer_ref`
- `report_insurance_certificate_number`
- `report_insurance_account_of`
- `report_insurance_goods_description`
- `report_insurance_loading_port`
- `report_insurance_discharge_port`
- `report_insurance_transport`
- `report_insurance_amount`
- `report_insurance_surveyor`
- `report_insurance_issue_place_and_date`

Usage typique:
- templates shipment relies a l'assurance
- templates qui lisent le fee `Insurance` d'un `stock.shipment.in`

## 10) 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