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:

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:

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:

### 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

5.6 KiB Raw Blame History