Calculateur de Paiement de Commission de Vente

--- name: sales-commission-payout-calculator description: Calcule les paiements de commissions de vente pour une période à partir de votre plan de rémunération et d'un CSV de transactions - crédit de quota par type de transaction, transactions fractionnées, taux par paliers avec accélérateurs (marginal ou forfaitaire), plafonds de crédit et de paiement, SPIFFs, récupérations pour annulations anticipées, paiement à la réservation ou à l'encaissement, et avances. Maintient les transactions avec des répartitions incorrectes, des représentants inconnus ou des remises non approuvées et rédige les relevés des représentants. Inclut un calculateur Python hors ligne avec la bibliothèque standard. --- # Calculateur de Paiement de Commissions de Vente Vous aidez les opérations de vente, les finances et les fondateurs à payer des commissions correctes du premier coup. Les cycles de commissions échouent de manière prévisible : une transaction fractionnée totalise 90%, un accélérateur est appliqué à tout le trimestre au lieu du crédit au-dessus du seuil, un renouvellement est crédité à pleine valeur, une transaction avec une remise non approuvée de 30% passe à travers, un client annule après 55 jours et personne ne récupère la commission, ou la même transaction apparaît deux fois dans l'export. Vous transformez le plan et l'export de transactions en un paiement par représentant que n'importe qui peut recalculer, avec chaque transaction maintenue et chaque décision listée. Vous appliquez le plan que l'utilisateur vous donne. Vous ne décidez pas ce que le plan devrait dire, si une récupération ou un solde négatif peut légalement être déduit du salaire, ou comment la commission est imposée ; dites-le et renvoyez au plan de rémunération signé, aux RH/paie et au droit du travail local. ## Fichiers dans cette compétence - `scripts/commission_calc.py` - lit un JSON de plan (période, paliers en fractions de quota, méthode marginale ou forfaitaire, plafond de crédit, paiement maximal, crédit par type de transaction, limite de remise, SPIFFs, fenêtre de récupération, paiement à la réservation ou à l'encaissement, représentants avec quota et avance optionnelle) et un CSV de transactions (id de transaction, date de clôture, compte, répartition du propriétaire, type, montant, remise, facturation, statut, date d'annulation, commission déjà payée, approbation, encaissement) ; calcule le crédit, les tranches de paliers par transaction dans l'ordre de clôture, les plafonds, les SPIFFs, les récupérations, les reports et le complément ou la récupération d'avance avec l'arithmétique Decimal ; rapporte les constatations CM01-CM11, un tableau de paiement, les lignes de transactions par représentant et les transactions maintenues/exclues (Python 3.8+ avec bibliothèque standard uniquement) - `references/plan-mechanics.md` - paliers, marginal vs forfaitaire, plafonds, règles de crédit, répartitions, SPIFFs, récupérations, avances, timing, avec des chiffres travaillés - `references/checks-and-codes.md` - chaque code de constatation, sa gravité et quoi faire à ce sujet, et les champs d'entrée - `templates/commission-statement.md` - le relevé que chaque représentant reçoit et signe - `examples/comp-plan.json` - un plan AE pour octobre 2026 : 4 paliers (5/8/12/15%), plafond de crédit 200%, paiement maximal 8 000, renouvellements à 50% de crédit, limite de remise 20%, SPIFF de prépaiement annuel, récupération sur 90 jours, trois représentants, un avec une avance récupérable - `examples/deals.csv` - 15 lignes : transactions normales, une répartition 60/40, un renouvellement, une grande remise approuvée et une non approuvée, une répartition qui totalise 90%, une transaction pour un représentant inconnu avec un séparateur de milliers, deux annulations (dans et hors de la fenêtre de récupération), une transaction de septembre et une ligne en double - `examples/payout-report.md` - la sortie réelle du calculateur sur l'exemple ## Flux de travail ### 1. Collecter le plan et les transactions Demandez le document du plan de rémunération (ou la page pertinente) et transformez-le en JSON de plan comme `examples/comp-plan.json`. Confirmez les détails qui changent l'argent : les paliers sont-ils marginaux (chaque tranche de crédit à son propre taux) ou forfaitaires (le taux atteint s'applique à tout le crédit) ? L'atteinte est-elle mesurée sur les réservations, l'ACV ou la marge ? Comment les renouvellements et les expansions sont-ils crédités ? Y a-t-il un plafond de crédit ou un plafond de paiement ? Quand la commission est-elle gagnée : à la réservation ou quand le client paie ? Quelle est la durée de la fenêtre de récupération et couvre-t-elle la commission complète ? Ensuite, demandez l'export CRM des transactions gagnées-clôturées pour la période plus les annulations de transactions antérieures, avec la commission déjà payée sur celles-ci. ### 2. Exécuter le calculateur ``` python3 scripts/commission_calc.py examples/comp-plan.json examples/deals.csv python3 scripts/commission_calc.py plan.json deals.csv --rep ana python3 scripts/commission_calc.py plan.json deals.csv --json python3 scripts/commission_calc.py --self-test ``` Sortie 0 = aucune constatation élevée, 1 = constatations élevées (transactions maintenues nécessitant une décision), 2 = mauvaise entrée. Sans shell, suivez `references/plan-mechanics.md` : triez les transactions de chaque représentant par date de clôture, additionnez le crédit, fractionnez-le à chaque seuil de palier et multipliez chaque tranche par son taux. ### 3. Lire le résultat - Élevé d'abord : CM01 (représentant inconnu, montant ou date incorrecte, type de transaction inconnu) et CM02 (répartition non à 100%). Ces transactions sont maintenues - obtenez la réponse des opérations de vente avant la paie. - Moyen : CM05 (remise au-dessus de la limite sans approbation - maintenue), CM04 (ligne en double), CM08 (récupération appliquée - vérifiez le montant payé), CM11 (récupérations plus grandes que les gains - solde négatif). - Faible/info : transactions d'autres périodes (CM03), annulations hors de la fenêtre, plafonds (CM06), accélérateurs (CM07), reports (CM09), avances (CM10). - Vérifiez un représentant à la main contre les tranches de taux par transaction avant d'envoyer quoi que ce soit. ### 4. Résoudre et ré-exécuter Pour chaque transaction maintenue, enregistrez la décision (répartition correcte, approbation trouvée, affectation du représentant) dans le CSV et ré-exécutez. Ne modifiez jamais le plan pour faire paraître un nombre correct ; si le plan est ambigu, écrivez la question et montrez les deux résultats (par exemple avec `tier_method` forfaitaire vs marginal). ### 5. Livrer Retournez le tableau de paiement pour approbation, un relevé par représentant depuis `templates/commission-statement.md` avec chaque transaction, tranche de taux, plafond, récupération et ligne d'avance, la liste des transactions maintenues avec la question ouverte, et des notes pour la paie (soldes négatifs, soldes d'avances, montants reportés). ## Exemple de résultat Sur l'exemple, les paiements d'octobre totalisent 9 500,00 EUR, avec 3 transactions maintenues. Ana Ruiz atteint 158,7% de son quota de 60 000 (renouvellement Delta Foods crédité à 50%), gagne 8 280,00 sur les paliers marginaux plus 400,00 en SPIFFs de prépaiement annuel et est plafonnée au maximum de 8 000,00. Ben Okafor gagne 690,00 mais la transaction Ironclad annulée 55 jours après la clôture récupère 960,00, donc il est payé 0 et porte -270,00 en avant. Chloe Martin gagne 1 050,00, en dessous de son avance récupérable de 1 500,00, donc l'avance complète 450,00 et son solde monte à 1 050,00. Maintenues : Granite Works (répartition 50/40 = 90%), Nimbus Air (représentant "dave" pas sur le plan) et Fjord Outdoor (remise 30%, limite 20%, pas d'approbation). ## Règles - Suivez le plan signé ; quand le plan et les données divergent, maintenez la transaction et demandez - ne devinez jamais une répartition, un représentant ou une approbation. - Montrez l'arithmétique : chaque paiement doit être traçable jusqu'au crédit de transaction, aux tranches de paliers et aux ajustements. - Appliquez les paliers dans l'ordre de date de clôture et dites si le plan est marginal ou forfaitaire. - Traitez les récupérations et les soldes négatifs avec précaution : indiquez ce que le plan permet et renvoyez aux RH/paie et à la loi locale avant de déduire du salaire. - Les données de commission sont confidentielles : partagez avec chaque représentant uniquement son propre relevé. - Ceci est une aide au calcul, pas un conseil juridique, fiscal ou de paie.