Skip to content

Documentação Técnica (este site) ​

Este site é gerado pelo apps/docs-tec usando VitePress com suporte a diagramas Mermaid.

A referência automática de tipos agora vive em um artefato separado, apps/docs-tipos, voltado exclusivamente ao uso local de desenvolvimento.

Como rodar localmente ​

bash
# Instalar dependências (se ainda não fez)
pnpm install

# Dev server na porta 3011
pnpm --filter @fc/docs-tec dev:open

Como o conteúdo é organizado ​

O site combina inclusão de fontes, páginas curadas e controle de visibilidade:

1 — <!--@include:--> (maioria das páginas) ​

A diretiva nativa do VitePress inclui o conteúdo de um arquivo externo diretamente. As páginas do site público sempre incluem o README.md do app/package — que é a versão pública sanitizada.

md
<!-- apps/docs-tec/site/pacotes/utils.md -->
# @fc/utils

Pacote base do monorepo com classes e funções de propósito geral. **Não tem dependências internas** — é a raiz do grafo de dependências da Fábrica de Cálculos.

## Módulos

Não há barrel: cada função é um arquivo, e o consumidor importa o arquivo que declara o símbolo pelo subpath `@fc/utils/<módulo>/<arquivo>` (ex.: `@fc/utils/datas/antesDe`). O `exports` do `package.json` publica cada módulo por wildcard (`./datas/*` → `src/datas/*.ts`); importar `@fc/utils` pela raiz não resolve e é barrado pelo linter.

| Módulo       | Conteúdo principal                                                                                                                                                                                   |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `datas`      | Aritmética de datas: `adicionarDias360`, `diferencaEntreDatas`, `ultimoDiaDoMes`, `entreCompetencias`, `mesmaCompetencia`, e mais de 40 funções para manipulação de datas no contexto previdenciário |
| `numeros`    | Arredondamento, truncamento e formatação numérica                                                                                                                                                    |
| `strings`    | Normalização, limpeza e comparação de strings                                                                                                                                                        |
| `predicados` | Funções de verificação de tipo e pertencimento: `tipoNumero`, `tipoString`, `tipoData`, `tipoObjeto`, `ehValorDeDicionario`, etc.                                                                    |
| `validacao`  | Validação de CPF, datas, competências e outros dados de entrada                                                                                                                                      |
| `objetos`    | Utilitários para manipulação de objetos e clonagem profunda                                                                                                                                          |
| `vetores`    | Operações sobre arrays: agrupamento, ordenação, deduplcação                                                                                                                                          |
| `enums`      | Utilitários de enumeração                                                                                                                                                                            |
| `url`        | Manipulação agnóstica de URLs e caminhos: `juntarUrl`, `normalizarCaminhoUrl`, `extrairHostname`, `ehHostLocal`                                                                                      |
| `http`       | Requisições JSON resilientes e interpretação do tempo de espera informado por serviços HTTP                                                                                                          |
| `etc`        | Funções auxiliares diversas                                                                                                                                                                          |

## Antes de criar uma função nova

Verifique primeiro se já existe uma função equivalente neste pacote ou em `@fc/comum`.

Use `@fc/utils` para funções compartilháveis que sejam agnósticas em relação ao domínio da Fábrica de Cálculos: datas, números, strings, predicados, objetos, URLs, serialização, validação genérica e infraestrutura técnica. Se a função souber de calculadoras, apps, contratos de API, mensagens do produto ou vocabulário de negócio, o destino provável é `@fc/comum`, não `@fc/utils`.

## Serialização CSV

`serializarCsv` recebe uma matriz de campos já preparada pela origem. Por padrão, usa ponto e vírgula, CRLF, BOM e quebra de linha final. Textos passam por `protegerTextoPlanilha`; números usam vírgula decimal, até 15 dígitos significativos e representação sem notação científica. Valores ausentes ficam vazios.

