--- name: simulacao-custo-contratacao description: 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: 1. Pedir ao usuário a planilha/fonte de referência daquela modalidade, do mesmo jeito que a de CLT existiu. 2. 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. 3. 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".