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:openComo 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) // trueClientes 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) // 50Para 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
| Necessidade | Método | Encerramento da operação |
|---|---|---|
| Somar ou multiplicar sem pedir corte | somar(...valores), multiplicar(...valores) | Conversão final para number |
| Resultado monetário | somarMoeda, multiplicarMoeda, dividirMoeda | Truncamento em duas casas e verificação da preservação dos centavos |
| Precisão configurável | somarComPrecisao({ casas }), multiplicarComPrecisao({ casas }) | Fábrica de função com truncamento na precisão escolhida |
| Dividir | dividir(numerador, denominador, casas) | Duas casas se casas for omitido |
| Aplicar uma fração | multiplicarPorRazaoMoeda(valor, numerador, denominador, ...fatores) | Preserva a razão até o corte monetário |
| Cortar um resultado já recebido | truncar(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 serveBuild completo
bash
pnpm --filter @fc/docs-tec buildAdicionando uma nova seção
- Criar o arquivo
.mdemapps/docs-tec/site/<secao>/nome.mdcom frontmattervisibilidade: publico. - Se o conteúdo vem de um README externo: garantir que o
README.mddo app ou package esteja sanitizado (sem credenciais, rotas privadas ou detalhes operacionais) e adicionar a diretiva@includeapontando para ele (ex.:../../../../apps/prev-tc/README.md). Nunca incluir oCONTEXT.md(interno). - Adicionar a entrada correspondente no sidebar em
apps/docs-tec/site/.vitepress/config.ts. - Rodar
pnpm docs:lintepnpm --filter @fc/docs-tec devantes de abrir PR.