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

Business Rules - Purchase Trade

Statut: draft Version: v0.2 Derniere mise a jour: 2026-03-27 Owner metier: a completer Owner technique: a completer

1) Scope

• Domaine: purchase_trade
• Hors scope:
• Modules impactes:
  • purchase_trade
  • lot

2) Glossaire

• Purchase Line: ligne d'achat.
• quantity_theorical: quantite theorique contractuelle de la ligne.
• Virtual Lot: lot unique de type virtual rattache a une purchase.line.
• lot.qt: table des quantites ouvertes, matchées ou shippées par lot.
• lot.qt ouvert: enregistrement lot.qt avec lot_p = virtual lot, lot_s = None et sans shipment.

3) Regles metier

BR-PT-001 - Ajustement de la quantite theorique apres creation du contrat

• Intent: conserver la coherence entre la quantite theorique de la ligne d'achat, le lot virtuel associe et les quantites ouvertes stockees dans lot.qt.
• Description:
  • Quand purchase.line.quantity_theorical est modifiee apres creation du contrat, le systeme doit recalculer le delta entre l'ancienne et la nouvelle valeur.
  • La regle s'applique au lot unique de type virtual rattache a la purchase.line.
• Conditions d'entree:
  • Une purchase.line existe deja.
  • Son champ quantity_theorical est modifie via write.
  • Un lot virtual est rattache a la ligne.
• Resultat attendu:
  • Si delta > 0:
    • augmenter la quantite courante du lot virtual via set_current_quantity pour conserver l'historique lot.qt.hist
    • augmenter le lot.qt ouvert existant
    • si aucun lot.qt ouvert n'existe, en creer un nouveau avec le delta
  • Si delta < 0:
    • diminuer le lot.qt ouvert uniquement si la quantite ouverte disponible est suffisante
    • diminuer la quantite courante du lot virtual du meme delta
    • si aucun lot.qt ouvert n'existe ou si sa quantite est insuffisante, bloquer avec l'erreur Please unlink or unmatch lot
• Definition du lot.qt ouvert:
  • lot_p = virtual lot
  • lot_s = None
  • lot_shipment_in = None
  • lot_shipment_internal = None
  • lot_shipment_out = None
• Exceptions:
  • si aucun lot virtual n'est trouve sur la ligne, la regle ne fait rien
• Priorite:
  • bloquante
• Source:
  • Decision metier documentee dans les commentaires de purchase_trade.purchase.Line.write

BR-PT-002 - Le lot physique est le pont metier entre purchase, sale et shipment

• Intent: disposer d'un chemin unique et stable pour retrouver les informations logistiques et de facturation reliees a un contrat d'achat ou de vente.
• Description:
  • Le lot physique (lot_type = physic) porte simultanement le lien vers:
    • la purchase.line via lot.line
    • la sale.line via lot.sale_line
    • le shipment via lot.lot_shipment_in / lot.lot_shipment_internal / lot.lot_shipment_out
  • Pour toute logique qui doit naviguer entre achat, vente, shipment et facture, il faut privilegier ce lot physique comme source de verite.
• Resultat attendu:
  • depuis une facture d'achat:
    • remonter a la purchase.line
    • puis au lot physique de la ligne
    • puis au shipment et aux donnees logistiques associees
  • depuis une facture de vente:
    • remonter a la sale.line
    • puis au lot physique matchant qui porte aussi la purchase.line
    • puis au shipment et aux donnees logistiques associees
• Cas d'usage typiques:
  • recuperer bl_date, bl_number, controller, from_location, to_location
  • retrouver une facture provisoire liee au lot
  • retrouver des fees rattaches au shipment
• Priorite:
  • structurante

BR-PT-003 - Le freight amount des templates facture vient du fee de shipment

• Intent: afficher dans les documents facture la vraie valeur de fret maritime rattachee au shipment du lot physique.
• Description:
  • Le FREIGHT VALUE d'une facture ne doit pas etre pris sur la facture elle-meme.
  • Il doit etre calcule a partir du fee.fee rattache au shipment (shipment_in) du lot physique relie a la facture.
• Regle de navigation:
  • retrouver le lot physique pertinent depuis la facture
  • retrouver son shipment
  • chercher le fee.fee avec:
    • shipment_in = shipment.id
    • product.name = 'Maritime freight'
  • utiliser fee.get_amount() comme montant de fret
• Portee:
  • s'applique aussi bien aux factures d'achat qu'aux factures de vente
  • cote vente, la remontee doit passer par le lot physique qui fait le lien entre purchase.line et sale.line
• Priorite:
  • importante

4) Exemples concrets

Exemple E1 - Augmentation simple

• Donnees:
  • ancienne quantity_theorical = 100
  • nouvelle quantity_theorical = 120
  • lot.qt ouvert = 40
• Attendu:
  • lot virtual augmente de 20
  • lot.qt ouvert passe de 40 a 60

Exemple E2 - Augmentation sans lot.qt ouvert

• Donnees:
  • ancienne quantity_theorical = 100
  • nouvelle quantity_theorical = 110
  • aucun lot.qt ouvert
• Attendu:
  • lot virtual augmente de 10
  • creation d'un lot.qt ouvert a 10

Exemple E3 - Diminution possible

• Donnees:
  • ancienne quantity_theorical = 100
  • nouvelle quantity_theorical = 90
  • lot.qt ouvert = 25
• Attendu:
  • lot virtual diminue de 10
  • lot.qt ouvert passe de 25 a 15

Exemple E4 - Diminution impossible

• Donnees:
  • ancienne quantity_theorical = 100
  • nouvelle quantity_theorical = 80
  • lot.qt ouvert = 5
• Attendu:
  • blocage avec Please unlink or unmatch lot

5) Impact code attendu

• Fichiers Python concernes:
  • modules/purchase_trade/purchase.py
  • modules/purchase_trade/lot.py

6) Strategie de tests

Pour cette regle, couvrir au minimum:

• augmentation avec lot.qt ouvert existant
• augmentation sans lot.qt ouvert
• diminution possible
• diminution impossible avec erreur