notes

modules/purchase_trade/docs/business/INDEX.md

@@ -17,6 +17,7 @@ Statut: `migration partielle`
 - Relatorio, `.fodt`, proprietes `report_*`: [reports-templates.md](reports-templates.md)
 - Risque, credit, forex: [risk-credit-forex.md](risk-credit-forex.md)
 - Rapport Lots Management: [lots-management.md](lots-management.md)
+- Diagnostics SQL des invariants: [sql/README.md](sql/README.md)
 
 ## Regles migrees dans cette premiere passe
 
@@ -25,6 +26,8 @@ Statut: `migration partielle`
 - `BR-PT-CON-003`: lieux stock propages dans Create Contracts.
 - `BR-PT-LOT-001`: cycle de vie des lots et des quantites.
 - `BR-PT-LOT-002`: quantity contractuelle, execute physique et ligne finie.
+- `BR-PT-LOT-003`: garde-fous Python et diagnostics SQL des invariants de
+  quantite.
 - `BR-PT-MAT-001`: Create Contracts multi-lots.
 - `BR-PT-SHP-001`: affectation controller.
 - `BR-PT-SHP-002`: couts SLA controller.

modules/purchase_trade/docs/business/README.md

@@ -53,6 +53,20 @@ Texte fonctionnel, sans nom de champ si ce n'est pas nécessaire.
 - Points de vigilance:
 ```
 
+## Convention de validation
+
+Quand une règle business devient structurante pour l'intégrité des données, elle
+doit être accompagnée autant que possible de deux garde-fous:
+
+- un check applicatif bloquant dans le code Python, appelé à la fin des flux qui
+  modifient les données concernées;
+- un diagnostic SQL en lecture seule pour auditer les bases existantes ou les
+  bases de test.
+
+Les diagnostics SQL du module sont rangés dans `business/sql/`. Ils ne
+remplacent pas les règles applicatives: ils servent à retrouver et qualifier les
+écarts déjà présents dans une base.
+
 ## Sources pendant la migration
 
 Les anciennes pages ne sont pas supprimées à cette étape. Elles restent des

modules/purchase_trade/docs/business/invariants.md

@@ -34,6 +34,16 @@ executer.
 - 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
 
@@ -63,4 +73,3 @@ chemin technique pour les retrouver est complexe.
 - Ne pas supposer qu'une variable locale comme `shipment` existe partout dans
   un `.fodt`.
 - Voir [reports-templates.md](reports-templates.md).
-

modules/purchase_trade/docs/business/sessions.md

@@ -23,4 +23,9 @@ canonique seulement quand elle est reprise dans une page thematique.
   [lots-and-quantities.md](lots-and-quantities.md).
 - Session `2026-05-09`: Lots Management, promue partiellement dans
   [lots-management.md](lots-management.md).
-
+- Session `2026-05-13`: cadrage `quantity_theorical` / `quantity`, amount de
+  ligne, Weight basis, invariants de quantite, checks Python bloquants et
+  diagnostic SQL. Promue dans
+  [lots-and-quantities.md](lots-and-quantities.md),
+  [lots-and-quantities.en.md](lots-and-quantities.en.md),
+  [invariants.md](invariants.md) et [sql/README.md](sql/README.md).

modules/purchase_trade/docs/business/sql/README.md

@@ -2,6 +2,13 @@
 
 These scripts are read-only diagnostics for a PostgreSQL test database.
 
+They exist to support the same business rules enforced by Python guards. The
+expected workflow is:
+
+1. write the consultant/developer rule in the thematic documentation;
+2. enforce the invariant in the application code when feasible;
+3. provide a read-only SQL diagnostic to audit existing data.
+
 ## quantity_consistency_checks.sql
 
 Checks the two core lot quantity invariants documented in

modules/purchase_trade/docs/index.md

@@ -12,6 +12,7 @@ regles lisibles par les consultants des notes utiles aux developpeurs.
 - [Glossaire](business/glossary.md)
 - [Invariants structurants](business/invariants.md)
 - [Journal de migration et sessions](business/sessions.md)
+- [Diagnostics SQL des règles business](business/sql/README.md)
 
 ## Regles par domaine