{
  "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"
  ],
  "sourceRefs": [
    "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"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Visão Geral\n\nO **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.\n\n## Fluxo de Processamento (Motor)\n\nO 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:\n\n{{diagram:finance-dashboard-flow}}\n\n## Regras de Negócio e Componentes\n\n### Indicadores KPI (Liquidez e Saldos)\nO serviço consolida quatro indicadores principais baseados no \"aqui e agora\":\n1. **Saldo Líquido (Net Balance)**: `Saldo de Contas - Dívidas Abertas (Faturas Cartão) - Despesas Pendentes de outras fontes`.\n2. **Saldo Bruto**: Simples soma do patrimônio nas contas correntes/investimentos configurados.\n3. **Receitas**: Total efetivado no mês.\n4. **Despesas**: Total efetivado no mês.\n\n*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.\n\n### Projeção de Fluxo de Caixa (Mês Vigente e Seguinte)\nEsta funcionalidade consolida transações reais postadas, transações reais pendentes e **transações virtuais geradas a partir de recorrências ativas**.\nO algoritmo de extrapolação (`getCashFlowProjections`):\n1. Captura o saldo em conta corrente atual.\n2. Soma as `incomes` pendentes e `incomes` oriundos de recorrências do mês atual.\n3. Subtrai as `expenses` pendentes, o montante devido em Faturas de Cartão e `expenses` oriundos de recorrências do mês atual.\n4. Retorna a previsão de Saldo Final para o Mês Atual.\n5. 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.\n\n### James Radar (O que vem a seguir)\nO **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.\nPara fazer isso, ele constrói uma coleção híbrida, instanciando classes em memória:\n- **Transações Pendentes reais** (exclui transferências).\n- **Recorrências Ativas** cujo `next_processing_date` está no intervalo.\n- **Faturas de Cartão Abertas** cujos dias de vencimento estão no intervalo.\n\nTodas 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.\n\n### Controles Otimizados de Fatura\nO 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`).",
  "sections": [
    {
      "id": "visao-geral",
      "level": 2,
      "title": "Visão Geral",
      "text": "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.",
      "line": 1
    },
    {
      "id": "fluxo-de-processamento-motor",
      "level": 2,
      "title": "Fluxo de Processamento (Motor)",
      "text": "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:",
      "line": 5
    },
    {
      "id": "regras-de-negocio-e-componentes",
      "level": 2,
      "title": "Regras de Negócio e Componentes",
      "text": "",
      "line": 11
    },
    {
      "id": "indicadores-kpi-liquidez-e-saldos",
      "level": 3,
      "title": "Indicadores KPI (Liquidez e Saldos)",
      "text": "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.",
      "line": 13
    },
    {
      "id": "projecao-de-fluxo-de-caixa-mes-vigente-e-seguinte",
      "level": 3,
      "title": "Projeção de Fluxo de Caixa (Mês Vigente e Seguinte)",
      "text": "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.",
      "line": 22
    },
    {
      "id": "james-radar-o-que-vem-a-seguir",
      "level": 3,
      "title": "James Radar (O que vem a seguir)",
      "text": "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.",
      "line": 31
    },
    {
      "id": "controles-otimizados-de-fatura",
      "level": 3,
      "title": "Controles Otimizados de Fatura",
      "text": "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`).",
      "line": 40
    }
  ],
  "sourcePath": "content/painel-financeiro.md",
  "visuals": [
    {
      "id": "finance-dashboard-flow",
      "kind": "flowchart",
      "title": "Processamento do painel financeiro",
      "description": "O painel reúne fontes financeiras e calcula indicadores e projeções.",
      "summary": "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.",
      "renderMode": "mermaid",
      "api": "api/diagrams/finance-dashboard-flow.json",
      "human": "diagrams/finance-dashboard-flow.html"
    }
  ],
  "apiVersion": 1
}