admin/tradon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
laurentbarontini
2026-05-14 11:20:33 +02:00
parent 355831c76d
commit 2b3c823743
41 changed files with 2101 additions and 554 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
modules/purchase_trade/docs/business/README.md
View File

@@ -1,3 +1,5 @@
<!-- Generated from docs_source/business by docs/tools/render_business_docs.py. -->
# Guide de lecture des règles business
Statut: `migration partielle`
@@ -6,32 +8,44 @@ 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`.
Certaines pages peuvent être générées depuis une source de vérité plus sobre,
rangée hors du dossier wiki dans `modules/purchase_trade/docs_source/`. Dans ce
cas, la page publiée dans `modules/purchase_trade/docs/` porte un commentaire
`Generated from ...` en tête de fichier et ne doit pas être modifiée
directement.
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.
<ul style="margin:0.65rem 0 1rem 1.1rem; padding-left:1rem; list-style-type:disc;">
<li style="margin:0.38rem 0;">les consultants, qui ont besoin d&#x27;une règle fonctionnelle stable sans détail de code inutile;
</li>
<li style="margin:0.38rem 0;">les développeurs, qui ont besoin des champs, modèles, fichiers et tests concernés pour appliquer la règle sans l&#x27;interpréter.
</li>
</ul>
## 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.
<ul style="margin:0.65rem 0 1rem 1.1rem; padding-left:1rem; list-style-type:disc;">
<li style="margin:0.38rem 0;">une page française, rédigée en français correct avec accents, typographie et formulations naturelles pour le wiki consultant;
</li>
<li style="margin:0.38rem 0;">une page anglaise miroir, portant le même contenu fonctionnel et technique.
</li>
</ul>
Convention de nommage:
- page française principale: `theme.md`;
- page anglaise miroir: `theme.en.md`.
<ul style="margin:0.65rem 0 1rem 1.1rem; padding-left:1rem; list-style-type:disc;">
<li style="margin:0.38rem 0;">page française principale: <code>theme.md</code>;
</li>
<li style="margin:0.38rem 0;">page anglaise miroir: <code>theme.en.md</code>.
</li>
</ul>
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.
@@ -39,50 +53,61 @@ Les deux pages doivent indiquer leur page miroir en en-tête.
## Convention source / wiki
Pour les pages qui ont besoin d'une présentation riche dans MkDocs:
Pour toute page business:
- éditer la source de vérité dans `modules/purchase_trade/docs_source/`;
- régénérer la version wiki avec:
<ul style="margin:0.65rem 0 1rem 1.1rem; padding-left:1rem; list-style-type:disc;">
<li style="margin:0.38rem 0;">éditer la source de vérité dans <code>modules/purchase_trade/docs_source/business/</code>;
</li>
<li style="margin:0.38rem 0;">régénérer la version wiki avec:
</li>
</ul>
```bash
python modules/purchase_trade/docs/tools/render_business_docs.py
```
<pre style="background:#263238; color:#eef7ff; padding:1rem; border-radius:0.35rem; overflow:auto;"><code>python modules/purchase_trade/docs/tools/render_business_docs.py</code></pre>
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:
<pre style="background:#263238; color:#eef7ff; padding:1rem; border-radius:0.35rem; overflow:auto;"><code>python modules/purchase_trade/docs/tools/render_business_docs.py --check</code></pre>
## Convention de rédaction
Pour chaque règle durable, utiliser autant que possible ce format:
```md
### BR-PT-THEME-001 - Titre court
<pre style="background:#263238; color:#eef7ff; padding:1rem; border-radius:0.35rem; overflow:auto;"><code>### 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.
Texte fonctionnel, sans nom de champ si ce n&#x27;est pas nécessaire.
#### Notes développeur
- Modèles/champs:
- Fichiers:
- Tests:
- Points de vigilance:
```
- Points de vigilance:</code></pre>
## 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.
<ul style="margin:0.65rem 0 1rem 1.1rem; padding-left:1rem; list-style-type:disc;">
<li style="margin:0.38rem 0;">un check applicatif bloquant dans le code Python, appelé à la fin des flux qui modifient les données concernées;
</li>
<li style="margin:0.38rem 0;">un diagnostic SQL en lecture seule pour auditer les bases existantes ou les bases de test.
</li>
</ul>
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
@@ -94,10 +119,19 @@ 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`
<ul style="margin:0.65rem 0 1rem 1.1rem; padding-left:1rem; list-style-type:disc;">
<li style="margin:0.38rem 0;"><code>modules/purchase_trade/docs/business-rules.md</code>
</li>
<li style="margin:0.38rem 0;"><code>modules/purchase_trade/docs/fees.md</code>
</li>
<li style="margin:0.38rem 0;"><code>modules/purchase_trade/docs/padding-invoice-accounting.md</code>
</li>
<li style="margin:0.38rem 0;"><code>modules/purchase_trade/docs/template-rules.md</code>
</li>
<li style="margin:0.38rem 0;"><code>modules/purchase_trade/docs/template-properties.md</code>
</li>
<li style="margin:0.38rem 0;"><code>notes/business_rules.md</code>
</li>
<li style="margin:0.38rem 0;"><code>notes/template_business_rules.md</code>
</li>
</ul>