Claude Code DTP Worker
71c1223cc3
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>
94 lines
4.7 KiB
Markdown
94 lines
4.7 KiB
Markdown
# 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).
|