portal_publico/.claude/skills/importacao-questor-plano-saude/SKILL.md

name

description

importacao-questor-plano-saude

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 <código> - <nome> (já somam mensalidade e coparticipação daquela pessoa) e Total Operadora <código> - <nome>. 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.