Skip to content

@fc/calculos-rgps ​

Biblioteca de domínio do RGPS — Regime Geral de Previdência Social usada pelas apps prev-tc, prev-rvt, prev-atrasados, prev-api e rmi-api.

Estende @fc/calculos-previdenciarios, que guarda o que o RGPS e o RPPS têm em comum — período, segurado, histórico, dados do cálculo, contrato de requisito e aritmética de tempo. Aqui fica o que é do regime geral: RMI, atrasados, evolução de benefício, fator previdenciário, qualidade de segurado, os requisitos do RGPS e a leitura dos documentos do INSS.

Ela concentra:

  1. contagem de tempo e carência
  2. análise de elegibilidade a benefícios
  3. cálculo de RMI e Revisão da Vida Toda
  4. evolução de benefícios
  5. cálculo de atrasados judiciais

Este README prioriza:

  • contrato real do código
  • fluxos reais de uso nas apps
  • pontos de mutação e efeitos colaterais
  • onde adicionar novas regras sem quebrar regras antigas

Catálogo de tempo especial ​

@fc/calculos-rgps/tempo-especial/* publica o catálogo de enquadramentos e a pesquisa pura por código ou texto, com filtros por decreto e tipo, sinônimos e correção aproximada. É a fonte única de prev-utils (busca local/offline) e prev-api (consulta REST paginada). Apresentação e cópia permanecem na app web; validação HTTP, paginação e projeção pública ficam na API.

Os dados tipados dos seis catálogos, as fontes e os textos normativos são preservados sem revisão de conteúdo. A ordenação estável preserva a posição original nos empates. IDs identificam entradas desta revisão do catálogo, sem promessa de permanência entre revisões.

Índice ​


Visão geral ​

O pacote implementa regras previdenciárias cujo comportamento varia por:

  • espécie de benefício
  • tipo de segurado
  • marcos legislativos
  • data de apuração
  • composição do histórico contributivo

A arquitetura reflete isso:

flowchart TD
  A["parametros / entidades"] --> B["requisitos / calculo-tc"]
  B --> C[analise-beneficios]
  C --> D[calculo-rmi]
  D --> E[evolucao-beneficio]
  E --> F[calculo-atrasados]

Há também módulos horizontais de suporte:

  • persistencia
  • documentos — tudo o que existe por causa de documento importado, em quatro estágios: documentos/plugins/<documento>/ (um plugin de leitura por documento; tipos.ts na raiz de documentos/ guarda os DTOs que eles produzem), documentos/segmentacao/ (isolamento de exemplares em PDFs com mais de um documento e ReferenciaExemplarDocumento), documentos/importacao/ (TipoDocumentoPrevidenciario, registroDocumentosPrevidenciarios entregue ao importador genérico de @fc/parsers, mapearTipoSegmentado, atualizarReferenciasDocumentais, prepararImportacaoPrevjud) e documentos/filtros/ (filtros de períodos e salários importados antes de entrarem no cálculo)
  • qualidade-segurado
  • segurado
  • utilidades-apis

O diretório documentos/plugins concentra os plugins RGPS (antes hospedados no antigo @fc/analisador-de-texto), incluindo:

  • CNIS
  • carta de concessão
  • RDCTC
  • formulário PJe
  • HISCRE
  • PDF Fábrica
  • planilha Google
  • plenus
  • processo
  • sibe-conbas
  • sibe-hiscal
  • tempo de contribuição

Superfície pública do pacote ​

Como consumir ​

O pacote não tem barrel: nem src/index.ts de raiz nem index.ts de pasta. Cada módulo é publicado pelo subpath do arquivo que o declara, e o consumidor importa exatamente o que usa:

ts
import type { ArquivoTc } from '@fc/calculos-rgps/persistencia/tc/tipos'
import { AnaliseBeneficiosRgps } from '@fc/calculos-rgps/analise-beneficios/AnaliseBeneficiosRgps'
import { DadosCalculoRgps } from '@fc/calculos-rgps/entidades/DadosCalculoRgps'
import { EspecieBeneficio } from '@fc/calculos-rgps/parametros/especie-beneficio/EspecieBeneficio'
import { PluginCnisCompleto } from '@fc/calculos-rgps/documentos/plugins/cnis/PluginCnisCompleto'
import { lerArquivoTc } from '@fc/calculos-rgps/utilidades-apis/tempo/conversor-arquivo/lerArquivoTc'

O import pela raiz (from '@fc/calculos-rgps') não resolve e é barrado pela cerca fc/cerca-pacotes-sem-barrel-raiz do @fc/eslint-config. Os plugins do analisador vivem um por arquivo (documentos/plugins/<documento>/Plugin<Nome>.ts; os leitores de CNIS têm a lista única documentos/plugins/pluginsCnis), e as cadeias de migradores são persistencia/tc/migradoresTc e persistencia/atrasados/migradoresAtrasados. O teste tests/arquitetura/sem-barrels.spec.ts tranca a ausência de index.ts.

O que o package.json expõe ​

O export map de package.json publica cada pasta de src/ por wildcard — @fc/calculos-rgps/<pasta>/* para analise-beneficios, calculadoras, calculo-atrasados, calculo-rmi, demonstrativos, baixa-renda-reclusao, calculo-tc, entidades, evolucao-beneficio, quadro-resumo, simulacao-por-totais, documentos (com documentos/plugins/*, documentos/segmentacao/*, documentos/importacao/* e documentos/filtros/* pelo mesmo wildcard), parametros, persistencia, qualidade-segurado, requisitos e utilidades-apis — mais os subpaths de apoio a teste:

  • @fc/calculos-rgps/testes/paridade-calc/*, suporte de teste para as apps previdenciárias (alinharResultados, caminhos, compararResultadosIntegral…)
  • @fc/calculos-rgps/testes/prevjud, builders compartilhados de cenários PrevJud

src/segurado/ segue privado (nunca esteve no barrel). O wildcard alcança também arquivos que o barrel escondia — helpers internos —, que continuam fora do contrato: ver "O que não deve ser tratado como API estável".

Superfície preferencial para entrada e saída ​

Na fase atual de unificação entre web e APIs, a superfície preferencial para adaptação de entrada/saída passou a ficar nas funções de criação de @fc/calculos-rgps/entidades/dados-calculo-rgps/criacao/* (entrada, uma por formato) e nas classes centrais do domínio (saída):

  • criarDadosCalculoRgpsDeEstadoWeb(...) para o formato usado pelo worker do prev-tc
  • criarDadosCalculoRgpsDeApiTempo(...) para payloads CalculoTempoApi
  • criarDadosCalculoRgpsDeApiTempoPrevjud(...) para payloads CalculoTempoPrevjudApi
  • criarDadosCalculoRgpsDeApiRmi(...) para payloads CalculoRmiApi
  • criarDadosCalculoRgpsDeApiRmiPrevjud(...) para payloads CalculoRmiPrevjudApi
  • criarDadosCalculoRgpsDeApiRmiDesvinculada(...) para payloads CalculoRmiDesvinculadaApi
  • criarDadosCalculoRgpsDeApiRmiDesvinculadaPrevjud(...) para payloads CalculoRmiDesvinculadaPrevjudApi
  • criarDadosCalculoRgpsDeArquivoTc(...) para arquivos .calc
  • criarDadosCalculoRgpsDePrevjud(...) para importar DadosPrevjud sobre um estado-base no mesmo formato da web
  • AnaliseBeneficiosRgps.paraApiResultado(...) e AnaliseBeneficiosRgps.paraApiGrupos(...) para saídas de tempo
  • CalculoRmi.paraApiBloco(...) e CalculoRmiDesvinculada.paraApi(...) para saídas de RMI

Os entrypoints legados em utilidades-apis continuam exportados e suportados nesta fase, mas agora funcionam como fachadas de compatibilidade sobre essa nova superfície.

Nas entradas de RMI, criterioSalarioMaternidade aceita UM_DOZE_AVOS ou MEDIA_SIMPLES_DOZE_ULTIMOS; quando omitido, usa UM_DOZE_AVOS. A leitura de um Arquivo .calc preserva esse critério no JSON devolvido. Em PeriodoContribuicaoApi, origem também usa valores nominais (CALCULO_INSS, CNIS, USUARIO, NENHUMA, PREVJUD ou MULTIPLA), e valores fora desse contrato são rejeitados.

O que não deve ser tratado como API estável ​

Os seguintes diretórios existem e são relevantes para entender a implementação, mas não devem ser assumidos como contrato externo estável:

  • src/calculadoras/
  • arquivos internos obterRegras*.ts
  • helpers internos de calculo-rmi, calculo-atrasados e calculo-tc

Se uma nova feature puder ser implementada usando símbolos já publicados pelos subpaths, prefira isso.

calcularPrescricaoParcelasSucessivas(...) é a exceção pública dentro de src/calculadoras: recebe o intervalo real de vencimentos da dívida, a data do ajuizamento e o prazo em meses civis. Opcionalmente, processa um marco interruptivo anterior e um período de suspensão. O resultado separa os períodos prescrito e não prescrito; a parcela cujo vencimento prescricional coincide com o ajuizamento permanece não prescrita.


Conceitos centrais do domínio ​

Espécies de benefício ​

O dicionário as const com tipo homônimo EspecieBeneficio concentra os códigos INSS em src/parametros/especie-beneficio/EspecieBeneficio.ts.

Espécies atualmente declaradas:

CódigoIdentificador
21PENSAO_PREVIDENCIARIA
25AUXILIO_RECLUSAO
31AUXILIO_POR_INCAPACIDADE_TEMPORARIA
32APOSENTADORIA_POR_INCAPACIDADE_PERMANENTE
36AUXILIO_ACIDENTE_PREVIDENCIARIO
41APOSENTADORIA_POR_IDADE
42APOSENTADORIA_POR_TEMPO_DE_CONTRIBUICAO
46APOSENTADORIA_ESPECIAL
57APOSENTADORIA_POR_TEMPO_DE_SERVICO_PROFESSOR
80SALARIO_MATERNIDADE
87AMPARO_SOCIAL_PCD
88AMPARO_SOCIAL_IDOSO
91AUXILIO_POR_INCAPACIDADE_TEMPORARIA_ACIDENTARIO
92APOSENTADORIA_POR_INCAPACIDADE_PERMANENTE_ACIDENTARIA
93PENSAO_ACIDENTARIA
94AUXILIO_ACIDENTE_ACIDENTARIO
95AUXILIO_SUPLEMENTAR

Os agrupamentos de espécies ficam em parametros/especie-beneficio/gruposEspecieBeneficio.ts; os predicados e as opções de interface ficam ao lado do dicionário. Ao adicionar uma espécie, revise também esses agrupamentos, as regras de concessão e seus consumidores.

Tipos de segurado ​

TipoSegurado define:

  • COMUM
  • PCD
  • RURICOLA

Esse tipo altera:

  • quais regras são geradas em RegrasConcessaoRgps
  • quais grupos aparecem em AnaliseBeneficiosRgps.apurarGrupos()
  • divisor e critérios em certas modalidades de RMI
  • possibilidade de direito adquirido ou tratamento especial em cenários pós-EC 103

Marcos temporais ​

MARCOS_TEMPORAIS vem de @fc/calculos-previdenciarios/parametros/marcos-temporais/marcosTemporais. As chaves são nominais, como CF_88, LEI_8213, LEI_9032, DPE_20, LEI_9876, LC_142, REGRA_PONTOS, DPE_103 e DIVISOR_MINIMO.

O RGPS escolhe as datas em que precisa refazer a contagem em MARCOS_CONTAGEM_TEMPO_RGPS, declarado em parametros/marcos-temporais/marcosContagemTempoRgps.ts. Use os marcos existentes nas comparações, preservando os casos na véspera, na data e no dia seguinte.

Unidade de tempo ​

Grande parte da biblioteca usa a convenção previdenciária de:

  • 1 ano = 360 dias
  • 1 mês = 30 dias

Isso afeta:

  • tempo de contribuição
  • idade previdenciária em várias regras
  • pedágio
  • pontos

Os testes das apps frequentemente formatam dias nessa convenção, como em apps/prev-tc/test/nuxt/helpers.ts.

Requisitos de concessão ​

Os requisitos são implementados em src/requisitos/ e retornam o contrato ResultadoRequisitoRgps, declarado em src/requisitos/tipos.ts.

Contrato real resumido:

ts
interface ResultadoRequisitoRgps {
  dataApuracao: Date
  nome: string
  rotulo: string
  resultado: {
    requisito: number
    apurado: number
    cumprido: boolean
    implementadoEm?: Date | Record<string, Date>
    paraPontos?: number
    paraCoeficiente?: number
    nota?: string
    inconsistencia: boolean
    porExtenso: string
    parametros?: {
      tipoContagem?: TipoContagem
      computarLc123?: boolean
      pedagio?: {
        dpe: Date
        patamar: number
        percentual: number
      }
      carencia?: {
        apenasRural: boolean
      }
    }
  }
}

Observação importante:

  • implementadoEm não é sempre uma Date; em alguns requisitos é uma tabela por competência.

Entidades principais ​

HistoricoRgps ​

Classe central do histórico contributivo em src/entidades/HistoricoRgps.ts.

Ela recebe:

  • lista de PeriodoRgps
  • lista de PeriodoPcd

E mantém:

  • mapas pré-calculados de tempo e carência
  • competências descartadas
  • competências excluídas
  • períodos excluídos derivados dessas competências

Também expõe operações como:

  • analisarComum
  • analisarPcd
  • analisarRural
  • analisarEspecial
  • descartar
  • excluirUltimoDescarte
  • excluirTodosDescartes

SeguradoRgps ​

Contrato real em src/entidades/SeguradoRgps.ts:

O construtor recebe SeguradoRgpsProps:

CampoTipoObrigatório
sexoSexosim
nascimentoDate ou string conversível em datasim
tipoTipoSeguradosim
historicoinstância de HistoricoRgpssim
salarios, salariosAnoCivilinstâncias de Salariosnão
beneficiosinstância de Beneficiosnão

Observações:

  • o nome real do campo é nascimento, não dataNascimento
  • o nome real do campo é tipo, não tipoSegurado
  • salarios e beneficios são opcionais, mas muitas integrações reais dependem deles
  • tipo possui setter e é alterado temporariamente por apurarGrupos()

DadosCalculoRgps ​

Contrato real em src/entidades/DadosCalculoRgps.ts:

O construtor recebe DadosCalculoRgpsProps, com o segurado, as datas de apuração, a espécie e as opções do cálculo. Consulte esse tipo para os campos obrigatórios e os parâmetros específicos de cada modalidade.

Nas entradas da aplicação, prefira deEstadoWeb; nas integrações HTTP, use o adaptador deApi* correspondente ao contrato. Esses métodos constroem as entidades e centralizam a adaptação. Um objeto JSON com campos semelhantes não substitui uma instância de HistoricoRgps, Salarios ou SeguradoRgps.

No construtor, DadosCalculoRgps:

  • valida e converte datas string
  • consolida salários
  • detecta competências abaixo do mínimo após EC 103
  • injeta competenciasExcluidas, datasParaCalculo e sexo no HistoricoRgps
  • chama historico.calcularMapas()

Ou seja: construir DadosCalculoRgps já dispara trabalho e mutação controlada no histórico.

Outras entidades frequentes ​

EntidadeUso principal
PeriodoRgpsvínculo/período computável ou não computável
PeriodoPcdmarcação de deficiência por intervalo
Salario / Salariossalários por competência
Beneficio / Beneficiosbenefícios concedidos, pagos, derivados ou usados em evolução
DadosAtrasadosraiz do cálculo de atrasados
Acrescimo / Acrescimosadicionais e acréscimos
Descontossdescontos no cálculo de atrasados
PeriodosBeneficioVantajosojanelas para desconto/acumulação em atrasados

Nomes legados relevantes ​

Alguns nomes reais do código são historicamente “estranhos”, mas precisam ser usados como estão:

  • CriterioSalarioMaternidade
  • Descontoss

Não “corrija” esses identificadores em código novo sem uma refatoração deliberada do pacote inteiro.


Fluxos canônicos de uso ​

Esta seção documenta os fluxos que de fato aparecem em prev-tc, prev-rvt e prev-atrasados.

1. Análise de tempo e elegibilidade ​

Com um estado de entrada no formato DadosCalculoEstadoWeb, já validado pela aplicação:

ts
import type { DadosCalculoEstadoWeb } from '@fc/calculos-rgps/entidades/DadosCalculoRgps'
import { AnaliseBeneficiosRgps } from '@fc/calculos-rgps/analise-beneficios/AnaliseBeneficiosRgps'
import { DadosCalculoRgps } from '@fc/calculos-rgps/entidades/DadosCalculoRgps'

function analisarTempo(estado: DadosCalculoEstadoWeb) {
  const dadosCalculo = criarDadosCalculoRgpsDeEstadoWeb(estado)
  const analise = new AnaliseBeneficiosRgps(dadosCalculo)
  return analise.apurarGrupos(true)
}

Esse fluxo pressupõe que as tabelas de índices exigidas pelo cálculo já foram instaladas, como faz o worker da aplicação. Para analisar somente a espécie e o tipo selecionados, use analise.apurar().ts const historico = new HistoricoRgps(periodosContribuicao, periodosPcd)

const dadosSegurado = new SeguradoRgps({ sexo, nascimento, tipo, historico, salarios: new Salarios(), beneficios: new Beneficios(), })

const dadosCalculo = new DadosCalculoRgps({ dadosSegurado, der, dataApuracao: der, especie, marcoCarencia, requisitoB41Pcd, aplicarIrsmFev94: false, calcularRmiPcdComRegraAnterior: false, calcularRmiComRegraAnteriorNaEc103: false, criterioSalarioMaternidade: CriterioSalarioMaternidade.MEDIA_SIMPLES_DOZE_ULTIMOS, opcoesAposEc103: { carencia: true, aplicarFator: true, excluirCompetenciasAbaixoDoMinimo: true, }, })

const analise = new AnaliseBeneficiosRgps(dadosCalculo) const resultado = analise.apurar()


Quando usar `apurarGrupos()`:

- quando a UI precisa avaliar todas as aposentadorias programadas plausíveis
- quando a integração quer comparar `COMUM`, `PCD` e `RURICOLA`

Comportamento importante:

- se a espécie inicial **não** for programada, `apurarGrupos()` devolve só um grupo
- se for programada, ele itera espécies e tipos, alterando temporariamente `dadosSegurado.tipo` e `dadosCalculo.especie`
- o parâmetro `desativarFiltros` muda bastante o resultado; `prev-tc` usa `true` no worker principal

### 2. Cálculo de RMI

O uso real nas apps não é um método simples “calcular tudo e devolver array”. O fluxo canônico é:

```ts
// A fábrica seleciona o motor pela modalidade e pela data de apuração.
const calculoRmi = criarCalculoRmi(dadosCalculo, tabelaIndexadores)

const linhas: ResultadoAposDescarte[] = []
const iterador = calculoRmi.calcular(tipoCalculo)

for (const linha of iterador) {
  linhas.push(linha)
}

const beneficiosMaisVantajosos = calculoRmi.beneficiosMaisVantajosos(linhas)

Esse padrão aparece em prev-tc em apps/prev-tc/app/composables/workers/calculoRmi.ts.

Contrato final mais usado pela UI:

ts
interface ResultadoCalculoRmi {
  maiorRmi: number
  moeda: DadosMoeda
  linhasDescartes: ResultadoAposDescarte[]
  beneficiosMaisVantajosos: BeneficioAnalisadoComRmi[]
}

Casos relevantes:

  • RMI normal na DIB
  • RMI por alterações legislativas
  • RMI com descartes
  • RMI desvinculada, usando coeficienteInformado e tempoInformado*

RMI desvinculada anterior à CF/88 ​

criarCalculoRmi retorna CalculoRmi no cálculo por períodos. Com a RMI desvinculada efetivamente ativa, retorna CalculoRmiDesvinculada após 05/10/1988 e CalculoRmiDesvinculadaAnteriorCf88 até essa data. Este último recusa DIB anterior a 11/06/1973 e espécies fora de 31, 32, 41, 42, 46 e 57; a espécie 57 exige DIB a partir de 30/06/1981.

O motor histórico fica em calculo-rmi/modo-rmi-desvinculada/regime-anterior-cf88/. Recebe coeficiente, salários e, quando necessários, grupos de 12 contribuições acima do menor valor-teto informados pelo usuário. Não analisa requisitos de concessão. O critério de correção é COEFICIENTES_INSS ou ORTN_OTN, segundo o dicionário CriterioCorrecaoSalariosAnteriorCf88.

O resultado conserva BeneficioAnalisadoComRmi e acrescenta a memória em dadosRmi.anteriorCf88. Cada salário é limitado ao teto de contribuição do seu mês; os salários corrigidos, a média, as parcelas e os limites da RMI são arredondados aos centavos. Com atividades concomitantes, cada secundária tem o seu PBC na mesma sistemática e entra no salário de benefício pela média multiplicada pela fração de anos informada; a soma com a média da principal é limitada ao maior valor-teto. O demonstrativo apresenta a RMI na DIB e a equivalência em salários mínimos. A evolução posterior pertence ao cálculo de atrasados.

A interface prev-tc e seus arquivos .calc preservam esses dados. As rotas específicas de RMI desvinculada da API ainda usam diretamente o motor posterior: não se deve presumir suporte ao regime histórico por essas rotas. Consulte o contrato de rmi-api antes de integrar esse caso.

3. Revisão da Vida Toda ​

CalculoRvt não é só uma variação pequena de CalculoRmi. Ele tem fluxo próprio, fortemente baseado em texto de carta/CNIS.

Contrato de entrada:

ts
interface ParametrosRvt {
  nascimento: Date
  sexo: Sexo
  tipo: TipoSegurado
  encadeamento: TipoEncadeamentoAtualizacaoSalarios
  carta: string
  cnis?: string
  opcoesFiltroCnis?: OpcoesFiltroCnis
  modificadoresVinculos: Record<string, VinculoProps>
  modificadoresSalarios: Record<string, SalarioProps>
  aplicarIrsmFev94: boolean
  usarSalarioMinimo: boolean
  manterSalariosCarta: boolean
  desabilitarDivisorMinimo: boolean
  desabilitarFator: boolean
}

Fluxo:

ts
const calculoRvt = new CalculoRvt(parametros, tabelaIndexadores)
const resultado = calculoRvt.calcularRmiRevisada()

Contrato de saída:

ts
interface ResultadoCalculoRvt {
  rmiRevisada: number
  indiceReposicao: number
  rmiRevisadaReajustada: number
  dadosReajuste: LinhaEvolucaoBeneficio[]
  diferenca: number
  direitoAdquirido: boolean
  dadosSalarioBeneficio: DadosSalarioBeneficio
  competenciaInicial: Date
  competenciaFinal: Date
  notasIndices: NotasCriterios
  notasMoedas: NotasCriterios
}

prev-rvt usa exatamente esse caminho, via worker, em apps/prev-rvt/app/composables/worker/calculoRvt.ts.

4. Evolução de benefício ​

Uso simples:

ts
const linhas = calcularEvolucaoSimples({
  beneficio,
  servicoIndices,
  servicoLimites,
})

Uso completo:

ts
const linhas = calcularEvolucaoCompleta({
  beneficio,
  servicoIndices,
  servicoLimites,
  servicoAdiantamentoAbono,
  inicio,
  termino,
  datasAdicionais,
})

Campos reais de LinhaEvolucaoBeneficio:

ts
interface LinhaEvolucaoBeneficio {
  competencia: Date
  data: Date
  dataTermino?: Date
  valorAnterior: number
  indice?: number
  aplicouIndiceReposicao?: boolean
  baseReajuste: number
  valorAtualIntegral: number
  coeficiente: number
  valorComCoeficiente: number
  rateio: number
  valorComRateio: number
  proporcaoRenda: number
  valorComProporcao: number
  adicional25PorCentoIntegral: number
  adicional25PorCento: number
  valorFinal: number
  rendaComAdicional: number
  rendaParaAcumulacao: number
  computouAbono: boolean
  abono?: number
  proporcaoAbono?: number
  adiantamentoAbono?: boolean
  piso: number
  teto: number
}

Os testes de tests/beneficio/evolucao-beneficios.spec.ts são a melhor referência para cenários de borda aqui.

5. Cálculo de atrasados ​

Fluxo-base:

ts
const dadosAtrasados = new DadosAtrasados({
  liquidacao,
  beneficiosDevidos,
  beneficiosPagos,
  descontos,
  acrescimos,
  periodosBeneficioVantajoso,
})

const calculo = new CalculoAtrasados(dadosAtrasados, tabelaIndexadores)
const resultado = calculo.calcular()

Nas apps, o worker monta antes um grafo de entidades:

  • Processo
  • Honorarios
  • Multa
  • Liquidacao
  • Beneficios
  • Descontoss
  • Acrescimos
  • PeriodosBeneficioVantajoso

Esse fluxo aparece em apps/prev-atrasados/app/composables/workers/calculoAtrasados.ts.


Módulos do pacote ​

parametros ​

Local: src/parametros/

Os parâmetros de domínio que só o RGPS nomeia (dicionários as const): fundamento, especie-beneficio, tipo-segurado, tipo-calculo-rmi, finalidade-beneficio, tipo-base-reajuste, marco-carencia, requisito-b41-pcd, criterio-salario-maternidade, criterio-apuracao-abono, efeitos-exclusao, os da baixa renda e da RMI desvinculada. Uma pasta por parâmetro, em kebab-case: o dicionário no arquivo homônimo e cada auxiliar em módulo próprio, sem index.ts. A constante de domínio que não é parâmetro segue a mesma pasta: marcos-temporais/marcosContagemTempoRgps.ts (MARCOS_CONTAGEM_TEMPO_RGPS, a seleção de marcos que obriga o RGPS a recontar o tempo).

O vocabulário que os dois regimes falam — Sexo, FormaContagem, TipoContagem, GrauDeficiencia, MotivoContagem, Origem, NaturezaVinculo, MARCOS_TEMPORAIS e PESOS — vem de @fc/calculos-previdenciarios/parametros/.

Nenhuma regra de cálculo deve nascer aqui, mas quase toda regra depende do que está aqui.

entidades ​

Local: src/entidades/

Camada de objetos do domínio. Além de armazenar dados, várias entidades validam, normalizam e precomputam estruturas.

requisitos ​

Local: src/requisitos/

Implementa os requisitos que compõem cada regra de concessão:

  • tempo
  • idade
  • carencia
  • pontos
  • pedagio
  • deficiencia
  • tempo-deficiencia
  • imediatidade
  • qualidade-segurado

analise-beneficios ​

Local: src/analise-beneficios/

Responsável por:

  • gerar regras aplicáveis
  • apurar cumprimento
  • separar cumpridos, não cumpridos e possível reafirmação
  • calcular grupos “nas alterações”
  • montar blocos progressivos

Arquivos centrais:

  • AnaliseBeneficiosRgps.ts
  • RegrasConcessaoRgps.ts
  • parametros/fundamento/ (o parâmetro Fundamento, seus rótulos e grupos, fora de analise-beneficios/)
  • obterRegras*.ts

Cada BeneficioAnalisado devolvido pela análise identifica a regra por dois campos: chaveFundamento (o nome do parâmetro, EC_103_ART_20, usado em filtros, agrupamentos e no cálculo de RMI por fundamento) e fundamento (a citação legal legível, EC 103, art. 20, para exibição e para as APIs).

calculo-tc ​

Local: src/calculo-tc/

Responsável por:

  • totalização
  • coincidência de períodos
  • carência
  • tempo especial
  • magistério
  • PcD
  • preponderância

É uma das áreas mais sensíveis para regressão.

calculo-tc/contagem-por-competencia/ guarda a conta do RGPS por competência — os dias das competências das pontas, antes e depois da EC 103, e se a primeira e a última competência contam inteiras quando outro período as cobre. PeriodoRgps.tempoEmDias e HistoricoRgps a usam; o RPPS conta data a data e não passa por ela.

calculo-tc/serie-historica ​

Local: src/calculo-tc/serie-historica/

A série histórica da Vida contributiva: gerarSerieHistorica(estado, progresso?) apura, competência a competência, do primeiro vínculo cadastrado até a data de apuração, o tempo simples e convertido, a carência, a carência de não programados (com a regra de perda e recuperação da qualidade de segurado, no requisito da espécie do grupo), a idade e a qualidade de segurado — contribuindo, em período de graça (com o término e as prorrogações) ou sem qualidade — com os mesmos totais e a mesma conta do demonstrativo, reapurados exatamente em cada data, sem interpolação — e os IDs dos vínculos e períodos de deficiência de cada competência, além da primeira filiação e dos marcos: perdas e reingressos de qualidade e a competência das 120 contribuições sem perda (só com o parâmetro do Tema 255/TNU ligado). Função pura, pensada para rodar em worker; carregamento sob demanda, cancelamento e cache são do consumidor.

simulacao-por-totais ​

Local: src/simulacao-por-totais/

A Simulação de Benefícios por Totais: quem tem o total de tempo apurado pelo INSS até a DER — e não os períodos que o compõem — informa esse total por marco temporal, acrescenta só os períodos que faltam (inteiros ou só pelo acréscimo da conversão) e vê se nasce direito a algum benefício. É uma metodologia alternativa, em pasta própria, que usa as classes do motor por trás sem alterá-las.

  • simularBeneficiosPorTotais(props) é a entrada: recebe segurado, DER, os totais absolutos até cada marco (tempo por modalidade em dias do ano de 360 e carência em contribuições; só o da DER é obrigatório) e os períodos adicionados, e devolve os grupos de benefícios programados avaliados, os marcos não informados, os totais informados normalizados e as regras não apuráveis.
  • Entre marcos vale o último total informado; só os períodos adicionados crescem. O total existe integralmente no marco, e o requisito que se cumpre graças a ele implementa-se ali.
  • Marco em branco não é um ponto da simulação: a regra que depende dele (pedágios, transições da EC 103, análises naquela data) é devolvida como não apurável, em vez de calculada com um valor que o usuário não informou.
  • Fora: não programadas, qualidade de segurado, RMI, atrasados e alçada — sem competências não há salário-de-benefício. O contrato de tempo das APIs não carrega a simulação.

baixa-renda-reclusao ​

Local: src/baixa-renda-reclusao/

A apuração do requisito de baixa renda do segurado recolhido à prisão para o auxílio-reclusão: apurarBaixaRendaReclusao(estado, { criterioDivisor }) escolhe o regime pela data da prisão (antes da EC 20/98, não aplicável; até a MP 871/2019, a renda na competência da prisão; a partir dela, a média dos salários de contribuição das 12 competências anteriores ao mês da prisão, pelos valores nominais limitados ao teto, dividida pelas competências com salário — Tema 310/TNU — ou sempre por 12), compara com o limite da portaria vigente na data (@fc/indices/limite-baixa-renda) e devolve o resultado conclusivo, não aplicável ou inconclusivo, com a memória de apuração, o critério aplicado, os fundamentos e as controvérsias que ficam para decisão do usuário (sem vínculo na prisão, Tema 896/STJ; último salário anterior; mês proporcional). Não concede o benefício nem examina os demais requisitos.

quadro-resumo ​

Local: src/quadro-resumo/

O motor do Quadro Resumo: a lista dos benefícios que cumprem requisitos, com a RMI de cada fundamento e o valor da causa. Funções puras, pensadas para rodar em worker, sobre o motor sem alterá-lo.

  • analisarCandidatosQuadroResumo(estado) reapura os grupos na DER, na DER reafirmada e nas datas de possível reafirmação propostas pelo motor até a data de apuração, e devolve um candidato por fundamento cumprido e hipótese de RMI, com a origem da DIB.
  • calcularRmiCandidatoQuadroResumo roda a RMI com filtro de fundamento na DIB do candidato; calcularRendaCandidatoQuadroResumo reajusta essa RMI até a data de referência (a renda mensal); calcularValorDaCausaCandidatoQuadroResumo apura atrasados simples e, deles, o valor da causa (vencidas mais doze vincendas) com a alçada informativa. Lacuna de índices e dados faltantes voltam como pendência com o motivo, não como zero.
  • Fora: totalização de períodos, RMI desvinculada e demonstrativos.

calculo-rmi ​

Local: src/calculo-rmi/

Responsável por:

  • PBC
  • correção dos salários
  • divisor
  • salário de benefício
  • aplicação do coeficiente apurado pela análise de benefícios, ou informado no modo desvinculado
  • fator previdenciário
  • descartes
  • RVT

Classes principais:

  • CalculoRmi
  • CalculoRmiDesvinculada
  • CalculoRmiDesvinculadaAnteriorCf88
  • CalculoRvt

evolucao-beneficio ​

Local: src/evolucao-beneficio/

Responsável por:

  • evolução simples
  • evolução completa
  • abono
  • rateio
  • proporcionalidade
  • aplicação de piso e teto

calculo-atrasados ​

Local: src/calculo-atrasados/

Responsável por:

  • consolidação de benefícios devidos/pagos
  • atualização
  • descontos EC 103
  • honorários
  • multa
  • outros débitos
  • vincendas
  • dados de alçada

concomitância — vive em @fc/calculos-judiciais ​

Não é módulo deste pacote. temConcomitancia e tirarConcomitancia mudaram para @fc/calculos-judiciais/concomitancia/* junto com a abstração de Periodo e Periodos, que os aplicam. O corte temporal da Lei 13.846/2019 continua sendo tratado no cálculo de RMI deste pacote.

persistencia ​

Local: src/persistencia/

Migra formatos serializados antigos de TC e atrasados. Cada cadeia é uma lista de Migrador (@fc/arquivos-calc) encadeados por versão da app que gravou o arquivo: tc/migradores/migrador01…11 e atrasados/migradores/migrador01…04.

É muito usada pelas apps ao abrir arquivos .calc.

parametros-legados/ traduz os parâmetros que os .calc gravavam como ordinal (sexo: 1, formaContagem: 2, finalidade: 0…) para o vocabulário nominal atual: ORDINAIS_LEGADOS (de @fc/calculos-previdenciarios, o vocabulário comum aos dois regimes) e ORDINAIS_LEGADOS_RGPS (os parâmetros que só o RGPS nomeia) são as tabelas congeladas da numeração antiga, migrarParametroLegado (de @fc/arquivos-calc) a regra (valor válido passa; o valor legado — ordinal, ou o texto antigo, como nos parâmetros do RPPS — é traduzido; ausente fica ausente; desconhecido cai no padrão histórico dos campos obrigatórios ou segue intacto, para a validação de domínio acusar), e migrarSeguradoRgpsLegado (que acrescenta o tipo ao sexo de migrarSeguradoLegado), migrarPeriodoContribuicaoLegado, migrarPeriodoPcdLegado e migrarBeneficioLegado aplicam-na por objeto. VALORES_LEGADOS_INDICES é a tabela congelada dos textos que os .calc gravavam para os parâmetros de @fc/indices (indexador: 'inpc', taxa: 'taxaLegal', encadeamento: 'padrao'), e migrarIndexadorFlexivelLegado, migrarTaxaJurosFlexivelLegada e migrarConsectariosLegados traduzem o encadeamento configurado dos consectários. ORDINAIS_LEGADOS_JUDICIAIS faz o mesmo para os parâmetros de @fc/calculos-judiciais que os .calc de atrasados gravavam como ordinal (criterioDeducaoAlcada, honorarios.baseIncidencia, multa.baseIncidencia), aplicada por migrarHonorariosLegados e migrarMultaLegada. Os migradores tc/migradores/migrador11 (10.11.6 → atual) e atrasados/migradores/migrador04 (5.6.10 → atual) usam-nas; a cadeia do RPPS (/calculos-rpps, migrador02) e a do RVT (apps/prev-rvt) reutilizam os mesmos mapeadores pelo subpath @fc/calculos-rgps/persistencia/*.

A simulação por totais grava dados.simulacaoPorTotais no mesmo arquivo: campo opcional, sem migrador; arquivo anterior abre como sempre abriu.

utilidades-apis ​

Local: src/utilidades-apis/

Converte entre:

  • payloads simples de API/UI
  • entidades do domínio
  • resultados serializados

Submódulos principais:

  • tempo
  • rmi
  • atrasados
  • leitura-documentos

Em leitura-documentos, usarDadosCarta(...) adapta a Carta de Concessão para o contrato do cálculo de tempo, com DER/DIB e competências em ISO. usarDadosPap(...) reúne esse resultado aos de CNIS e RDCTC, preservando a ordem global dos documentos segmentados.

documentos/filtros e documentos/plugins ​

Responsáveis por interpretar e filtrar dados externos, especialmente CNIS, carta e dossiês.

Os plugins entregam sexo, forma e motivo de contagem, grau de deficiência e natureza do vínculo com os tipos e valores de @fc/calculos-previdenciarios/parametros/: por exemplo, Sexo.FEMININO (F), FormaContagem.ESPECIAL_25 e GrauDeficiencia.MODERADO. Rótulos encontrados no documento são convertidos durante a extração. DadosPeriodo, em documentos/tipos, conserva o contrato de dados extraídos, com datas Date e carência/prioridade opcionais; a preparação para o cálculo completa esses campos e define excluido. Os envelopes JSON de RDCTC guardados antes dessa mudança continuam aceitos: os rótulos antigos são migrados durante a leitura, antes da preparação para o cálculo ou da saída HTTP/MCP.

Consumidores devem importar os parâmetros diretamente do motor: os tipos Analisador* e os módulos documentos/mapeamento/mapear*DoAnalisador foram removidos. Os resultados finais da importação mantêm o comportamento anterior.

Além dos filtros, documentos/plugins expõe os plugins RGPS consumidos pelo registro documentos/importacao/registroDocumentosPrevidenciarios (entregue ao importador genérico de @fc/parsers) e pelas apps. Exemplos:

  • PluginCnisCompleto, PluginCnisVinculos, PluginMeuINSS
  • PluginCartaConcessao, PluginCartaConcessaoNova
  • PluginHiscreSat
  • PluginPlanilhaGoogle
  • fonteIndicadoresCnis e obterIndicadorCnis

Demonstrativos: resultados, marcas e apresentação ​

Os geradores de demonstrativos/tempo/, demonstrativos/rmi/ e demonstrativos/atrasados/ recebem um contexto explícito e produzem blocos, notas e tabelas a partir dos resultados do motor. As colunas leem a linha tipada. Marcas identificam fatos como período não computado, salário descartado, linha de total ou valor modificado pelo usuário.

A interface traduz essas marcas em apresentação. Os montadores de PDF usam os contratos de @fc/calculos-judiciais/demonstrativos/ e o documento de @fc/demonstrativo-pdf. Cores, classes CSS e larguras pertencem aos consumidores; a regra que escolhe o valor e sua marca permanece no gerador. Para corrigir uma divergência, compare primeiro o resultado calculado, depois a tabela semântica e, por fim, a tradução para tela ou PDF.

Efeitos colaterais e mutabilidade interna ​

Esta é uma seção crítica para quem vai mexer na biblioteca.

DadosCalculoRgps não é puramente declarativo ​

Ao ser construído, ele:

  • converte datas string para Date
  • consolida salários
  • escreve em dadosSegurado.historico
  • chama historico.calcularMapas()

AnaliseBeneficiosRgps.apurarGrupos() muta e restaura estado ​

Durante a execução, ele altera temporariamente:

  • dadosSegurado.tipo
  • dadosCalculo.especie

e ao final restaura os valores anteriores.

Consequências:

  • não compartilhe a mesma instância em fluxos concorrentes
  • evite assumir que DadosCalculoRgps é imutável
  • se for criar paralelização, clone ou reconstrua o grafo de entrada

HistoricoRgps acumula estado de descarte ​

Operações de descarte alteram mapas e listas internas. Isso é intencional para suportar cálculo iterativo de descartes na RMI.


Como as apps consomem a biblioteca ​

prev-tc ​

Usa a biblioteca como motor principal de:

  • análise de tempo
  • elegibilidade
  • RMI
  • abertura de arquivos .calc

Pontos importantes observados nos testes:

  • apurarGrupos(true) é o comportamento canônico do worker
  • o fluxo comum passa por desserialização de payload em entidade real
  • os testes afirmam fundamentos, totais, carência e marcos de alteração

Referências:

prev-rvt ​

Usa:

  • CalculoRvt
  • parsing de carta
  • parsing de CNIS
  • modificadores de vínculos e salários
  • validação de aplicação do fator previdenciário

Referências:

prev-atrasados ​

Usa:

  • evolução de benefícios
  • cálculo de atrasados
  • descontos
  • honorários
  • multa
  • períodos de benefício vantajoso

Referência:


Guia para novas regras ​

Nova espécie de benefício ​

Checklist mínimo:

  1. adicionar ao dicionário EspecieBeneficio
  2. adicionar rótulo
  3. revisar agrupamentos de espécie
  4. criar ou adaptar obterRegras*.ts
  5. registrar em RegrasConcessaoRgps
  6. revisar impacto em coeficiente, fator, divisor, RVT e atrasados
  7. revisar serializadores e migradores, se a espécie aparecer em payload salvo

Novo requisito ​

  1. criar módulo em src/requisitos/<nome>/
  2. implementar contrato RequisitoRgps
  3. nada a exportar: o arquivo já sai por @fc/calculos-rgps/requisitos/*
  4. plugar nas regras que o usam
  5. verificar se o requisito participa de: paraPontosparaCoeficienteimplementadoEm análise postergada

Novo marco temporal ​

  1. adicionar em MARCOS_TEMPORAIS, no núcleo comum
  2. revisar MARCOS_CONTAGEM_TEMPO_RGPS quando aplicável
  3. revisar ROTULOS_ALTERACOES_TIPO_CALCULO_RMI, DATAS_APURACAO_POR_TIPO_CALCULO_RMI e os grupos progressivos quando fizer sentido

Mudança em regra existente ​

Sempre testar três camadas:

  1. unidade do pacote
  2. integração da app consumidora principal
  3. cenário de direito adquirido ou regra anterior

Onde normalmente mexer ​

MudançaArquivos mais prováveis
nova regra de benefícioanalise-beneficios/obterRegras*.ts
novo requisitorequisitos/<nome>/
regra igual à do RPPS@fc/calculos-previdenciarios/requisitos/ (pontos, pedágio, colunas especial e PcD, deficiência) — a regra idêntica por lei não se duplica
nova transiçãodefinirGruposProgressivasRgps.ts (agrupamento comum em @fc/calculos-previdenciarios/analise-beneficios/agrupamento/), marcos-temporais/marcosTemporais.ts do núcleo
mudança de coeficienteanalise-beneficios/coeficiente/
mudança de fatoranalise-beneficios/fator-previdenciario/
mudança de divisor/PBCcalculo-rmi/
mudança de evoluçãoevolucao-beneficio/
mudança de atrasadoscalculo-atrasados/

Estratégia de testes ​

Preferência do repositório ​

Nesta biblioteca, testes mais valiosos tendem a afirmar invariantes semânticas, não snapshots amplos.

Exemplos de assertivas fortes:

  • fundamentos reconhecidos
  • tempo total apurado
  • carência
  • data de implementação
  • divisor
  • média
  • salário de benefício
  • aplicação ou não do fator
  • total devido em atrasados

Isso aparece tanto nos testes do pacote quanto nas apps consumidoras.

Paridade web/API a partir de .calc ​

O gerador específico do domínio fica em tests/paridade-calc/, não em @fc/test-utils. Rode primeiro em modo de inspeção:

bash
pnpm --filter @fc/calculos-rgps gerar-teste-paridade-calc -- --arquivo caminho/arquivo.calc --dry-run

O dry-run trata a saída como candidata e mostra um inventário de privacidade sem revelar valores. Ele sinaliza datas pessoais e textos livres para revisão, informa a canonização do timestamp obrigatório e bloqueia identificador, e-mail ou credencial residual. Depois de revisar os campos e o inventário, classifique a origem e gere:

bash
pnpm --filter @fc/calculos-rgps gerar-teste-paridade-calc -- --arquivo caminho/arquivo.calc --origem sintetica
# ou: --origem anonimizada-revisada

O gerador grava a fonte canônica em @fc/test-utils, reaproveita conteúdo idêntico em execuções posteriores e cria as specs de Tempo/RMI em prev-tc ou de Atrasados em prev-atrasados. Sanitização estrutural não é anonimização irreversível. A paridade dinâmica prova concordância entre superfícies; valores juridicamente validados pertencem a casos de ouro separados.

Quando usar snapshot ​

Snapshot pode ser útil para estruturas muito grandes e estáveis, mas não deve substituir assertivas de negócio sobre:

  • fundamento
  • datas
  • valores centrais
  • efeitos de marcos temporais

Cobertura mínima recomendada para regra nova ​

  • um cenário positivo
  • um cenário negativo
  • um cenário em marco anterior
  • um cenário em marco posterior
  • um cenário com integração real na app mais afetada

Armadilhas comuns ​

  • Não renomeie identificadores do domínio — o código usa PT-BR sem acento e os nomes refletem o contrato jurídico real.
  • DadosCalculoRgps, SeguradoRgps e HistoricoRgps não são imutáveis — são mutados internamente durante o fluxo de cálculo.
  • apurarGrupos() não é uma expansão simples — aplica filtros de concomitância, interseções e regras de marco temporal.
  • CalculoRmi usa gerador síncrono — entrega etapas de descarte conforme o consumidor percorre o iterador; o worker é que executa esse percurso fora da thread principal.
  • Não há barrel: importe pelo subpath do arquivo que declara o símbolo. O wildcard do exports alcança também helpers internos, que não são API estável.
  • Ao alterar qualquer regra pós-marco temporal, preserve e teste explicitamente o comportamento pré-marco.
  • Antes de criar nova abstração, busque uso real nas apps (prev-tc, prev-rvt, prev-atrasados) — muitas decisões de design já estão cristalizadas lá.

Dependências externas ​

PacoteO que fornece
@fc/indicesíndices de correção, limites do RGPS, tábua de mortalidade, serviços de reajuste
@fc/comumEntidade, Competencia, memoização e utilidades compartilhadas
@fc/utilsdatas, aritmética previdenciária, predicados, truncamento e conversões
@fc/calculos-judiciaissuporte a liquidação judicial, honorários, multa e débitos
@fc/parsersleitura de arquivos, núcleo genérico do parser por plugins e orquestração

Referências úteis ​

Honorários contratuais ​

O cálculo de Atrasados aceita o parâmetro opcional honorariosContratuais: { destacar: true, percentual: 0.3 }, equivalente a 30%. O percentual é uma fração de 0 a 1, com até quatro casas decimais (duas casas percentuais); ativação sem percentual é recusada. Ausência ou destacar: false desativa o destaque.

O resultado opcional honorariosContratuais contém percentual, valores discriminados de honorarios e autor, além de dadosRra quando disponível. A divisão incide sobre o Resultado Atrasados final, conserva valores e meses de RRA e mantém a condenação e os honorários sucumbenciais. JSON, .calc, MCP e PDF usam essa mesma regra. O quadro “Honorários Contratuais (Destaque)” aparece após Resultado Atrasados e fica oculto na apuração exclusiva de sucumbenciais.