# Template Properties - Purchase Trade

Statut: `draft`
Version: `v0.3`
Derniere mise a jour: `2026-04-23`

## 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_product_name`
  - Usage: nom produit principal
  - 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

### Payment order

- `report_payment_order_short_name`
  - Usage: nom court emetteur du payment order
  - Source de verite: `invoice.company.party.rec_name`

- `report_payment_order_document_reference`
  - Usage: reference du document payment order
  - Source de verite: `invoice.number`, fallback `invoice.reference`

- `report_payment_order_from_account_nb`
  - Usage: compte bancaire emetteur
  - Source de verite: premier `bank.account` de la societe

- `report_payment_order_to_bank_name`
  - Usage: banque destinataire
  - Source de verite: banque du premier compte bancaire du partenaire facture

- `report_payment_order_to_bank_city`
  - Usage: ville banque destinataire
  - Source de verite: adresse de la banque destinataire

- `report_payment_order_amount`
  - Usage: montant payment order
  - Source de verite: `invoice.total_amount`

- `report_payment_order_currency_code`
  - Usage: devise payment order
  - Source de verite: `invoice.currency` (`code`, fallback `rec_name/symbol`)

- `report_payment_order_amount_text`
  - Usage: montant en lettres
  - Source de verite: conversion `amount_to_currency_words(invoice.total_amount)`

- `report_payment_order_value_date`
  - Usage: date valeur
  - Source de verite: `invoice.payment_term_date`, fallback `invoice.invoice_date`

- `report_payment_order_company_address`
  - Usage: bloc beneficiaire
  - Source de verite: `invoice.invoice_address.full_address`, fallback
    `invoice.report_address`

- `report_payment_order_beneficiary_account_nb`
  - Usage: compte beneficiaire
  - Source de verite: premier compte bancaire du `invoice.party`

- `report_payment_order_beneficiary_bank_name`
  - Usage: banque beneficiaire
  - Source de verite: banque du compte beneficiaire

- `report_payment_order_beneficiary_bank_city`
  - Usage: ville banque beneficiaire
  - Source de verite: adresse banque beneficiaire

- `report_payment_order_swift_code`
  - Usage: swift/bic beneficiaire
  - Source de verite: `bank.bic`

- `report_payment_order_other_instructions`
  - Usage: instructions complementaires
  - Source de verite: `invoice.description`

- `report_payment_order_reference`
  - Usage: reference business de paiement
  - Source de verite: `invoice.reference`, fallback `invoice.number`

- `report_payment_order_current_user`
  - Usage: signataire payment order
  - Source de verite: utilisateur courant (`res.user`)

- `report_payment_order_current_user_email`
  - Usage: email retour swift
  - Source de verite: contact email du `party` utilisateur, fallback `user.email`

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

Usage typique:
- base de travail pour les templates de type `sale_ict.fodt`
- source de verite de plusieurs proprietes du bridge facture

### Proprietes specifiques `sale_melya.fodt`

- `report_melya_proforma_number`
  - Usage: valeur affichee dans `Proforma Nr`
  - Source de verite: deal lie via `report_deal`, fallback numero de vente

- `report_melya_buyer_address`
  - Usage: bloc buyer avec nom long et adresse
  - Source de verite: `sale.invoice_address.full_address` avec le contexte
    `address_with_party`

- `report_melya_incoterm`
  - Usage: ligne `DELIVERY TERMS`
  - Source de verite: incoterm code + lieu incoterm + pays du lieu incoterm

## 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_incoming_amount`
- `report_insurance_amount_insured`
- `report_insurance_surveyor`
- `report_insurance_contact_surveyor`
- `report_insurance_issue_place_and_date`

Usage typique:
- templates shipment relies a l'assurance
- `report_insurance_amount`: montant affiche dans `Amount insured` (priorite a
  `110%` du total incoming, fallback fee `Insurance`)
- `report_insurance_incoming_amount`: somme `incoming_moves` de
  `quantity * unit_price`, avec fallback lot
  (`lot.line.unit_price * lot.get_current_quantity_converted()`)
- `report_insurance_amount_insured`: `110%` de
  `report_insurance_incoming_amount`
- `report_insurance_contact_surveyor`: nom et adresse du surveyor affiches
  sous `Contact the following surveyor` (priorite au champ shipment
  `surveyor`, puis fallback controller / fee `Insurance`). La premiere ligne
  d'adresse est ignoree si elle duplique le nom long de la party.
- base de travail pour un certificat d'assurance lie a un shipment

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