portal_publico/portal_api/custo_contratacao/CLAUDE.md

Simulação de Custo de Contratação (Geradoc)

Movido do CLAUDE.md da raiz em 2026-08-26 para reduzir conflito de edição entre aplicações (documentação por app, código continua no mesmo lugar). Ver CLAUDE.md na raiz para arquitetura geral/transversal do Portal (modelo de permissões, API, CSS, etc.) — este arquivo é carregado automaticamente ao trabalhar dentro de portal_api/custo_contratacao/. Ver também a skill simulacao-custo-contratacao (.claude/skills/) para contexto de negócio (por quê, limitações conhecidas).

Ferramenta que substitui a planilha manual de custo de contratação (projects/planilha de custo/*.xlsx) por um formulário no Portal — calcula o custo de contratar um Empregado CLT e devolve um PDF pronto pra enviar ao cliente. Permissão de toggle único (apps["simulacao-custo-contratacao"] em permissoes["geradoc"], sem par visualizar/editar), checada manualmente (request.user.permissao_app("geradoc", "simulacao-custo-contratacao")) nas duas views (não são ModelViewSet — são funções simples, POST /api/simulacao-custo-contratacao/gerar/ e GET/PATCH /api/parametros-fiscais-custo-contratacao/).

• Escopo v1: só Empregado CLT. O pedido original mencionava 5 modalidades (Simples Nacional, Regime Normal, Pró-labore, Empregado, Empregado Doméstico), mas só havia planilha de referência validada pra Empregado CLT — as outras 4 ficam para quando houver uma fonte de regras equivalente confirmada pelo contador; não implementar "seguindo o mesmo padrão" por conta própria.
• Sem persistência: POST /api/simulacao-custo-contratacao/gerar/ é um cálculo pontual — recebe os dados do formulário, calcula (custo_contratacao.calculo.calcula_custo_empregado) e devolve o PDF direto (HttpResponse binário, Content-Disposition: inline), nada é salvo no banco. Diferente do padrão "com histórico" de ImportacaoPlanoSaude/IndicadorApuracao.
• Tabelas de INSS/IRRF editáveis pelo banco: ParametroFiscalCustoContratacao (models.py) é um singleton (atual(), sempre pk=1, criado sob demanda via get_or_create) com faixas_inss/faixas_irrf em JSONField (lista de {limite_superior, aliquota, deduzir}) + escalares (teto de desconto de INSS, alíquota/dedução do IRRF acima da última faixa, desconto simplificado do IRRF, dedução por dependente, e os 3 parâmetros da redução da Lei 15.270/2025 — coeficientes A/B e limite de rendimento bruto), editáveis pelo painel colapsável da própria tela (GET/PATCH /api/parametros-fiscais-custo-contratacao/, mesma permissão de quem usa a simulação). custo_contratacao/tabelas.py continua existindo só como seed/default da primeira criação da linha (_faixas_inss_padrao/_faixas_irrf_padrao em models.py) — calculo.py nunca lê tabelas.py direto, sempre recebe um ParametrosFiscais (dataclass pura, sem ORM) montado por ParametroFiscalCustoContratacao.para_calculo().
• Redução de IRRF da Lei nº 15.270/2025 (art. 3º-A da Lei 9.250/1995, 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 já calculado pela tabela progressiva tradicional (que a lei não alterou), nunca deixando o imposto final negativo.
• Correção deliberada em relação à planilha original: a planilha nunca somava a dedução por dependente (R$189,59/dependente) à base do IRRF quando usava o desconto real de INSS — só quando usava o desconto simplificado (que por lei substitui os dois). Confirmado como gap com o usuário e corrigido: ao usar o desconto real de INSS, a dedução por dependente também é subtraída agora (custo_contratacao/calculo.py).
• PDF via reportlab (pure-Python, sem dependência nativa problemática no Windows) — cabeçalho é um banner marrom escuro com logo-branco.png + "De Paula Contadores", nas cores reais da marca (dourado #D3AF4D, marrom #4A3C28, amostradas do próprio logo.png), não o roxo do tema de interface do Portal.
• Localização no menu (dentro de Geradoc, ao lado de "Gerar Contrato"/"Gerar Procuração") foi escolha explícita do usuário, não Utilitários.

API

Endpoint	Método	Uso
/api/simulacao-custo-contratacao/gerar/	POST	calcula (portal_api.custo_contratacao.calculo.calcula_custo_empregado) e devolve o PDF direto na resposta (application/pdf, sem persistir nada); PermissaoApp-like check manual via permissao_app("geradoc", "simulacao-custo-contratacao")
/api/parametros-fiscais-custo-contratacao/	GET/PATCH	tabelas de INSS/IRRF + parâmetros da Lei 15.270/2025 usados pela simulação (ParametroFiscalCustoContratacao, singleton pk=1); mesma permissão da simulação, sem par visualizar/editar dedicado

Estes endpoints moravam na tabela de API do CLAUDE.md da raiz e foram trazidos para cá: endpoint de aplicação mora na doc da aplicação. A raiz mantém só os transversais (auth, /api/me/, catálogo, perfis, usuários, favoritos, widgets, compromissos, notificações).