ZN/pt

Metodologia

Como construímos, verificamos e mantemos actualizadas as 189 calculadoras do ZN.pt. Esta página descreve o processo em detalhe para que possas avaliar a fiabilidade dos resultados que apresentamos.

Ciclo de construção de uma calculadora

1. Escolha da fórmula

Cada calculadora começa pela identificação da fórmula ou algoritmo oficial. Para cálculos fiscais (IMT, IUC, ISV, IRS, IS, AIMI), consultamos directamente o código legal aplicável (CIMT, CIUC, CISV, CIRS, CIS) e as portarias/circulares em vigor. Para cálculos científicos (IMC, TMB, distância Haversine, cinéticas), usamos fórmulas de referência académica publicadas.

2. Implementação em TypeScript puro

Cada motor de cálculo é escrito como uma função pura em TypeScript, sem dependências de framework. Isto significa: dados os mesmos inputs, o output é sempre o mesmo. Não há efeitos secundários, não há estado interno, não há chamadas de rede. As calculadoras correm inteiramente no browser do utilizador.

3. Validação de inputs

Cada função valida os inputs contra limites razoáveis. Por exemplo, a calculadora de IUC recusa cilindradas negativas ou acima de 10 000 cm³, e a de idade recusa datas de nascimento no futuro. Os erros são retornados como mensagens amigáveis, não como excepções técnicas.

4. Testes automatizados

Cada motor tem testes escritos com Vitest cobrindo casos típicos (input esperado → output correcto), casos-limite (zero, negativos, muito grandes), e casos de erro (validação falha). Actualmente o total ultrapassa 900 testes que correm em cada alteração ao código. Se uma correcção parte outro cálculo, os testes detectam antes do deploy.

5. Cross-check com sites oficiais

Sempre que possível, os resultados são cruzados com simuladores oficiais das entidades relevantes (Portal das Finanças AT, Simulador de Crédito do BdP, Simulador de Pensões da SS, etc.). Divergências significativas são investigadas antes da publicação.

6. Explicação e enquadramento

Cada tool page tem uma secção "Guia detalhado" com 700-1000 palavras explicando: como se calcula, a fórmula usada, exemplo prático com números reais portugueses, contexto legal, erros comuns, e referências. Isto permite ao utilizador auditar mentalmente o resultado.

Fontes primárias utilizadas

Para conteúdo fiscal e legal em Portugal, as fontes oficiais em que baseamos as calculadoras incluem:

  • Autoridade Tributária e Aduaneira (AT) — portaldasfinancas.gov.pt — tabelas IRS, códigos fiscais, portarias
  • Segurança Social (ISS) — seg-social.pt — valores IAS, cotizações, subsídios
  • Banco de Portugal (BdP) — bportugal.pt — Aviso 4/2018 (DSTI), taxas de referência
  • IEFP — iefp.pt — subsídio desemprego, bolsas estágio Ativar
  • IHRU — portaldahabitacao.pt — programas habitação
  • INE — ine.pt — IPC (inflação), coeficientes actualização rendas
  • Diário da República — dre.pt — legislação primária
  • DGS — orientações clínicas (tensão arterial, IMC, alcoolemia)
  • EFSA — limites nutricionais (cafeína, etc.)
  • OMS — critérios de saúde de referência

Ciclo de actualização anual

Todos os valores fiscais e legais são revistos anualmente entre 1 de Janeiro e 15 de Fevereiro, quando o Orçamento do Estado entra em vigor e as portarias anuais são publicadas. O processo tem 5 fases:

  1. Grep automático — script ./scripts/check-fiscal.sh lista todos os valores fiscais hardcoded no código, para revisão manual
  2. Consulta OE + Diário da República — identificar mudanças em IAS, SMN, escalões IRS, tabelas IMT/IUC/ISV, subsídios
  3. Actualização de tabelas versionadas — ficheiros tipo data/irs-tables-2026.ts são clonados para o novo ano, mantendo o histórico
  4. Re-execução da suite de testes — 900+ testes correm com os novos valores, detectando regressões
  5. Actualização dos textos MDX — explicações longas são revistas para reflectir o novo ano e valores

Correcções e feedback

Erros acontecem. Se detectas um valor desactualizado, uma fórmula incorrecta, ou uma situação particular (isenção, benefício, excepção) mal tratada, envia mensagem para ola@zn.pt. Correcções materiais costumam ser aplicadas na semana seguinte e as páginas afectadas passam a mostrar a nova data de "última revisão".

Limitações declaradas

As calculadoras são simplificações para casos típicos. Casos-limite frequentemente exigem consulta a profissional:

  • Situações fiscais especiais (residente não habitual, sujeição parcial, benefícios fiscais específicos)
  • Créditos com condições particulares (spread negociado, seguros associados, moratórias)
  • Enquadramento laboral misto (contrato prazo + independente + rendimentos categoria E)
  • Deduções à colecta com majorações regionais (interior)

Cada calculadora indica no fim quando o resultado é aproximação e o utilizador deve consultar fonte oficial ou profissional habilitado.