145 lines
6.4 KiB
Markdown
145 lines
6.4 KiB
Markdown
# AGENTS.md - Module `purchase_trade`
|
|
|
|
Ce guide complete le `AGENTS.md` racine.
|
|
Pour ce module, les regles locales ci-dessous priment.
|
|
|
|
## 1) Perimetre metier
|
|
|
|
Le module `purchase_trade` etend les flux achat/vente Tryton avec une logique
|
|
de negoce physique:
|
|
|
|
- contrats d'achat (`purchase.purchase`, `purchase.line`)
|
|
- contrats de vente (`sale.sale`, `sale.line`)
|
|
- lots physiques et virtuels
|
|
- matching achat/vente
|
|
- shipments et execution logistique
|
|
- frais (`fee.fee`)
|
|
- templates de documents metier et facture
|
|
|
|
## 2) Fichiers pivots
|
|
|
|
- Contrats achat:
|
|
- `modules/purchase_trade/purchase.py`
|
|
- Contrats vente:
|
|
- `modules/purchase_trade/sale.py`
|
|
- Lots / matching / invoicing:
|
|
- `modules/purchase_trade/lot.py`
|
|
- Shipments / lien facture-lot:
|
|
- `modules/purchase_trade/stock.py`
|
|
- Fees:
|
|
- `modules/purchase_trade/fee.py`
|
|
- Bridge facture / templates:
|
|
- `modules/purchase_trade/invoice.py`
|
|
- Vues:
|
|
- `modules/purchase_trade/view/*.xml`
|
|
- Actions module:
|
|
- `modules/purchase_trade/*.xml`
|
|
- Manifest:
|
|
- `modules/purchase_trade/tryton.cfg`
|
|
|
|
## 3) Documentation locale a lire en priorite
|
|
|
|
- Regles metier:
|
|
- `modules/purchase_trade/docs/business-rules.md`
|
|
- Regles templates:
|
|
- `modules/purchase_trade/docs/template-rules.md`
|
|
- Catalogue des proprietes templates:
|
|
- `modules/purchase_trade/docs/template-properties.md`
|
|
|
|
## 4) Invariants metier a preserver
|
|
|
|
- Un lot `virtual` est la reference d'ouverture de quantite pour une `purchase.line`.
|
|
- Une `sale.line` doit aussi avoir au minimum un lot `virtual`; une valuation
|
|
cote sale ne doit donc pas disparaitre juste parce que le lot est `open`.
|
|
- Le lot physique est le pont principal entre:
|
|
- `purchase.line`
|
|
- `sale.line`
|
|
- shipment
|
|
- facture
|
|
- Pour remonter d'une facture vers shipment / BL / controller / fret:
|
|
- privilegier le lot physique
|
|
- ne pas multiplier des chemins d'acces concurrents
|
|
- Le `FREIGHT VALUE` d'un template facture vient du `fee.fee` du shipment
|
|
dont le produit est `Maritime freight`.
|
|
- Le wizard `Create contracts` en mode `matched` peut maintenant partir de
|
|
plusieurs `lot.qt`, mais doit conserver un matching par lot source et laisser
|
|
`created_by_code = True` sur les lignes creees pour ne pas declencher les
|
|
creations automatiques de lots dans les validations.
|
|
- En valuation / PnL:
|
|
- la valeur stockee dans `type` est la cle technique (`pur. priced`,
|
|
`sale priced`, `pur. fee`, etc.), pas le label affiche dans l'UI
|
|
- les references doivent rester coherentes avec le type de lot:
|
|
`Purchase/Open`, `Purchase/Physic`, `Sale/Open`, `Sale/Physic`
|
|
- pour une sale matchee, les lignes de valuation purchase generees sur un lot
|
|
physique doivent aussi renseigner `sale` et `sale_line` afin de remonter
|
|
dans l'onglet PnL de la sale
|
|
- une sale non matchee doit etre valorisable "sale-first" et alimenter
|
|
`valuation.valuation` / `valuation.valuation.line`
|
|
- si une `sale.line` `basis` n'a ni `price_summary` ni `lot_price_sale`,
|
|
creer quand meme une ligne `sale priced` avec `price = 0` et `amount = 0`
|
|
plutot que de ne rien generer
|
|
- le MTM ne doit etre renseigne que pour `pur. priced`, `sale priced` et
|
|
`derivative`; jamais pour les fees
|
|
- `mtm_price` doit afficher le prix brut de valorisation (sans ratio), alors
|
|
que `mtm` reste le montant calcule selon la logique de strategie
|
|
- En pricing:
|
|
- le `unit_price` doit rester un prix de base, hors `premium`
|
|
- le `premium` doit impacter le prix total economique et donc le `amount`,
|
|
aussi bien en `priced` qu'en `basis`
|
|
- si `linked currency` est active, le `premium` est saisi dans la devise /
|
|
unite liee (ex: `USC/LB`) puis converti vers le repere de la ligne pour le
|
|
calcul du `amount`
|
|
- en `basis + linked currency`, le `linked_price` doit representer le prix
|
|
basis brut (hors premium) dans la devise liee; le `unit_price` reste ce
|
|
prix brut converti, et le `premium` converti est ajoute seulement dans
|
|
l'`amount`
|
|
- si `linked currency` est cochee, `linked_price`, `linked_currency` et
|
|
`linked_unit` sont requis
|
|
- dans les forms, presenter le bloc prix dans l'ordre:
|
|
`price_type` -> linked fields -> `premium` -> `unit_price` -> `amount`
|
|
- en valuation `basis`, le premium s'applique a chaque composant, pas
|
|
uniquement a une ligne de resume
|
|
- pour une ligne `basis` sans `price_summary`, la valuation fallback doit
|
|
utiliser `unit_price + premium` (et pas `unit_price` seul)
|
|
- a la validation d'une `sale.line`, si un lot virtuel est cree et qu'aucun
|
|
matching purchase n'existe, il faut lancer `generate_from_sale_line()` pour
|
|
alimenter le PnL sale-first
|
|
|
|
## 5) Conventions de modification
|
|
|
|
1. Modifier la logique metier dans le fichier pivot le plus proche.
|
|
2. Si un template `.fodt` devient complexe, deplacer la logique dans une
|
|
propriete Python `report_*`.
|
|
3. Pour une facture trade, preferer enrichir `modules/purchase_trade/invoice.py`
|
|
plutot que surcharger lourdement le `.fodt`.
|
|
4. Si une regle metier durable change, mettre a jour
|
|
`docs/business-rules.md`.
|
|
5. Si une convention de template change, mettre a jour
|
|
`docs/template-rules.md`.
|
|
6. Pour les vues XML Tryton de ce module, utiliser `editable="1"` sur les
|
|
`<tree>` editables; ne pas utiliser `editable="bottom"`.
|
|
|
|
## 6) Pieges connus
|
|
|
|
- Plusieurs actions de report `account.invoice` peuvent sembler rendre le meme
|
|
document a cause du cache `invoice_report_cache`.
|
|
- Les reports alternatifs (`Final Invoice`, `Prepayment`, etc.) ne doivent pas
|
|
reutiliser le cache du report standard sans verification.
|
|
- Pour les donnees achat/vente partagees, ne pas supposer qu'une facture de
|
|
vente doit lire directement sur la `sale.line`: souvent, la verite metier
|
|
passe par le lot physique et/ou la `account.invoice.line`.
|
|
- Dans les ecrans PnL, le label `Sale price` correspond au type stocke
|
|
`sale priced`; idem pour `Pur. price` / `pur. priced`.
|
|
- Une ligne `basis` sans resume de pricing peut sinon disparaitre de la
|
|
valuation si aucun fallback explicite a `0` n'est prevu.
|
|
- Le calcul du prix peut diverger entre `unit_price`, `linked_price`,
|
|
`lot_price` et valuation si le premium n'est pas traite explicitement dans
|
|
chaque maillon.
|
|
|
|
## 7) Definition of done (module `purchase_trade`)
|
|
|
|
- Le flux achat/vente/lot cible reste coherent.
|
|
- Les impacts templates/facture ont ete verifies conceptuellement.
|
|
- Les docs locales ont ete mises a jour si une nouvelle regle durable a emerge.
|
|
- Le patch reste minimal et local au domaine demande.
|