@fc/comum

Entidades, contratos e vocabulário compartilhados por todas as apps e packages da Fábrica de Cálculos. Depende apenas de @fc/utils.

Antes de criar uma função nova

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

Use @fc/comum para código compartilhável que conheça o domínio da Fábrica de Cálculos: contratos de API, mensagens padronizadas, registro de apps/calculadoras, telemetria, entidades e enums de negócio. Funções puramente técnicas e agnósticas em relação ao domínio devem ficar em @fc/utils.

Mantenha a função local ao app ou layer apenas quando ela representar uma regra realmente específica daquele contexto.

Módulos

O pacote não tem barrel: cada módulo é uma pasta publicada por wildcard no exports ("./servidor/*": "./src/servidor/*.ts"), e o consumidor importa o arquivo que declara o símbolo — import { responder } from '@fc/comum/servidor/envelope/responder', nunca @fc/comum.

Módulo	Conteúdo
api	Envelope de resposta de toda a superfície de API (RespostaApi, RespostaPaginadaApi em api/tipos), mensagens HTTP amigáveis (api/mensagens), extrairCodigoErroApi, extrairMensagemErroApi e a rede transitória de proteção do contrato de datas (normalizarDatasContratoApi, ADR 0004)
apiKeys	Política de consumo da API pública: classes de consumidor, cotas, escopos, status de solicitação (apiKeys/constantes, apiKeys/tipos) e nomePadraoChaveApi
apps	Registro das apps (apps/registroApps), caminhos públicos e documentações do portal (apps/urlsPublicas, apps/constantes), identificação de Arquivos online (apps/arquivosOnline)
compartilhamento	Gramática dos tokens opacos de links públicos e permalinks (ehTokenCompartilhamento)
entidades	Entidade, Id, IdUniversal, Competencia, Colecao, Memo, TalvezSequencial — um arquivo por classe
enums	HealthStatus, OpcaoEnum<T> e os utilitários de opções (obterOpcoesEnum, obterOpcoesEnumString) que preservam valores numéricos ou textuais
openapi	descricaoComVersoes e lerCsvDeGlobs
servidor	Só servidor. Contexto de requisição, logger correlacionado, logger JSON de servidor (criarLoggerJson: uma linha por evento em execução empacotada, identado só no nuxt dev), construtores do envelope (servidor/envelope/*), rate limit (servidor/rateLimit/*), leitura limitada de corpo JSON, resolução de id e IP do cliente, decodificação repetida de caminho (caminhoDecodificado, ex-@fc/utils/http)
uso	Vocabulário de telemetria: dicionários de ações e origens (uso/constantes), tipos de payload (uso/tipos) e validações (uso/validacao)
ambienteInterface	Arquivo de raiz (@fc/comum/ambienteInterface): aviso visual de ambiente não produtivo

OpcaoEnum<T> exige que cada consumidor declare o tipo textual ou numérico de valor. Os produtores obterOpcoesEnum e obterOpcoesEnumString inferem esse tipo diretamente do dicionário recebido, inclusive quando a chamada seleciona apenas um subconjunto por filtro.

API

O módulo api centraliza o envelope de resposta e as mensagens HTTP amigáveis em português. Use mensagemHttpAmigavel para mapear status HTTP conhecidos para texto de interface e traduzirMensagemHttpPadrao para traduzir mensagens padrão em inglês vindas de frameworks HTTP.

import { mensagemHttpAmigavel, traduzirMensagemHttpPadrao } from '@fc/comum/api/mensagens'

const mensagem404 = mensagemHttpAmigavel(404)
const mensagemTraduzida = traduzirMensagemHttpPadrao('Not Found')

Os construtores do envelope (responder, responderErro, responderEmProgresso, responderPaginado) ficam em servidor/envelope/ e são funções puras, sem dependência de framework HTTP.

import { responder } from '@fc/comum/servidor/envelope/responder'

Registro de apps

O módulo apps expõe o registro interno dos apps da Fábrica de Cálculos. O ID canônico de negócio usa o formato dominio.funcao (rgps.beneficios, rgps.atrasados, rgps.utils, rgps.rvt, rpps.beneficios), enquanto aliases legados como @fc/prev-tc são aceitos apenas para leitura/importação.

O campo categoria diferencia calculadoras de utilidades. O campo ativa define quais apps sobem no ambiente local coordenado (pnpm dev:local). O campo portal define quais apps aparecem na landing pública do PDPJ. Apps inativos continuam no registro para leitura de arquivos, dados antigos e aliases legados.

Como resolver uma app

1. A app é conhecida em tempo de compilação? → acesso estrutural por APPS. Não escreva o literal 'rgps.beneficios' fora de registroApps.ts: a string não quebra quando a entrada sai do registro, a propriedade quebra.
2. É o app.config.ts ou o nuxt.config.ts da própria app declarando a identidade dela? → obterAppPorPacote(name), com name importado do package.json ao lado. Não use APPS.X aqui: a graça é que o package.json já é a fonte, e repetir a chave repete o erro que se quer evitar.
3. O valor chegou em runtime? (campo app de um .calc, payload de API, useAppConfig().idApp, nome lido de disco) → obterAppPorIdentificador(valor), que devolve undefined e obriga a tratar. Aceita id, pacote e aliases legados — é a porta de leitura de dado antigo.
4. Só preciso do id canônico, sem tocar no resto da entrada → normalizarIdApp(valor).

Combinar 3 e 4 no mesmo caminho — normalizar e depois buscar a entrada pelo id — é buscar duas vezes: use obterAppPorIdentificador e leia o .id dela.

import { APPS, APPS_CATALOGO_CALCULADORAS, APPS_REGISTRADOS_ATIVOS, IDS_APPS_ONLINE, obterAppPorIdentificador, obterAppPorPacote } from '@fc/comum/apps/registroApps'

const civeis = APPS.CIVEIS                                   // app conhecida em compilação
const propria = obterAppPorPacote(name)                      // identidade da própria app, pelo package.json
const doArquivo = obterAppPorIdentificador(arquivo.calculo)  // valor de runtime, pode não existir
const appsAtivos = APPS_REGISTRADOS_ATIVOS
const catalogoCalculadoras = APPS_CATALOGO_CALCULADORAS
const idsAppsComPersistenciaOnline = IDS_APPS_ONLINE

Telemetria de uso

O módulo uso expõe o contrato compartilhado de telemetria. DICIONARIO_ACOES_USO é a fonte canônica das ações, com rótulo, descrição, recurso, ambiente e forma/operação quando aplicável. ACOES_USO_VALIDAS é derivado das chaves desse dicionário para validação em APIs e proxies. As origens de calculadoras são derivadas de APPS_REGISTRADOS; produtores que não pertencem a esse catálogo ficam numa lista explícita. validarAcaoUsoDaOrigem impede que uma origem declare ações de outro produto.

Para cálculos salvos, produtores novos usam ações semânticas de criação (rgps.calculos-salvos.web.criar e usuario.grupos.web.calculo-criar); as ações antigas de salvar permanecem apenas para leitura histórica. Downloads .calc usam rgps.arquivos-calc.web.baixar e podem incluir idEventoCliente para deduplicação de retentativas. Metadados com chaves de CPF de terceiro ou nome civil são recusados na entrada e removidos defensivamente antes da persistência.

import { ACOES_USO_VALIDAS, DICIONARIO_ACOES_USO } from '@fc/comum/uso/constantes'
import type { AcaoUso } from '@fc/comum/uso/tipos'

const descricao = DICIONARIO_ACOES_USO['rgps.beneficios.web']
const acoes: readonly AcaoUso[] = ACOES_USO_VALIDAS

Tokens de compartilhamento

O módulo compartilhamento define a gramática comum dos identificadores opacos usados por links públicos e permalinks: 32 bytes aleatórios codificados em base64url, sem padding, resultando em exatamente 43 caracteres. ehTokenCompartilhamento() é o validador canônico para bordas de interface e servidor; o token identifica um registro persistido e não carrega assinatura nem conteúdo decodificável.

Ambiente de interface

obterMensagemAmbienteInterface centraliza a redação do aviso visual exibido quando uma interface roda em dev ou stg. Valores prod, vazios ou desconhecidos não exibem mensagem. Para builds que exigem declaração explícita de ambiente, use exigirAmbienteInterface.

import { exigirAmbienteInterface, obterMensagemAmbienteInterface } from '@fc/comum/ambienteInterface'

const ambiente = exigirAmbienteInterface('prod')
const mensagem = obterMensagemAmbienteInterface('dev')

Instalação (monorepo)

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