25.03.26

modules/purchase_trade/docs/business-rules.md

@@ -0,0 +1,113 @@
+# Business Rules - Purchase Trade
+
+Statut: `draft`
+Version: `v0.1`
+Derniere mise a jour: `2026-03-25`
+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`
+
+## 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