5.8 KiB
| name | description |
|---|---|
| simulacao-custo-contratacao | Guia de manutenção/extensão da ferramenta "Simulação de Custo de Contratação" do Portal De Paula (Geradoc, portal_api/custo_contratacao/, tela custo-contratacao.html). Documenta o que ela substitui (planilha manual de custo de empregado CLT), por que o escopo hoje é só uma modalidade, e o que verificar antes de adicionar as demais. Usar ao ajustar as tabelas fiscais, ao investigar um valor calculado, ou ao avaliar se já é seguro implementar Simples Nacional/Regime Normal/Pró-labore/Empregado Doméstico. |
Simulação de Custo de Contratação: origem, escopo e extensão
0. O que este documento é
Complemento de contexto de negócio pro CLAUDE.md (seção "Simulação de Custo de Contratação (Geradoc)"), que já documenta a arquitetura técnica em detalhe (models, endpoints, ParametroFiscalCustoContratacao, fluxo de PDF). Ler os dois antes de alterar cálculo fiscal, este arquivo foca no "por quê" e no que falta.
1. Origem: planilha manual de custo de contratação
A ferramenta substitui uma planilha Excel usada pelo contador pra calcular manualmente quanto custa contratar um Empregado CLT com um determinado salário. O arquivo de referência que validou a fórmula está versionado no próprio repositório: Portal/projects/planilha de custo/1972 - CUSTO EMPREGADO SALÁRIO (8.500,00).xlsx (diferente da skill de Plano de Saúde, aqui a fonte histórica já está dentro do git, então qualquer contribuidor tem acesso). Esse arquivo é a referência de conferência pra qualquer mudança futura na fórmula: se um valor calculado pela tela parecer errado, reproduzir o mesmo salário na planilha e comparar campo a campo antes de assumir que é bug do código.
2. Escopo v1: por que só Empregado CLT
O pedido original do usuário mencionava 5 modalidades (Simples Nacional, Regime Normal, Pró-labore, Empregado CLT, Empregado Doméstico), mas só existia uma planilha de referência validada com o contador, a de Empregado CLT. As outras 4 não foram implementadas "seguindo o mesmo padrão" por decisão explícita: não inventar a fórmula de uma modalidade sem uma fonte equivalente confirmada (planilha real validada, ou confirmação explícita do contador sobre a regra). Antes de implementar qualquer uma das 4 modalidades faltantes:
- Pedir ao usuário a planilha/fonte de referência daquela modalidade, do mesmo jeito que a de CLT existiu.
- Validar a fórmula rodando pelo menos um caso conhecido da planilha e comparando com o resultado da nova implementação, antes de considerar pronta.
- Seguir o mesmo padrão de
ParametrosFiscais/ParametroFiscalCustoContratacao(tabelas editáveis pelo banco, não hardcoded), sem hardcodear números fiscais de novo.
3. Correção deliberada em relação à planilha original
A planilha original nunca somava a dedução por dependente (R$ 189,59/dependente) à base do IRRF quando o cálculo usava o desconto real de INSS, só quando usava o desconto simplificado (que por lei substitui os dois). Isso foi identificado como um gap real da planilha (não uma regra fiscal intencional), confirmado com o usuário e corrigido: portal_api/custo_contratacao/calculo.py agora soma a dedução por dependente também no caminho de desconto real de INSS. Se algum dia o valor calculado pela ferramenta divergir da planilha antiga nesse cenário específico (funcionário com dependentes mais desconto real de INSS), a ferramenta está certa, a planilha estava errada. Não "corrigir" a ferramenta pra bater com a planilha nesse caso sem reconfirmar com o contador.
4. Redução de IRRF da Lei nº 15.270/2025, vigente desde jan/2026
Isenção total até R$ 5.000 de rendimento bruto mensal, redução decrescente até zerar em R$ 7.350 (redução = max(0, coeficiente_a − coeficiente_b × rendimento_bruto), aplicada por cima do imposto da tabela progressiva tradicional, nunca deixando o imposto final negativo). Os coeficientes A/B e o limite de rendimento são parâmetros editáveis em ParametroFiscalCustoContratacao, não hardcoded. Se a lei for alterada/atualizada no futuro (ou revogada), ajustar pelo painel da própria tela, não no código, a menos que a fórmula em si mude (não só os valores).
5. Tabelas fiscais (INSS/IRRF): atualização anual
ParametroFiscalCustoContratacao é um singleton (pk=1, criado sob demanda) com as faixas de INSS/IRRF em JSONField, editável por GET/PATCH /api/parametros-fiscais-custo-contratacao/ (painel colapsável na própria tela, mesma permissão da simulação). custo_contratacao/tabelas.py só fornece o valor padrão da primeira criação, nunca é lido de novo depois disso. Quando o governo publicar novas faixas de INSS/IRRF (normalmente todo início de ano), a atualização correta é pela tela (ou por uma migração de dados, se for preferível ter isso versionado). Não editar tabelas.py esperando efeito em produção, já que o banco só lê aquele arquivo uma vez.
6. PDF gerado: identidade visual é a do escritório, não a do Portal
O cabeçalho do PDF usa logo-branco.png (identidade "De Paula Contadores", dourado/marrom) sobre um banner marrom escuro, nunca a marca "P.I.D." do Portal, porque o documento é entregue ao cliente como se o próprio escritório o tivesse gerado. Ver feedback_logos_documentos_vs_portal na memória antes de qualquer mudança visual nesse PDF.
7. Sem persistência: cada simulação é um cálculo pontual
POST /api/simulacao-custo-contratacao/gerar/ recebe os dados do formulário, calcula e devolve o PDF direto na resposta. Nada é salvo no banco. Isso é intencional (diferente do padrão "com histórico" de Importação de Plano de Saúde/Indicador de Desempenho). Se um dia for pedido histórico de simulações, é uma mudança de escopo deliberada, não um bug de "esqueceram de salvar".