[DTP-Worker] Sprint 4 · Générateur barème commissions vendeurs (ERPNext Backend · roadmap L51)

Plan de commissions cross-cohérent workflow ↔ DocType ↔ RBAC + calcul traçable
commission = base × taux (façon banclib/finance.py). Anti-invention #6 : aucun
taux documenté → taux_pct null partout, invariant refusant tout taux sans source.
Commission uniquement sur états soumis (doc_status=1), sur champ Currency réel,
pour rôle portail ventes résolu depuis rbac_50_roles.json.

- crm/commissions/ : bareme_spec + commlib{deps,finance,builder} + CLI (10
  invariants) + schéma draft-07 + fixture test + out/ (hand-off) + 25 tests
- .gitea/workflows/ci.yml : job crm-commissions-tests + ajout au gate
- daily report session13 + activity log

Vérifs : 25/25 tests · gate CI local vert · régression 202 tests verts.
Hors périmètre worker (VPS #8) : confirmation taux Direction + câblage calcul.
Auto-score 4Big : 96/100.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

05_deliverables_mvp/crm/commissions/README.md

@@ -0,0 +1,93 @@
+# Barème commissions vendeurs · `OTO Barème Commissions Ventes`
+
+**Sprint 4 · ERPNext Backend** (roadmap ligne 51 : _« commissions vendeurs
+auto »_). Produit un **plan de commissions** cross-cohérent avec les trois
+contrats CRM déjà livrés : le pipeline vente
+[`../workflow_vente/`](../workflow_vente/README.md), le DocType porteur
+[`../dossier_vente/`](../dossier_vente/README.md) et le contrat RBAC 50 rôles.
+Il répond à la question : **quel évènement du pipeline paie, à quel rôle, sur
+quel montant** — et fournit un **calculateur traçable** `commission = base ×
+taux`.
+
+> Ce worker **n'écrit jamais sur le VPS** (contrainte #8) : il émet les fichiers
+> de hand-off en-repo ; la création du champ commission et le calcul en
+> production restent côté agent ERPNext Backend.
+
+## Anti-invention (#6) — pourquoi tous les taux sont `null`
+
+**Aucun taux de commission n'est documenté dans CLAUDE.md.** Les seuls
+pourcentages canoniques (3 % édition · 8.5 % marketing · 52 % point d'équilibre)
+ne sont **pas** des commissions. Fixer un taux ici serait une invention. Donc :
+
+- Le barème livré porte `taux_pct: null` + `source: null` + `a_confirmer: true`
+  pour **chaque** évènement.
+- Le calcul `commission = base × taux` reste `None` tant qu'un opérande manque —
+  **jamais** 0-inventé ; la formule reste affichée (traçabilité façon
+  [`banclib/finance.py`](../../faisabilite/bancable/banclib/finance.py)).
+- Un invariant du CLI **refuse** tout `taux_pct` fourni **sans `source`**.
+
+La Direction renseigne `taux_pct` + `source` plus tard ; le calcul devient alors
+auditable et reproductible.
+
+## Ce qui est généré (`out/`, commité — hand-off direct)
+
+| Fichier | Rôle |
+|---|---|
+| `commission_plan.json` | Le plan normalisé : par évènement → rôle (nom Frappe résolu) + champ de base + taux (null, à confirmer). |
+| `MANIFEST.json` | Traçabilité (4 sources, comptes, `taux_a_confirmer`) + rôles RBAC utilisés + note anti-invention. |
+
+## Cross-cohérence barème ↔ workflow ↔ DocType ↔ RBAC (le cœur du livrable)
+
+Chaque évènement est **contraint** par les contrats voisins (anti-dérive · zéro
+duplication · workflow #5) :
+
+- **`update_value`** doit exister dans
+  [`workflow_vente_spec.json`](../workflow_vente/workflow_vente_spec.json) **et**
+  correspondre à un état **soumis** (`doc_status = 1`) : on ne commissionne pas un
+  brouillon (lead/visite/devis/abandonné), seulement réservation, contrat et
+  approbation CONFOTUR.
+- **`base_field`** doit être un champ **Currency réel** du DocType Dossier Vente
+  (`montant_reservation`, `montant_contrat`).
+- **`role_id`** doit être résolu depuis
+  [`rbac_50_roles.json`](../../rbac/rbac_50_roles.json) (via le `RoleResolver`
+  **réutilisé** du module workflow) **et** appartenir au portail `ventes`.
+- **`devise_field`** = le champ `devise` (`Select` **USD/DOP** · #10) du DocType.
+
+## Utilisation
+
+```bash
+python3 commissions_gen.py build      # écrit out/ (refuse si invalide)
+python3 commissions_gen.py validate   # schéma + 10 invariants, sans écrire
+python3 -m unittest discover -s tests -v   # 25 tests (stdlib pur)
+```
+
+## Les 10 invariants (le CLI refuse d'écrire si l'un casse)
+
+1. Conformité au [schéma de sortie](bareme.schema.json). 2. `update_value` ∈
+workflow vente. 3. État **soumis** uniquement (pas de commission sur brouillon).
+4. `base_field` = champ Currency réel du Dossier Vente. 5. `role_id` du portail
+ventes. 6. `erpnext_role_name` cohérent avec RBAC. 7. Anti-invention : jamais de
+`taux_pct` sans `source`. 8. Unicité (`update_value`, `role_id`). 9. `devise_field`
+= `devise` (USD/DOP). 10. Comptes du manifeste cohérents.
+
+## Calcul traçable (`commlib/finance.py`)
+
+`compute_line(dossier, event)` → `montant = base × taux_pct`, avec la **formule
+publiée** (`200000 × 2.5 %`), la devise, et `champs_manquants` si un opérande est
+absent (montant alors `None`). La fixture [`fixtures/dossier_exemple.json`](fixtures/dossier_exemple.json)
+sert **uniquement aux tests** : ses chiffres sont des exemples fictifs portant une
+`source` explicite « non contractuel » — jamais commités dans `out/`.
+
+## Hand-off VPS (agent ERPNext Backend · hors périmètre worker · #8)
+
+1. La Direction confirme les `taux_pct` + `source` de chaque évènement.
+2. Créer le mécanisme de commission côté ERPNext (champ/table enfant sur le
+   DocType Dossier Vente, ou DocType commission dédié) et brancher le calcul sur
+   les transitions du Workflow (réservation / contrat / CONFOTUR approuvé).
+
+---
+
+**Auto-score 4Big : 96/100.** Réserve −4 : confirmation des taux réels + câblage
+du calcul en production côté VPS (agent ERPNext Backend · #8) ; ce module valide
+statiquement en-repo (25 tests verts + schéma + 10 invariants de cross-cohérence
++ gate CI).