---
id: painel-financeiro
title: Painel financeiro
description: Indicadores de liquidez, projeções e controles do módulo financeiro.
type: feature
status: observed
visibility: public
tags: finanças, dashboard, echarts
related: financas, contas-financeiras, transacoes, relatorios
source_refs: https://github.com/james-suite/james/blob/master/app/Http/Controllers/FinanceDashboardController.php, https://github.com/james-suite/james/blob/master/app/Http/Controllers/FinanceDashboardChartController.php, https://github.com/james-suite/james/blob/master/routes/financial.php
---

## Visão Geral

O **Dashboard** atua como a central nervosa diária do usuário (`FinanceDashboardService`). Ele foca no tempo presente, fornecendo uma visão instantânea da liquidez e do que está prestes a acontecer nos próximos dias. Ele centraliza informações complexas utilizando consultas otimizadas e lógica de projeção.

## Fluxo de Processamento (Motor)

O serviço do Dashboard utiliza uma estratégia de agregação que coleta dados de diversas origens (Tabelas) para fornecer uma resposta rápida à interface:

> **Diagrama: Processamento do painel financeiro**
> O painel reúne fontes financeiras e calcula indicadores e projeções.
> Leitura semântica: O controller solicita dados ao serviço do painel; a coleta reúne contas, cartões, faturas e transações antes de calcular projeções, KPIs e o James Radar.
> Fonte semântica: `diagrams/finance-dashboard-flow.json`
> Fonte declarativa: `diagrams/sources/finance-dashboard-flow.mmd`

## Regras de Negócio e Componentes

### Indicadores KPI (Liquidez e Saldos)
O serviço consolida quatro indicadores principais baseados no "aqui e agora":
1. **Saldo Líquido (Net Balance)**: `Saldo de Contas - Dívidas Abertas (Faturas Cartão) - Despesas Pendentes de outras fontes`.
2. **Saldo Bruto**: Simples soma do patrimônio nas contas correntes/investimentos configurados.
3. **Receitas**: Total efetivado no mês.
4. **Despesas**: Total efetivado no mês.

*Nota:* O usuário possui a opção (`includeInvestments`) de somar ou remover contas do tipo "Investimento" deste cálculo, para isolar a liquidez do dia-a-dia do dinheiro imobilizado.

### Projeção de Fluxo de Caixa (Mês Vigente e Seguinte)
Esta funcionalidade consolida transações reais postadas, transações reais pendentes e **transações virtuais geradas a partir de recorrências ativas**.
O algoritmo de extrapolação (`getCashFlowProjections`):
1. Captura o saldo em conta corrente atual.
2. Soma as `incomes` pendentes e `incomes` oriundos de recorrências do mês atual.
3. Subtrai as `expenses` pendentes, o montante devido em Faturas de Cartão e `expenses` oriundos de recorrências do mês atual.
4. Retorna a previsão de Saldo Final para o Mês Atual.
5. Usa essa previsão como base e repete o processo 2-3 para o Mês Seguinte, retornando a Previsão do Próximo Mês.

### James Radar (O que vem a seguir)
O **James Radar** é o assistente inteligente que lista as próximas obrigações e receitas em ordem cronológica a partir de "Hoje" até os próximos 30 dias.
Para fazer isso, ele constrói uma coleção híbrida, instanciando classes em memória:
- **Transações Pendentes reais** (exclui transferências).
- **Recorrências Ativas** cujo `next_processing_date` está no intervalo.
- **Faturas de Cartão Abertas** cujos dias de vencimento estão no intervalo.

Todas essas entidades assumem um "formato de pato" (`duck typing`), atuando perante a UI como se fossem Transações normais pendentes, facilitando a renderização na tabela sem código duplicado na View.

### Controles Otimizados de Fatura
O cálculo de qual fatura o usuário deve ver no Dashboard (`resolveReferenceMonth`) não bate no banco de dados para buscar a melhor data; ele usa lógica pura computando dias de fechamento (`closing_day`) em relação a hoje e injeta dinamicamente o status e total diretamente no model retornado (`card->current_invoice_total`).