```ts
import { serializarCsv } from '@fc/utils/strings/serializarCsv'

serializarCsv([
  ['Descrição', 'Valor'],
  ['Parcela', -1234.5],
])

OpcoesSerializacaoCsv, em @fc/utils/strings/tipos, permite configurar separador, quebraLinha, bom, terminarComQuebraLinha e sempreEntreAspas. Os callbacks formatarNumero e protegerTexto substituem os padrões; o escape de aspas, separadores e quebras permanece obrigatório depois deles.

O tipo CampoCsv aceita texto, número, null, undefined ou { tipo: 'formatado', valor: string }. Essa última forma conserva conteúdo que a origem já formatou e protegeu quando necessário: recebe apenas escape CSV, sem executar os callbacks novamente. A distinção permite preservar números negativos já formatados sem tratar mensagens textuais iniciadas por hífen como números.

A origem resolve cabeçalhos, ordem, grupos, campos vazios e totais. O serializador não interpreta objetos de tabelas. serializarLinhaCsv e serializarCampoCsv oferecem as mesmas regras para uma linha ou campo isolado; formatarNumeroCsv expõe a formatação numérica padrão. Nenhuma dessas funções depende de navegador.

Web Workers — criarWorkerScope ​

Todas as apps da Fábrica de Cálculos executam cálculos pesados fora da thread principal usando a infraestrutura de criarWorkerScope deste pacote.

A assinatura é criarWorkerScope(ctx, opcoesLogger, trabalho). O contexto é o DedicatedWorkerGlobalScope; as opções do logger podem ser fixas ou uma função da mensagem; o trabalho recebe a entrada e um contexto com publicarProgresso.

A resposta usa ResultadoWorker: tipo identifica sucesso, erro ou progresso, e dados carrega o conteúdo. O consumidor deve tratar esses casos, coordenar cancelamento e reconstruir entidades a partir dos dados recebidos. Consulte o worker real apps/prev-tc/app/composables/workers/calculoTempo.ts como referência; uma entidade enviada por postMessage não preserva seus métodos.

Quando a tarefa lança, usarWorker rejeita com um Error reconstruído que conserva a mensagem, o nome e o código da exceção original; a classe não atravessa a fronteira do Worker.

Uso ​

ts
import { converterStringEmData } from '@fc/utils/datas/converterStringEmData'
import { mesmaCompetencia } from '@fc/utils/datas/mesmaCompetencia'
import { ehValorDeDicionario } from '@fc/utils/predicados/ehValorDeDicionario'
import { tipoNumero } from '@fc/utils/predicados/tipoNumero'

converterStringEmData('01/2024')       // Date
mesmaCompetencia(new Date(), outra)    // boolean
ehValorDeDicionario(valor, dicionario) // preserva o tipo dos valores
tipoNumero(1)                           // true

Clientes HTTP podem declarar sua própria política de confiabilidade e reutilizar o transporte agnóstico:

ts
import { requisitarJson } from '@fc/utils/http/requisitarJson'

const { resposta, dados } = await requisitarJson(url, {
  nomeServico: 'Serviço externo',
  politica: {
    maximoTentativas: 3,
    timeoutTentativaMs: 10_000,
    orcamentoTotalMs: 30_000,
    atrasoBaseMs: 250,
    limiteCorpoBytes: 2 * 1024 * 1024,
  },
})

Para coordenar uma nova tentativa sem adotar o transporte completo, obterEsperaRetryAfter interpreta o cabeçalho Retry-After em segundos ou data HTTP e devolve o intervalo em milissegundos:

ts
import { obterEsperaRetryAfter } from '@fc/utils/http/obterEsperaRetryAfter'

const esperaMs = obterEsperaRetryAfter(resposta.headers)

Aritmética decimal ​

Decimais interpreta os operandos pela representação decimal canônica de number, conserva os intermediários exatos e converte o resultado uma única vez. ComPrecisao e Moeda truncam em direção a zero somente ao fim da operação.

ts
import { Decimais } from '@fc/utils/numeros/decimais'

Decimais.somar(0.1, 0.2) // 0.3
Decimais.multiplicarMoeda(100, -0.29) // -29
Decimais.dividirMoeda(1, 0.015) // 66.66
Decimais.multiplicarPorRazaoMoeda(1200, 10, 12) // 1000
Decimais.multiplicarPorRazaoMoeda(1200, 1, 12, 0.5) // 50

Para razões exatas, mantenha numerador e denominador separados: 1 / 12 já é uma aproximação quando chega à função. multiplicarPorRazaoComPrecisao({ casas }) cria a variante configurável, com os mesmos argumentos de multiplicarPorRazaoMoeda.

A precisão aceita inteiros de 0 a 324, com duas casas por padrão; truncar usa zero por padrão. Operandos não finitos, divisão por zero, estouro e subfluxo da conversão final lançam erro. Os métodos monetários também recusam resultados cuja conversão para number perderia centavos. O retorno continua sujeito aos limites de representação de number; a classe não recupera precisão perdida antes da chamada. Soma e multiplicação sem argumentos retornam zero.

Escolha da operação e limites ​

NecessidadeMétodoEncerramento da operação
Somar ou multiplicar sem pedir cortesomar(...valores), multiplicar(...valores)Conversão final para number
Resultado monetáriosomarMoeda, multiplicarMoeda, dividirMoedaTruncamento em duas casas e verificação da preservação dos centavos
Precisão configurávelsomarComPrecisao({ casas }), multiplicarComPrecisao({ casas })Fábrica de função com truncamento na precisão escolhida
Dividirdividir(numerador, denominador, casas)Duas casas se casas for omitido
Aplicar uma fraçãomultiplicarPorRazaoMoeda(valor, numerador, denominador, ...fatores)Preserva a razão até o corte monetário
Cortar um resultado já recebidotruncar(valor, casas)Em direção a zero; zero casas por padrão

ComPrecisao({ casas: 2 }) não oferece a verificação adicional de centavos de Moeda. Para valores monetários, prefira os métodos monetários. Truncar também não é arredondar: truncar(-1.239, 2) devolve -1.23.

A ordem importa. somarMoeda(0.009, 0.009) devolve 0.01; cortar cada parcela antes da soma devolve zero. Escolha o ponto de encerramento conforme a regra do cálculo. truncar(a * b, 2) recebe um produto já calculado pelo JavaScript; multiplicarMoeda(a, b) recebe os operandos para realizar a multiplicação decimal.

Internamente, o núcleo decompõe o texto canônico do número em coeficiente inteiro e escala decimal. Soma e multiplicação usam inteiros number enquanto seguros; quando necessário, promovem os operandos originais a BigInt. A divisão usa divisão inteira em BigInt. Essa estratégia preserva os intermediários, mas o retorno público continua sendo number.

Decimais.normalizar(texto) expande notação científica sem arredondar os dígitos. Texto sem expoente ou inválido é devolvido intacto; expoentes com módulo acima de 10000 são recusados.

Instalação (monorepo) ​

jsonc
// package.json
{ "dependencies": { "@fc/utils": "workspace:*" } }

Os packages/ exportam TypeScript puro: o exports do package.json aponta direto para os .ts de src/ — sem step de compilação.


### 2 — Conteúdo curado (páginas de arquitetura, guias, segurança)

Páginas que agregam informação de múltiplas fontes ou contêm diagramas Mermaid têm conteúdo escrito diretamente em `site/`.

### 3 — Visibilidade por frontmatter

Toda página em `site/**/*.md` declara `visibilidade: publico` (ou `interno`) no frontmatter. Páginas com `visibilidade: interno` são excluídas do build de produção, mas aparecem em desenvolvimento com prefixo `[INTERNO]`. Conteúdo realmente sensível (credenciais, schema literal, rotas privadas, headers proprietários) fica nos `CONTEXT.md` internos da raiz, app ou package dono do assunto, **fora do site público**.

O linter `pnpm docs:lint` cobre os dois sites, os READMEs públicos e arquivos textuais publicados. Ele bloqueia CPFs com DV válido, rotas privadas, headers proprietários, credenciais conhecidas, hostnames internos, nomes de configuração de implantação e caminhos operacionais, entre outros detalhes que não pertencem à superfície pública.

Os arquivos visuais publicados também têm hash, origem e data de revisão registrados em um inventário. Um arquivo novo ou alterado exige aprovação humana antes de o inventário ser atualizado; OCR pode auxiliar a conferência, mas não substitui essa revisão.

## Mapa seção → fonte

| Seção do site                       | Fonte de verdade                              |
| ----------------------------------- | --------------------------------------------- |
| `/visao-geral/`                     | Curado                                        |
| `/arquitetura/`                     | Curado + diagramas Mermaid                    |
| `/apis/backoffice`                  | `apps/backoffice/README.md`                   |
| `/apis/mcp`                         | `apps/mcp/README.md`                          |
| `/apis/prev-api`                    | `apps/prev-api/README.md`                     |
| `/apis/prev-documentos`             | `apps/prev-documentos/README.md`              |
| `/apis/rmi-api`                     | `apps/rmi-api/README.md`                      |
| `/apps/arquivos-online`             | `apps/arquivos-online/README.md`              |
| `/calculadoras/civeis`              | `apps/civeis/README.md`                       |
| `/calculadoras/prev-atrasados`      | `apps/prev-atrasados/README.md`               |
| `/calculadoras/prev-rpps`           | `apps/prev-rpps/README.md`                    |
| `/calculadoras/prev-rvt`            | `apps/prev-rvt/README.md`                     |
| `/calculadoras/prev-tc`             | `apps/prev-tc/README.md`                      |
| `/calculadoras/prev-utils`          | `apps/prev-utils/README.md`                   |
| `/desenvolvimento/docs-tec`         | Curado                                        |
| `/desenvolvimento/nova-camada-nuxt` | `apps/base/README.md`                         |
| `/pacotes/arquivos-calc`            | `packages/arquivos-calc/README.md`            |
| `/pacotes/calculos-civeis`          | `packages/calculos-civeis/README.md`          |
| `/pacotes/calculos-judiciais`       | `packages/calculos-judiciais/README.md`       |
| `/pacotes/calculos-previdenciarios` | `packages/calculos-previdenciarios/README.md` |
| `/pacotes/calculos-rgps`            | `packages/calculos-rgps/README.md`            |
| `/pacotes/calculos-rpps`            | `packages/calculos-rpps/README.md`            |
| `/pacotes/cliente-geolocalizacao`   | `packages/cliente-geolocalizacao/README.md`   |
| `/pacotes/cliente-pdpj`             | `packages/cliente-pdpj/README.md`             |
| `/pacotes/cliente-sgs`              | `packages/cliente-sgs/README.md`              |
| `/pacotes/cliente-sidra`            | `packages/cliente-sidra/README.md`            |
| `/pacotes/comum`                    | `packages/comum/README.md`                    |
| `/pacotes/html-formatado`           | `packages/html-formatado/README.md`           |
| `/pacotes/indices`                  | `packages/indices/README.md`                  |
| `/pacotes/parsers`                  | `packages/parsers/README.md`                  |
| `/pacotes/servicos-internos`        | `packages/servicos-internos/README.md`        |
| `/pacotes/swagger-nuxt-module`      | `packages/swagger-nuxt-module/README.md`      |
| `/pacotes/test-utils`               | `packages/test-utils/README.md`               |
| `/pacotes/utils`                    | `packages/utils/README.md`                    |
| `/pacotes/vitepress-plugin-mermaid` | `packages/vitepress-plugin-mermaid/README.md` |

## Referência TypeScript local

A documentação automática de tipos é gerada pelo app separado `apps/docs-tipos`. Ela não faz parte do `docs-tec` público e não entra no pipeline de publicação.

```bash
# Gerar HTML do TypeDoc
pnpm --filter @fc/docs-tipos generate

# Gerar e servir localmente (porta 3012)
pnpm --filter @fc/docs-tipos serve

Build completo ​

bash
pnpm --filter @fc/docs-tec build

Adicionando uma nova seção ​

  1. Criar o arquivo .md em apps/docs-tec/site/<secao>/nome.md com frontmatter visibilidade: publico.
  2. Se o conteúdo vem de um README externo: garantir que o README.md do app ou package esteja sanitizado (sem credenciais, rotas privadas ou detalhes operacionais) e adicionar a diretiva @include apontando para ele (ex.: ../../../../apps/prev-tc/README.md). Nunca incluir o CONTEXT.md (interno).
  3. Adicionar a entrada correspondente no sidebar em apps/docs-tec/site/.vitepress/config.ts.
  4. Rodar pnpm docs:lint e pnpm --filter @fc/docs-tec dev antes de abrir PR.