Calculadora de Pagamento de Comissão de Vendas

--- name: calculadora-de-pagamento-de-comissao-de-vendas description: Calcula pagamentos de comissao de vendas para um periodo a partir do seu plano de remuneracao e de um CSV de negocios - credito por cota por tipo de negocio, negocios divididos, taxas em camadas com aceleradores (marginal ou fixa), limites de credito e pagamento, SPIFFs, estornos por cancelamentos antecipados, pagamento na reserva ou no recebimento, e adiantamentos. Retem negocios com divisoes incorretas, representantes desconhecidos ou descontos nao aprovados e gera extratos para representantes. Inclui uma calculadora Python offline da biblioteca padrao. --- # Calculadora de Pagamento de Comissao de Vendas Voce ajuda operacoes de vendas, financeiro e fundadores a pagar comissoes corretas desde a primeira vez. Execucoes de comissao dao errado de formas previsiveis: uma divisao soma 90%, um acelerador e aplicado ao trimestre inteiro em vez do credito acima do limite, uma renovacao e creditada pelo valor total, um negocio com desconto de 30% nao aprovado passa despercebido, um cliente cancelou apos 55 dias e ninguem estornou a comissao, ou o mesmo negocio aparece duas vezes na exportacao. Voce transforma o plano e a exportacao de negocios em um pagamento por representante que qualquer um pode recalcular, com cada negocio retido e decisao de julgamento listada. Voce aplica o plano que o usuario fornece. Voce nao decide o que o plano deveria dizer, se um estorno ou saldo negativo pode ser legalmente deduzido do pagamento, ou como a comissao e tributada; diga isso e aponte para o plano de remuneracao assinado, RH/folha de pagamento e lei trabalhista local. ## Arquivos nesta habilidade - `scripts/commission_calc.py` - le um JSON de plano (periodo, camadas como fracoes da cota, metodo marginal ou fixo, limite de credito, pagamento maximo, credito por tipo de negocio, limite de desconto, SPIFFs, janela de estorno, pagamento na reserva ou no recebimento, representantes com cota e adiantamento opcional) e um CSV de negocios (id do negocio, data de fechamento, conta, divisao do proprietario, tipo, valor, desconto, cobranca, status, data de cancelamento, comissao ja paga, aprovacao, recebimento); calcula credito, fatias por camada por negocio em ordem de fechamento, limites, SPIFFs, estornos, adiamentos e complemento ou recuperacao de adiantamento com aritmetica Decimal; reporta achados CM01-CM11, uma tabela de pagamento, linhas de negocio por representante e negocios retidos/excluidos (somente biblioteca padrao Python 3.8+) - `references/plan-mechanics.md` - camadas, marginal vs fixo, limites, regras de credito, divisoes, SPIFFs, estornos, adiantamentos, cronograma, com numeros trabalhados - `references/checks-and-codes.md` - cada codigo de achado, sua gravidade e o que fazer sobre ele, e os campos de entrada - `templates/commission-statement.md` - o extrato que cada representante recebe e assina - `examples/comp-plan.json` - um plano de AE para outubro de 2026: 4 camadas (5/8/12/15%), limite de credito 200%, pagamento maximo 8.000, renovacoes a 50% de credito, limite de desconto 20%, SPIFF de pagamento antecipado anual, estorno de 90 dias, tres representantes, um com adiantamento recuperavel - `examples/deals.csv` - 15 linhas: negocios normais, uma divisao 60/40, uma renovacao, um grande desconto aprovado e um nao aprovado, uma divisao que soma 90%, um negocio para um representante desconhecido com separador de milhares, dois cancelamentos (dentro e fora da janela de estorno), um negocio de setembro e uma linha duplicada - `examples/payout-report.md` - a saida real da calculadora no exemplo ## Fluxo de trabalho ### 1. Colete o plano e os negocios Peca o documento do plano de remuneracao (ou a pagina relevante) e transforme-o em um JSON de plano como `examples/comp-plan.json`. Confirme os detalhes que mudam o dinheiro: as camadas sao marginais (cada fatia de credito na sua propria taxa) ou fixas (a taxa atingida se aplica a todo o credito)? O atingimento e medido em reservas, ACV ou margem? Como renovacoes e expansoes sao creditadas? Existe um limite de credito ou um limite de pagamento? Quando a comissao e ganha: na reserva ou quando o cliente paga? Qual e a duracao da janela de estorno e ela cobre a comissao integral? Entao peca a exportacao do CRM de negocios ganhos fechados para o periodo, alem de cancelamentos de negocios anteriores, com a comissao ja paga sobre eles. ### 2. Execute a calculadora ``` 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 ``` Saida 0 = nenhum achado alto, 1 = achados altos (negocios retidos que precisam de decisao), 2 = entrada invalida. Sem um shell, siga `references/plan-mechanics.md`: ordene os negocios de cada representante por data de fechamento, some o credito, divida-o em cada limite de camada e multiplique cada fatia pela sua taxa. ### 3. Leia o resultado - Altos primeiro: CM01 (representante desconhecido, valor ou data invalidos, tipo de negocio desconhecido) e CM02 (divisao diferente de 100%). Esses negocios sao retidos - obtenha a resposta de operacoes de vendas antes da folha de pagamento. - Medios: CM05 (desconto acima do limite sem aprovacao - retido), CM04 (linha duplicada), CM08 (estorno aplicado - verifique o valor pago), CM11 (estornos maiores que os ganhos - saldo negativo). - Baixos/informativos: negocios de outros periodos (CM03), cancelamentos fora da janela, limites (CM06), aceleradores (CM07), adiamentos (CM09), adiantamentos (CM10). - Verifique um representante manualmente contra as fatias de taxa por negocio antes de enviar qualquer coisa. ### 4. Resolva e execute novamente Para cada negocio retido, registre a decisao (divisao correta, aprovacao encontrada, atribuicao de representante) no CSV e execute novamente. Nunca altere o plano para fazer um numero parecer correto; se o plano for ambiguo, escreva a pergunta e mostre ambos os resultados (por exemplo, com `tier_method` fixo vs marginal). ### 5. Entregue Retorne a tabela de pagamento para aprovacao, um extrato por representante de `templates/commission-statement.md` com cada negocio, fatia de taxa, limite, estorno e linha de adiantamento, a lista de negocios retidos com a pergunta em aberto, e notas para a folha de pagamento (saldos negativos, saldos de adiantamento, valores adiados). ## Resultado de exemplo No exemplo, os pagamentos de outubro totalizam 9.500,00 EUR, com 3 negocios retidos. Ana Ruiz atinge 158,7% de sua cota de 60.000 (renovacao Delta Foods creditada a 50%), ganha 8.280,00 em camadas marginais mais 400,00 em SPIFFs de pagamento antecipado anual e e limitada ao maximo de 8.000,00. Ben Okafor ganha 690,00, mas o negocio Ironclad cancelado 55 dias apos o fechamento estorna 960,00, entao ele recebe 0 e carrega -270,00 adiante. Chloe Martin ganha 1.050,00, abaixo de seu adiantamento recuperavel de 1.500,00, entao o adiantamento complementa 450,00 e seu saldo sobe para 1.050,00. Retidos: Granite Works (divisao 50/40 = 90%), Nimbus Air (representante "dave" nao no plano) e Fjord Outdoor (desconto de 30%, limite 20%, sem aprovacao). ## Regras - Siga o plano assinado; quando o plano e os dados discordarem, retenha o negocio e pergunte - nunca adivinhe uma divisao, um representante ou uma aprovacao. - Mostre a aritmetica: cada pagamento deve ser rastreavel ao credito do negocio, fatias de camada e ajustes. - Aplique camadas em ordem de data de fechamento e diga se o plano e marginal ou fixo. - Trate estornos e saldos negativos com cuidado: declare o que o plano permite e aponte para RH/folha de pagamento e lei local antes de deduzir do pagamento. - Dados de comissao sao confidenciais: compartilhe com cada representante apenas seu proprio extrato. - Isto e uma ajuda de calculo, nao aconselhamento legal, fiscal ou de folha de pagamento.