118 lines
4.0 KiB
Markdown
118 lines
4.0 KiB
Markdown
# Guide de lecture des règles business
|
|
|
|
Statut: `migration partielle`
|
|
Dernière mise à jour: `2026-05-13`
|
|
|
|
Ce dossier devient la source de lecture thématique publiée dans le wiki pour les
|
|
règles business du module `purchase_trade`.
|
|
|
|
Toutes les pages business publiées dans `modules/purchase_trade/docs/business/`
|
|
sont générées depuis une source de vérité plus sobre, rangée hors du dossier
|
|
wiki dans `modules/purchase_trade/docs_source/business/`.
|
|
|
|
Les pages publiées portent un commentaire `Generated from ...` en tête de
|
|
fichier et ne doivent pas être modifiées directement. Aucun contenu business ne
|
|
doit être ajouté ou modifié sans passer par cette source puis par le script de
|
|
génération.
|
|
|
|
Chaque page doit rester lisible par deux publics:
|
|
|
|
- les consultants, qui ont besoin d'une règle fonctionnelle stable sans détail
|
|
de code inutile;
|
|
- les développeurs, qui ont besoin des champs, modèles, fichiers et tests
|
|
concernés pour appliquer la règle sans l'interpréter.
|
|
|
|
## Convention de langues
|
|
|
|
Chaque page thématique durable doit exister en deux versions maintenues
|
|
ensemble:
|
|
|
|
- une page française, rédigée en français correct avec accents, typographie et
|
|
formulations naturelles pour le wiki consultant;
|
|
- une page anglaise miroir, portant le même contenu fonctionnel et technique.
|
|
|
|
Convention de nommage:
|
|
|
|
- page française principale: `theme.md`;
|
|
- page anglaise miroir: `theme.en.md`.
|
|
|
|
Toute modification d'une règle business, d'un statut, d'un champ technique ou
|
|
d'un point de vigilance doit être reportée dans les deux pages au même moment.
|
|
Les deux pages doivent indiquer leur page miroir en en-tête.
|
|
|
|
## Convention source / wiki
|
|
|
|
Pour toute page business:
|
|
|
|
- éditer la source de vérité dans `modules/purchase_trade/docs_source/business/`;
|
|
- régénérer la version wiki avec:
|
|
|
|
```bash
|
|
python modules/purchase_trade/docs/tools/render_business_docs.py
|
|
```
|
|
|
|
Le rendu wiki privilégie du HTML simple et portable plutôt que des extensions
|
|
MkDocs optionnelles. Cela évite d'exposer dans le wiki des marqueurs non rendus
|
|
comme `!!!` ou `:material-...:`.
|
|
|
|
Les fichiers générés dans `modules/purchase_trade/docs/business/` sont des
|
|
artefacts de publication: ils peuvent être relus, mais toute correction doit
|
|
être reportée dans `docs_source/business/` avant régénération.
|
|
|
|
Avant de livrer une modification documentaire, vérifier que les pages publiées
|
|
sont à jour avec:
|
|
|
|
```bash
|
|
python modules/purchase_trade/docs/tools/render_business_docs.py --check
|
|
```
|
|
|
|
## Convention de rédaction
|
|
|
|
Pour chaque règle durable, utiliser autant que possible ce format:
|
|
|
|
```md
|
|
### BR-PT-THEME-001 - Titre court
|
|
|
|
Statut: active
|
|
Source: business-rules.md / note de session / décision projet
|
|
|
|
#### Règle consultant
|
|
|
|
Texte fonctionnel, sans nom de champ si ce n'est pas nécessaire.
|
|
|
|
#### Notes développeur
|
|
|
|
- Modèles/champs:
|
|
- Fichiers:
|
|
- Tests:
|
|
- 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
|
|
sources de vérification jusqu'à ce que chaque décision soit promue dans une
|
|
page thématique:
|
|
|
|
- `modules/purchase_trade/docs/business-rules.md`
|
|
- `modules/purchase_trade/docs/fees.md`
|
|
- `modules/purchase_trade/docs/padding-invoice-accounting.md`
|
|
- `modules/purchase_trade/docs/template-rules.md`
|
|
- `modules/purchase_trade/docs/template-properties.md`
|
|
- `notes/business_rules.md`
|
|
- `notes/template_business_rules.md`
|