From 7642c600dac5f19a9add3dd9a2ee138d911232f5 Mon Sep 17 00:00:00 2001 From: Gabriel Date: Tue, 25 Aug 2026 09:32:29 -0300 Subject: [PATCH] =?UTF-8?q?Inclus=C3=A3o=20de=20skills?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../importacao-questor-plano-saude/SKILL.md | 110 ++++++++++++++++++ .claude/skills/indicador-desempenho/SKILL.md | 45 +++++++ .../simulacao-custo-contratacao/SKILL.md | 42 +++++++ 3 files changed, 197 insertions(+) create mode 100644 .claude/skills/importacao-questor-plano-saude/SKILL.md create mode 100644 .claude/skills/indicador-desempenho/SKILL.md create mode 100644 .claude/skills/simulacao-custo-contratacao/SKILL.md diff --git a/.claude/skills/importacao-questor-plano-saude/SKILL.md b/.claude/skills/importacao-questor-plano-saude/SKILL.md new file mode 100644 index 0000000..4c851da --- /dev/null +++ b/.claude/skills/importacao-questor-plano-saude/SKILL.md @@ -0,0 +1,110 @@ +--- +name: importacao-questor-plano-saude +description: Guia de manutenção/extensão da ferramenta "Importação de Plano de Saúde" do Portal De Paula (portal_api/planos_saude/, tela importacao-plano-saude.html). Nasceu como processo manual mensal só da TECNOMYL e hoje atende várias empresas/operadoras reais (9 parsers, 13 empresas com regra de custeio cadastrada). Documenta quais operadoras/empresas já estão parametrizadas e validadas com dado real, o que ainda falta pra TECNOMYL rodar 100% pela tela, e como adicionar uma operadora nova. Usar ao dar manutenção nos parsers, ao investigar uma divergência de valores numa importação, ou ao decidir se uma empresa/operadora nova pode ser cadastrada com segurança. +--- + +# Importação de Plano de Saúde: origem, migração e estado atual + +## 0. O que este documento é (e o que não é) + +Este SKILL.md documenta **o processo de negócio e sua migração** para dentro do Portal. É o complemento "por quê"/"cuidado com X" da documentação técnica, que já está exaustivamente descrita em `CLAUDE.md` (seção "Importação de Plano de Saúde (Utilitários)"). Antes de tocar em qualquer parser ou regra de custeio, ler os dois: `CLAUDE.md` pra arquitetura (models, endpoints, formato de `custeio_por_tipo`, "Regra empresa", "Vínculos de nome salvos"), este arquivo pra contexto de negócio e para a lista de pontos ainda não confirmados como equivalentes ao processo manual original. + +## 1. Origem: processo manual mensal da TECNOMYL + +Até a ferramenta existir, a importação de plano de saúde/odontológico da TECNOMYL (código Questor `1778`, operadoras AMIL/Unimed/Bradesco) era feita **à mão, todo mês**, com scripts Python ad-hoc (nunca versionados como projeto, só o protótipo em `Portal/projects/project/` ficou como referência) seguindo um runbook vivo por competência: `Plano de Saúde - TM\MM-AAAA\Memoria_Importacao_Questor.md` (fora deste repositório, só na máquina de quem processava). Esse runbook documenta, com exemplos numéricos reais validados com o cliente: + +- Extração AMIL (PDF ou XLSX) por CPF, tipos T/D/A (agregado sempre 100% descontado do empregado, nunca custeado pela empresa). +- Extração Unimed por nome mais teto de R$ 661,61/família (titular e dependentes). +- Extração Bradesco por nome, valores já individualizados por beneficiário. +- Cerca de 30 pares de nome divergente entre operadora e Questor, descobertos e confirmados um a um ao longo de várias competências. +- Checklist de validação e um método de auditoria pós-importação comparando com o relatório `Plano de Saúde - Lançamentos` exportado do próprio Questor. + +**Esse runbook por competência continua existindo e sendo o mais atualizado sobre a TECNOMYL especificamente.** Quem for decidir se pode aposentar o processo manual pra essa empresa deve ler a competência mais recente dele antes de qualquer coisa, não só este SKILL.md (que é sobre o processo em geral, não uma cópia congelada dos números de uma competência). + +## 2. O que foi migrado para o Portal (`portal_api/planos_saude/`) + +A ferramenta hoje é **genérica multi-empresa/multi-operadora** (não é "o robô da TECNOMYL"). TECNOMYL é só mais um `codigo_empresa` (`1778`) entre várias empresas que passam pela mesma tela. O pipeline, os parsers por operadora, o formato de custeio configurável e as regras gerais (nunca aproximar nome automaticamente, valor negativo nunca vai pro CSV final, um mesmo beneficiário pode aparecer em várias linhas/rubricas e precisa ser somado) estão descritos em detalhe no `CLAUDE.md`, não repetir aqui. + +Confirmado hoje (rodada em que este documento foi atualizado) que já refletem regras específicas validadas com a TECNOMYL: + +- **Teto Unimed de R$ 661,61/família**: migrado como `regra_empresa: unimed_1778_tecnomyl` (`portal_api/planos_saude/regras_empresa.py`), com prioridade dependente primeiro e titular absorve o residual, validado contra o mesmo exemplo do runbook original (Antonio Eduardo Petroni: 361,01 de mensalidade, 224,09 de empresa, 136,92 de desconto). +- **Cadastro de Regras por empresa+operadora** (`RegraCusteioPlanoSaude`): substitui a decisão manual "quem paga o quê" por combinação, configurar uma vez e reaproveitar todo mês. +- **Vínculos de nome salvos (DE/PARA)** (`VinculoNomeOperadora`): substitui a tabela de equivalência estática do runbook por um mecanismo que aprende. Confirmar manualmente uma vez ("Vincular pessoa") e o sistema reaplica sozinho nas competências seguintes. As cerca de 30 equivalências já conhecidas da TECNOMYL (seção 5 do runbook) **não foram pré-carregadas no banco**. Na prática, a primeira competência da TECNOMYL rodada pela tela vai gerar auditoria pra cada uma delas de novo, até serem confirmadas uma vez cada. + +## 3. Operadoras e empresas já parametrizadas hoje (fotografia do banco em 25/08/2026) + +A ferramenta deixou de ser "a automação da TECNOMYL", hoje atende várias empresas/operadoras reais. Os números abaixo vieram de consultar o banco de produção direto (`RegraCusteioPlanoSaude`/`ImportacaoPlanoSaude`) na rodada em que este documento foi escrito. **É uma fotografia, não um fato permanente**: cresce todo mês, reconsultar antes de confiar nela pra uma decisão importante (`python manage.py shell`, os dois models citados). + +### 3.1 Os 9 parsers de operadora existentes: uso real até agora + +| Operadora (`pipeline.OPERADORAS`) | Casamento | Importações no banco | Alguma concluída? | +|---|---|---|---| +| `unimed_saude` (5060, CSV ou 2 PDFs) | nome (mensalidade), CPF (coparticipação em PDF) | 8 | Sim (empresas 1123, 221, mais testes antigos) | +| `itamed_saude` (3755) | nome | 11 | Sim (221, 197, 1684, 626) | +| `dental_uni_odonto_mensalidade` (Dental Uni) | nome | 2 | **Não**, as 2 existentes estão em "revisão" | +| `unimed_oeste_pr_saude` (4709) | nome | 3 | Sim, mas de uma execução **anterior** à empresa 1601 hoje cadastrada (a de 1601 está em revisão) | +| `bradesco_saude` (1386) | nome | 1 | Sim (empresa 221) | +| `bradesco_dental_odonto_mensalidade` (3759) | nome | 1 | Sim (empresa 1684). **Ver ressalva abaixo** | +| `unimed_vitoria_saude` (4750) | nome | 1 | Sim (empresa 792) | +| `sulamerica_odonto_mensalidade` (4726) | CPF | 1 | Sim (empresa 792) | +| `amil_odonto_mensalidade` (898) | CPF | **0** | Nunca foi rodada nem uma vez dentro da ferramenta | + +**Ressalva sobre a Bradesco Dental (3759):** o `CLAUDE.md` registra que este parser foi escrito só a partir de texto colado numa conversa, nunca confirmado contra o arquivo real. O banco, porém, já tem uma importação **concluída** pra esse operador (empresa 1684), ou seja, alguém rodou um arquivo real depois daquela ressalva ser escrita. "Concluída" só significa que o pipeline processou sem erro e o CSV foi gerado, **não** que os valores foram de fato conferidos linha a linha contra a fatura. Antes de remover a ressalva do `CLAUDE.md`, confirmar com o usuário se essa conferência manual aconteceu. + +**AMIL nunca foi usada de verdade na ferramenta.** O parser existe, é o mesmo código portado do protótipo original, mas nenhuma empresa (TECNOMYL inclusive) passou um arquivo AMIL pela tela ainda. É o operador com menos garantia real de estar 100% certo hoje, mesmo sendo o mais simples dos 9. + +### 3.2 Empresas com "Cadastro de Regras" salvo (13 empresas, 17 combinações empresa+operadora) + +| Cód. empresa | Razão social | Operadora(s) cadastrada(s) | +|---|---|---| +| 92 | PRESCINOTTI & CIA LTDA. | Unimed | +| 129 | SOCIEDADE CIVIL NOSSA SENHORA APARECIDA | Unimed | +| 197 | ENTREGA COMÉRCIO DE MÓVEIS LTDA - EPP | Itamed | +| **221** | ROSSONI, PIOTTO & CIA LTDA | Bradesco Saúde, Unimed e Itamed (**3 operadoras, todas com importação concluída**, melhor empresa de referência hoje pra testar qualquer mudança no pipeline) | +| 626 | MTI SERVIÇOS E COMÉRCIO EXTERIOR LTDA | Itamed | +| 792 | WEITNAUER BRASIL IMPORTADORA E EXPORTADORA DE PERFUMES E COSMÉTICOS LTDA | SulAmérica Odonto e Unimed Vitória | +| 1006 | COPYVIC LOCAÇÃO DE EQUIPAMENTOS LTDA | Itamed | +| 1084 | LUSIA DALA ROSA VOLPATO LTDA | Dental Uni | +| 1123 | VÍDEO UP COMUNICAÇÃO LTDA | Unimed | +| 1601 | LABORATÓRIO DE ANÁLISES CLÍNICAS OSWALDO CRUZ DE MEDIANEIRA LTDA | Unimed Oeste do Paraná | +| 1604 | T & F JOALHEIROS E ACESSÓRIOS LTDA - ME | Itamed | +| 1684 | FRT CONSOLIDADORA LTDA | Itamed e Bradesco Dental | +| 2028 | LAS WINE BAR LTDA | Dental Uni | + +**TECNOMYL (1778) não está nesta lista, não tem nenhuma `RegraCusteioPlanoSaude` cadastrada hoje**, nem pra Unimed, nem AMIL, nem Bradesco. Existe um único registro de importação histórico pra ela na tabela `ImportacaoPlanoSaude` (Unimed, com `regra_empresa=unimed_1778_tecnomyl` já setado), mas ficou em status **"revisão"**, nunca chegou a gerar o CSV, e é de antes da separação do "Cadastro de Regras" (não tem `regra_custeio_salva` vinculada). Não apareceria hoje no fluxo atual de "Nova Importação" sem primeiro cadastrar a regra pela tela "Cadastro de Regras". Isto confirma, com dado real, o que a seção 4 abaixo já levanta como suspeita: **a migração da TECNOMYL nunca foi finalizada de ponta a ponta dentro da ferramenta**, nem para a Unimed (que já tem o algoritmo de teto pronto no código). + +## 4. Pontos NÃO confirmados como equivalentes (verificar antes de confiar na tela pra TECNOMYL) + +Isto é o motivo mais provável pelo qual a TECNOMYL específica ainda pode estar rodando pelo processo manual, mesmo com a ferramenta existindo: as regras abaixo são regras de negócio reais, validadas com o cliente no processo manual, e **não têm evidência de estarem implementadas na ferramenta genérica** (verificado lendo o código dos parsers na rodada em que este documento foi escrito): + +1. **AMIL, tipo "A" (agregado) vs. "D" (dependente direto):** o parser genérico (`operadoras/amil/odonto_mensalidade.py`) extrai o tipo (`T`/`D`/`A`), mas o resto do pipeline trata `D` e `A` como o mesmo "dependente" pra efeito de custeio (`matcher._regra_para_pessoa`, ver `CLAUDE.md`). A regra da TECNOMYL exige que **todo tipo A seja 100% descontado do empregado, independente da regra configurada para dependente** (que pra TECNOMYL costuma custear D pela empresa). Rodar a TECNOMYL pela tela sem resolver isso faria um agregado ser custeado pela empresa por engano. +2. **Bradesco, dependente sem linha no modelo do Questor:** regra manual, acumular o valor desse dependente na linha do **titular** (não é regra geral do leiaute, é específica). O `matcher.py` genérico, na ausência dessa regra, deve estar tratando esse caso como "sem cadastro", indo pra auditoria (comportamento padrão do resto do sistema), o que é uma saída **segura** (não lança valor errado, só some do CSV até alguém resolver), mas não é o mesmo resultado do processo manual. +3. **Auditoria pós-importação contra o relatório do Questor** (`Plano de Saúde - Lançamentos - Competência MM/AAAA`): não existe essa feature na ferramenta. Ver seção 6 abaixo pra reproduzir esse método manualmente, se for pedido. +4. **Sistema Contabit** (seção 10 do runbook, formato alternativo de rubricas 338/200/201): fora do escopo da ferramenta, que só gera o leiaute do Questor. + +Nenhum desses é motivo pra não usar a ferramenta, são pontos que **quem for migrar a TECNOMYL de vez pra tela precisa resolver primeiro** (ou confirmar que já deixaram de ser relevantes, ex.: se a TECNOMYL não tiver mais nenhum beneficiário tipo A). Até resolver, mais seguro tratar qualquer resultado da tela pra TECNOMYL como "conferir manualmente contra o runbook" antes de subir ao Questor, em vez de confiar de olhos fechados. + +## 5. Como adicionar/ajustar um parser de operadora + +Ver `CLAUDE.md` (tabela de operadoras registradas, `OperadoraParser.extrai()`, `pipeline.OPERADORAS`) para o mecanismo técnico. Regras de negócio que **nunca devem ser reinterpretadas** sem confirmar de novo com o usuário, válidas pra qualquer operadora nova: + +- Nome divergente nunca é resolvido por aproximação automática (fuzzy match). Sempre confirmação humana explícita, mesmo que pareça óbvio. +- Nenhum valor negativo entra no CSV final, vira auditoria, nunca é zerado/truncado silenciosamente. +- Um mesmo beneficiário pode gerar várias linhas/rubricas no arquivo da operadora (mensalidade mais retroativo, por exemplo). Sempre somar por indivíduo antes de decidir o valor final, nunca tratar cada linha isoladamente. +- PDF sem texto selecionável precisa de OCR (`docling`), não `pdfplumber`. Testar `page.chars`/`extract_text()` contra o arquivo real antes de escolher qual usar (ver nota em `operadoras/bradesco/saude.py`). +- Todo parser novo em PDF só deve ser considerado confiável depois de rodado contra o arquivo real (nunca só a partir de texto colado numa conversa). Ver [[feedback_pdf_parser_precisa_arquivo_real]]. + +## 6. Auditoria pós-importação contra o relatório do Questor (ainda manual) + +Se for pedido pra conferir se o que foi gerado bateu com o que ficou lançado no Questor, e a pessoa tiver em mãos o PDF `Plano de Saúde - Lançamentos - Competência MM/AAAA` exportado do próprio sistema: + +1. Extrair o texto do PDF (`pdfplumber`) e parsear por bloco de funcionário: linhas `Total Titular`/`Total Dependente - ` (já somam mensalidade e coparticipação daquela pessoa) e `Total Operadora - `. A linha `Total Operadora` só aparece **depois** dos totais daquele bloco, não antes (bufferizar e atribuir a operadora só quando essa linha aparecer). +2. Recompor o valor esperado por pessoa somando os CSVs de mensalidade e coparticipação já gerados. +3. Cruzar por **nome exato** (os nomes do PDF vêm do próprio Questor, sem precisar de tabela de equivalência aqui, diferente do cruzamento com o arquivo da operadora). +4. Pessoa com `VALOREMPRESA=0` e `VALOR=0` pode não gerar lançamento nenhum no sistema, não é divergência. +5. Confirmar que ninguém da lista de pendências/auditoria aparece lançado no sistema. +6. A linha `Total Empresa` no fim do PDF é o total geral de todas as operadoras, serve de conferência rápida contra a soma dos CSVs antes de entrar no detalhe pessoa a pessoa. + +## 7. Onde está o histórico real de competências já processadas + +Fora deste repositório, só na máquina de quem processa hoje: `Plano de Saúde - TM\MM-AAAA\` (por competência: `Memoria_Importacao_Questor.md`, os CSVs gerados, `Faltantes_Questor_MM_AAAA.xlsx`, `Auditoria_Importacao_Questor_MM_AAAA.xlsx`). **Isso é uma limitação real pro objetivo de "qualquer contribuidor consegue dar andamento sem precisar desta máquina"**, nada neste SKILL.md substitui esse runbook, só resume o que ele documenta de mais estável. Se for necessário que outra pessoa continue esse processo (manual ou via tela) sem acesso a esta máquina, os arquivos dessa pasta precisam ser trazidos para algum lugar compartilhado (git ou outro), decisão que envolve dados de funcionários reais (nomes, valores), então não fazer isso sem o usuário confirmar onde/como. diff --git a/.claude/skills/indicador-desempenho/SKILL.md b/.claude/skills/indicador-desempenho/SKILL.md new file mode 100644 index 0000000..4eae22d --- /dev/null +++ b/.claude/skills/indicador-desempenho/SKILL.md @@ -0,0 +1,45 @@ +--- +name: indicador-desempenho +description: Guia de manutenção/extensão da ferramenta "Indicador de Desempenho" do Portal De Paula (Geradoc, portal_api/indicadores/, tela indicador-desempenho.html). Documenta o que ela substitui (apuração manual em planilha .ods do Fiscontábil), por que o escopo hoje é só esse departamento, e a limitação conhecida de resolução por gerente ao expandir pra outros departamentos. Usar ao investigar um valor de apuração, ao dar manutenção nos critérios/percentuais, ou ao planejar a expansão pra outro departamento além do Fisco/Contábil. +--- + +# Indicador de Desempenho: origem, escopo e limitações conhecidas + +## 0. O que este documento é + +Complemento de contexto de negócio pro `CLAUDE.md` (seção "Indicador de Desempenho (Geradoc)"), que já documenta a arquitetura técnica em detalhe (8 models, fórmula de composição, endpoints de ajuste em lote, layout do recibo em PDF). Ler os dois antes de mexer em cálculo de percentual ou em departamento, este arquivo foca no "por quê" e nas limitações que ainda não têm solução. + +## 1. Origem: apuração manual em planilha quebrada + +A ferramenta substitui a apuração mensal do indicador de desempenho do Fiscontábil (departamentos Contábil/Fiscal do escritório), antes feita numa planilha `.ods` com fórmulas quebradas por anos de edição manual acumulada. O material de origem está versionado no próprio repositório, em `Portal/projects/Indicadores/`: + +- `FISCO CONTABIL 0726 OK.ods`: a planilha antiga (última versão "OK" antes da migração), fonte dos primeiros percentuais/critérios semeados via `seed_indicador_desempenho`. +- `Honorários Por Cliente.xlsx` e `Serviços Tareffa.xlsx`: os dois relatórios que o RH sobe todo mês na tela ("Nova Apuração"), mesmo formato desde então. +- `Modelo de Recibo.pdf`: referência visual original do recibo entregue a cada colaborador. `indicadores/recibo.py` reproduz o mesmo formato em `reportlab`. + +Se um valor calculado pela ferramenta parecer estranho pra uma competência antiga, comparar contra a planilha `.ods` antes de assumir que é bug, mas lembrar que a planilha tinha fórmulas comprovadamente quebradas, então "diferente da planilha" não é automaticamente "a ferramenta está errada". + +## 2. Escopo v1: só Fisco/Contábil, mas a estrutura já é multi-departamento + +Só o Fisco/Contábil (papéis Balancete/Liberação Fiscal/Conciliação Financeira) tem critérios e percentuais cadastrados hoje, mas o modelo de dados (`IndicadorDepartamento`, `IndicadorDepartamentoGerente`, critérios/percentuais com FK pra departamento) já foi desenhado pra suportar outros departamentos desde a rodada em que isso foi introduzido, não é uma limitação de schema. Adicionar um departamento novo é: cadastrar o `IndicadorDepartamento` (Configurações → Departamentos), mapear os gerentes dele (`IndicadorDepartamentoGerente`), e cadastrar os critérios/percentuais próprios daquele departamento (RH decide os valores, não é herdado do Fisco/Contábil). + +## 3. Limitação conhecida e sem solução hoje: resolução de departamento por gerente + +`IndicadorApuracaoColaborador.departamento` é resolvido **pelo gerente do colaborador** (`departamentos.carrega_mapa_gerentes()`, `{nome_gerente: departamento_id}`), não pelo colaborador individualmente. Isso quebra quando **um mesmo gerente supervisiona pessoas de departamentos diferentes**: caso real já confirmado com dados reais, "Elizangela de Paula Kuhn" supervisiona diretamente os líderes do Fisco/Contábil **e** Luciane Gonzaga, que deveria cair no departamento "Rocket". Como todos compartilham o mesmo gerente, mapear Elizangela para "Gerentes" classifica Luciane como "Gerentes" também, errado. + +Não existe mais um mecanismo de exceção por colaborador individual, o antigo `IndicadorSetorApelido` cobria exatamente esse tipo de caso e foi removido na migração pra departamentos (`0033` a `0035`). **Antes de expandir a ferramenta pra um segundo departamento de verdade**, decidir como resolver isso. As opções mais óbvias são: (a) reintroduzir uma exceção por nome de colaborador por cima da relação gerente/departamento, ou (b) resolver departamento por outro campo já existente na planilha Tareffa (se houver um mais granular que "gerente"). Não presumir qual das duas o usuário prefere sem perguntar, é uma decisão de produto, não só técnica. + +## 4. Percentuais/critérios são cadastro editável, nunca hardcoded + +O primeiro histórico (`seed_indicador_desempenho`, idempotente) foi populado com os valores exatos da planilha antiga, mas com `vigente_desde` fixado em **01/01/2024 por falta de data documentada** na planilha de origem. Se o usuário informar a data real em que essas regras passaram a valer, corrigir esse seed (ou os registros já criados no banco, se o seed já rodou em produção) em vez de deixar a data placeholder implícita como se fosse a data real. + +## 5. Robustez: bugs reais encontrados testando com dados de produção (43 colaboradores) + +Duas armadilhas já mordidas uma vez, que valem a pena verificar de novo em qualquer parser/campo novo desta ferramenta: + +- `openpyxl.load_workbook(..., read_only=True)` precisa de `.close()` explícito (`indicadores/leiaute.py`). Sem isso, o Windows mantém o arquivo de upload memory-mapped e bloqueia excluir a apuração depois (erro só aparece na hora de excluir, não na hora de processar, fácil de não notar em teste rápido). +- Todo `DecimalField` que representa "um percentual de 0 a 100" precisa de `max_digits >= decimal_places + 3`, não `+ 2`. O valor exato `100` não cabe senão (`DataError: numeric field overflow`), erro que só aparece quando um colaborador de fato bate 100% em algum critério, não em qualquer teste com valores fracionários. + +## 6. Correção deliberada no recibo: o banner sempre mostra o percentual medido, nunca o pago + +Quando `pct_individual` é ajustado manualmente pela Diretoria/RH (ex.: forçado para 100%), o banner "PERCENTUAL DO INDICADOR INDIVIDUAL" do PDF continua mostrando o percentual **efetivo/medido** (recalculado na hora via `composicao_individual()`), não o valor pago. Decisão explícita do usuário, pra o colaborador sempre ver o que de fato atingiu, com uma linha de detalhe separada mostrando o valor ajustado ao lado. Não "simplificar" isso pra mostrar só `pct_individual` puro no banner, perderia essa distinção intencional entre medido e pago. diff --git a/.claude/skills/simulacao-custo-contratacao/SKILL.md b/.claude/skills/simulacao-custo-contratacao/SKILL.md new file mode 100644 index 0000000..9578140 --- /dev/null +++ b/.claude/skills/simulacao-custo-contratacao/SKILL.md @@ -0,0 +1,42 @@ +--- +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".