Dashboard Financeiro Inteligente - Documentação Técnica (v1.1)

1. Visão Geral

O Dashboard Financeiro Inteligente é uma Single-Page Application (SPA) desenvolvida em HTML, CSS e JavaScript puro. Opera inteiramente no lado do cliente (client-side), sem backend. Dados do usuário são persistidos no localStorage do navegador, garantindo privacidade e funcionamento offline.

Tecnologias:

• HTML5
• Bootstrap 5.3.3
• Chart.js
• jsPDF
• html2canvas
• JavaScript (ES6)

2. Arquitetura do Código

A aplicação reside em um único arquivo, index.html, dividido em:

• Estrutura HTML (<body>): Elementos visíveis da UI.
• Estilização CSS (<style>): Tema (claro/escuro) e estilos customizados.
• Lógica JavaScript (<script>): Gestão de estado, manipulação do DOM e lógica das ferramentas.

3. Estrutura HTML

A interface é modularizada em divs exibidas/ocultadas conforme a navegação (seções #home, #calculadora-renda-passiva, etc.), além de modais, menu e cabeçalho.

4. Lógica da Aplicação (JavaScript)

4.1. Estado Global e Inicialização

A aplicação é centralizada no objeto appState, armazenado no localStorage. A função init() orquestra a inicialização e carregamento dos dados.

4.2. Gerenciamento de Dados e Persistência

As funções loadState() e saveState() gerenciam a leitura e escrita do appState no localStorage. A lógica de consentimento (handleConsent) controla a persistência de dados.

4.3. Navegação e UI

A função showSection() controla a visibilidade das divs de conteúdo.

4.4. Funcionalidades Principais e Detalhamento dos Cálculos

4.4.1. Ferramenta: Controle de Despesas (#controle-despesas)

Função Principal de Renderização: renderBudgetsUI()

Cálculos:

• Agregação de Totais: Utiliza filter e reduce em transactions para calcular totais de receitas e despesas.

// Cálculo do total de receitas
const totalReceitas = (currentMonthData.transactions || [])
    .filter(t => t.type === 'receita')
    .reduce((sum, t) => sum + t.value, 0);

// Cálculo do total de despesas
const totalDespesas = (currentMonthData.transactions || [])
    .filter(t => t.type === 'despesa')
    .reduce((sum, t) => sum + t.value, 0);

• Cálculo do Saldo: saldoMes = totalReceitas - totalDespesas;

• Cálculo do Progresso do Orçamento: Calcula o percentual do orçamento consumido por categoria.

const totalSpent = (currentMonthData.transactions || [])
    .filter(t => t.category === budget.name && t.type === 'despesa')
    .reduce((sum, t) => sum + t.value, 0);

const percentage = budget.limit > 0 ? (totalSpent / budget.limit) * 100 : 0;

4.4.2. Ferramenta: Projeção de Renda Passiva (#calculadora-renda-passiva)

Função Principal de Cálculo: gerarProjecao()

Cálculos:

• Juros Compostos Anuais: Utiliza um loop for para 30 anos, aplicando a fórmula:

valorFinalAcumulado = (valorFinalAcumulado + aporteAnual) * (1 + (rendimentoAplicacoes / 100));

• Cálculo da Renda Passiva Potencial: Baseado na Taxa de Retirada Segura.

const rendaPassivaAnual = valorFinalAcumulado * (taxaRetirada / 100);
const rendaPassivaMensal = rendaPassivaAnual / 12;

• Verificação do Objetivo: Compara rendaPassivaMensal com objetivoRendaPassiva.

4.4.3. Ferramenta: Diagnóstico Financeiro (#calculo-inteligente)

Função Principal de Cálculo: gerarDiagnostico()
Função Auxiliar: calculateMonthTotals(monthData)

Cálculos:

• Agregação de Dados por Categoria (calculateMonthTotals): Classifica transações como ‘receita’, ‘necessidade’ ou ‘desejo’.
• Cálculo dos Totais do Período (gerarDiagnostico): Agrega totais usando calculateMonthTotals.
• Métricas Financeiras Chave: Percentuais da Regra 50/30/20 e DTI (Relação Dívida/Renda). Exemplos:

// Percentual da renda gasto em necessidades
const percNecessidades = (totalNecessidades / totalReceitas) * 100;

// DTI
const dti = (totalDividas / avgReceitas) * 100;

• Geração Condicional do Relatório (getDiagnosisHTML): Gera um plano de ação baseado em condicionais (if).

if (data.dti > 35) {
    dicas.dividas.push({tipo: 'danger', texto: 'Seu nível de endividamento é perigosamente alto...'});
}