diff --git a/modules/purchase_trade/docs/business/INDEX.md b/modules/purchase_trade/docs/business/INDEX.md index 3eeff12..af2d99d 100644 --- a/modules/purchase_trade/docs/business/INDEX.md +++ b/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. diff --git a/modules/purchase_trade/docs/business/README.md b/modules/purchase_trade/docs/business/README.md index 60b45c2..96e2499 100644 --- a/modules/purchase_trade/docs/business/README.md +++ b/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 diff --git a/modules/purchase_trade/docs/business/invariants.md b/modules/purchase_trade/docs/business/invariants.md index 2fa25de..a38144a 100644 --- a/modules/purchase_trade/docs/business/invariants.md +++ b/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). - diff --git a/modules/purchase_trade/docs/business/sessions.md b/modules/purchase_trade/docs/business/sessions.md index 516a962..5cb8e8a 100644 --- a/modules/purchase_trade/docs/business/sessions.md +++ b/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). diff --git a/modules/purchase_trade/docs/business/sql/README.md b/modules/purchase_trade/docs/business/sql/README.md index 24ba628..426119d 100644 --- a/modules/purchase_trade/docs/business/sql/README.md +++ b/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 diff --git a/modules/purchase_trade/docs/index.md b/modules/purchase_trade/docs/index.md index 23990b2..18f50e8 100644 --- a/modules/purchase_trade/docs/index.md +++ b/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