Comissionamento

Cálculo de comissão de venda para canais que remuneram de formas diferentes: varejo físico, e-commerce, atacado, pessoa jurídica e operação em outro país. Cada canal tem sua regra, e todas precisam fechar com o financeiro.

O problema

Comissão é cálculo com consequência dos dois lados. Errar para menos e o vendedor reclama com razão; errar para mais e a empresa paga o que não devia. E precisa ser auditável, porque alguém vai perguntar por que aquele valor deu aquilo, meses depois.

O cálculo depende de venda, devolução, cancelamento, meta, hierarquia de equipe e regra de rateio. Esses dados vivem em sistemas diferentes e chegam em momentos diferentes, e parte deles retroage sobre comissão que já foi apurada.

Olhadas de longe, as regras dos cinco canais são a mesma coisa: percentual sobre venda, ajustado por devolução, distribuído por hierarquia. De perto elas divergem em tudo que importa — base de cálculo, momento de apuração, o que retroage, como o rateio trata equipe, e o que acontece quando a venda é cancelada depois do fechamento.

O que eu construí

• Motor de cálculo por canal, com a regra de cada modalidade isolada em vez de um cálculo único com ramificação para todos os casos
• Consolidação que reúne o resultado dos canais numa visão única para o financeiro
• Extração de nota fiscal como insumo do cálculo, reconciliando o que foi faturado com o que foi vendido
• Tratamento de evento posterior: devolução e cancelamento que retroagem sobre comissão já apurada
• Trilha de apuração, guardando não só o valor mas de onde ele veio, para responder à contestação

Decisões que eu defendo

Uma implementação por canal, não um cálculo parametrizado. A tentação óbvia é unificar, e entender por que ela não se aplica aqui foi o ponto da decisão. Em pagamentos, o que varia é quais etapas de uma sequência conhecida se aplicam, e isso cabe em configuração. Em comissão, o que varia é a fórmula, e parametrizar fórmula produz uma linguagem de programação mal disfarçada de configuração: o negócio não consegue mexer, o desenvolvedor mexe com medo, e ninguém tem teste. O raciocínio completo está em ADR 4 — Uma implementação por canal, não um motor parametrizado.

O custo aceito é duplicação real: corrigir um comportamento compartilhado exige aplicar em cinco lugares, com risco permanente de esquecer o quinto.

Como isso envelheceu

Melhor do que eu esperava, por uma razão que eu não tinha antecipado: rotatividade. O maior repositório da área passou por 29 autores diferentes ao longo do tempo, e código independente e legível sobreviveu a isso. Cada pessoa que chegou conseguiu alterar o canal de que precisava sem entender os outros quatro. Um motor genérico com essa quantidade de mãos teria virado código intocável.

Limite

A base comum ficou duplicada por tempo demais. Rateio proporcional, tratamento de resíduo de arredondamento e trilha de apuração são genuinamente iguais entre canais, e a decisão de não generalizar foi aplicada de forma larga demais no começo.

Ver também

ADR 4 — Uma implementação por canal, não um motor parametrizado · Backend .NET · Dados e persistência · Modelagem de domínio, DDD e CQRS