docs

modules/purchase_trade/docs_source/business/invariants.md

@@ -0,0 +1,75 @@
+# Invariants structurants
+
+Statut: `migration partielle`
+
+Ces invariants doivent etre relus avant de modifier des flux `purchase_trade`
+touchant lots, quantites, fees, PnL, factures ou templates.
+
+## INV-PT-001 - Le lot physique est le pont metier stable
+
+### Regle consultant
+
+Quand une information doit relier achat, vente, shipment et facture, le chemin
+fonctionnel de reference passe par le lot physique. Il porte le lien entre les
+contrats et l'execution logistique.
+
+### Notes developpeur
+
+- Source historique: `BR-PT-002`.
+- Voir aussi: [lots-and-quantities.md](lots-and-quantities.md),
+  [matching.md](matching.md), [reports-templates.md](reports-templates.md).
+- Champs frequents: `lot.line`, `lot.sale_line`, `lot_shipment_in`,
+  `lot_shipment_internal`, `lot_shipment_out`.
+
+## INV-PT-002 - Le reliquat ouvert ne doit pas doubler les lots physiques
+
+### Regle consultant
+
+Une quantite deja executee physiquement ne doit pas rester disponible comme
+quantite ouverte. Le reliquat ouvert represente seulement ce qui reste a
+executer.
+
+### Notes developpeur
+
+- Source historique: `BR-PT-020`.
+- Le calcul doit tenir compte de la quantite contractuelle, des lots physiques
+  existants et des `lot.qt` deja matches ou shippes.
+- Regle de conservation:
+  `sum(lots physiques) + lot virtuel = quantity_theorical`.
+- Regle du forecast ouvert:
+  `sum(lot.qt non zero) = max(lot virtuel, 0)`.
+- Les lignes `lot.qt` a zero sont ignorees par les checks: elles peuvent servir
+  de memoire d'une prevision consommee.
+- Le check applicatif est centralise dans
+  `lot.lot.assert_lines_quantity_consistency()`.
+- Le diagnostic SQL correspondant est
+  [sql/quantity_consistency_checks.sql](sql/quantity_consistency_checks.sql).
+
+## INV-PT-003 - Les fees utilisent leurs lots effectifs
+
+### Regle consultant
+
+Un fee ouvert suit le lot virtuel tant qu'il n'y a pas de lot physique. Des
+qu'un ou plusieurs lots physiques sont lies au fee, ils deviennent la base
+effective de calcul.
+
+### Notes developpeur
+
+- Source historique: `BR-PT-021`.
+- Ne pas supprimer le lien virtuel: il reste le fallback si les physiques sont
+  retires.
+- Voir [fees.md](fees.md).
+
+## INV-PT-004 - Les templates doivent rester simples
+
+### Regle consultant
+
+Les documents doivent afficher des informations metier stables, meme si le
+chemin technique pour les retrouver est complexe.
+
+### Notes developpeur
+
+- Preferer des proprietes Python `report_*` aux expressions Genshi complexes.
+- Ne pas supposer qu'une variable locale comme `shipment` existe partout dans
+  un `.fodt`.
+- Voir [reports-templates.md](reports-templates.md).