{
  "id": "relatorios",
  "title": "Relatórios",
  "description": "Consultas de longo prazo e visualizações do fluxo financeiro em regime de caixa.",
  "type": "feature",
  "status": "observed",
  "visibility": "public",
  "tags": [
    "finanças",
    "relatórios",
    "echarts"
  ],
  "related": [
    "financas",
    "painel-financeiro",
    "transacoes",
    "tags-financeiras"
  ],
  "sourceRefs": [
    "https://github.com/james-suite/james/blob/master/app/Services/ReportsService.php",
    "https://github.com/james-suite/james/blob/master/app/Http/Controllers/ReportsController.php"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Visão Geral\n\nO Módulo de **Relatórios** (`ReportsService`) fornece visualizações profundas do passado financeiro para auditoria, e do futuro para planejamento. Ao contrário do Dashboard, que consolida apenas os 30 dias presentes, os relatórios são desenhados para suportar queries de longo prazo (anos) e aplicar achatamentos (`flattening`) avançados para gerar gráficos compreensivos (Sankey, Evolução de Saldo em Regime de Caixa, Análise de Tags com Drill-down).\n\n## Arquitetura de Coleta (`getUnifiedTransactions`)\n\nO núcleo motor dos relatórios é o método unificador. Para evitar problemas de formatação múltipla e inconsistências, o sistema condensa o passado e o futuro em um único tubo de dados, mesclando:\n1. **Transações Reais**: O histórico concreto do banco de dados (respeitando filtros de contas, período e tags).\n2. **Transações Virtuais**: Instancia e \"rebobina\" a lógica das Recorrências ativas até a data de início do filtro, projetando datas futuras com a periodicidade adequada (`weekly`, `monthly`, `yearly`).\n\nEssa coleção híbrida abastece todos os métodos subsequentes (gráficos), eliminando a necessidade de recalcular projeções de banco de dados para cada gráfico.\n\n## Relatórios e Gráficos Gerados\n\n### 1. Diagrama de Sankey (Fluxo de Dinheiro)\nIlustra de forma orgânica de onde veio e para onde foi o dinheiro no período especificado:\n- **Achatamento de Itens (`flattenTransactionsForTags`)**: Para que uma única despesa em mercado possa refletir, por exemplo, R$50 de \"Açougue\", R$30 de \"Limpeza\" e R$20 de \"Bebidas\" (quebrando a transação através da tabela `financial_transaction_items`), o sistema expande cada item em uma pseudo-transação própria conectada ao *node* central. O resíduo fica associado à tag principal.\n- **Lógica de Construção**: Agrupa despesas e receitas pela Tag Primária e conecta tudo a um Nodo central (\"Fluxo de Caixa\"). Também integra o Saldo Anterior (antes do período) e resulta em um Nodo Final (\"Saldo Líquido\" ou \"Uso de Reservas/Déficit\").\n\n### 2. Evolução de Saldo e Caixa (Regime de Caixa)\nConstrói gráficos de linha/área cumulativos alinhados estritamente ao **Regime de Caixa** (quando o dinheiro efetivamente entrou ou saiu das contas):\n- **Interpolação de Datas**: Independentemente de não haverem registros em um dia/mês, o sistema gera o array cobrindo todos os espaços do intervalo (`interval = daily, weekly, monthly, yearly`) para manter a continuidade do eixo X.\n- **Tratamento de Cartão de Crédito**: Para faturas quitadas, a dedução de saldo ocorre na data exata do pagamento (`paid_at`). Para faturas futuras ou abertas, o impacto é projetado na data de vencimento (`due_date`).\n\n### 3. Análise de Tags e Drill-down Dinâmico\nAgrega a coleção de transações unificadas e fatiadas (`flattened`), fornecendo:\n- O total geral de Gastos vs Receitas no período selecionado.\n- Gastos concentrados agrupados pela Tag Primária (gráfico de pizza / donut e barras).\n- **Drill-down Interativo**: Ao selecionar tags específicas no filtro superior, tanto a tabela analítica de transações quanto os gráficos convergem instantaneamente para o conjunto fatiado, permitindo auditar o fluxo de micro-categorias.\n- **Net Tags (Tags Líquidas)**: Consolida o fluxo líquido de tags que possuem entradas e saídas simultâneas (ex: \"Freelance\", \"Viagem\", \"Reembolso\").\n\n## Filtros e Escopos Inteligentes\n\n### Isolamento de Investimentos\nO usuário pode optar por incluir ou excluir contas do tipo \"Investimento\". Ao ativar a exclusão:\n- Transações diretas em contas de investimento são removidas.\n- Transferências enviadas para corretoras são tratadas como alocação de capital e filtradas sem distorcer o fluxo de despesas de consumo do dia a dia.\n\n### Pagamentos Parciais e Transferências Internas\nTransações associadas a `PAGAMENTO_PARCIAL_ID` ou `TRANSFERENCIA_ID` são expurgadas dos cálculos de Evolução de Saldo para evitar contagem dupla de patrimônio (já que uma transferência entre contas correntes não gera riqueza nem custo real).",
  "sections": [
    {
      "id": "visao-geral",
      "level": 2,
      "title": "Visão Geral",
      "text": "O Módulo de **Relatórios** (`ReportsService`) fornece visualizações profundas do passado financeiro para auditoria, e do futuro para planejamento. Ao contrário do Dashboard, que consolida apenas os 30 dias presentes, os relatórios são desenhados para suportar queries de longo prazo (anos) e aplicar achatamentos (`flattening`) avançados para gerar gráficos compreensivos (Sankey, Evolução de Saldo em Regime de Caixa, Análise de Tags com Drill-down).",
      "line": 1
    },
    {
      "id": "arquitetura-de-coleta-getunifiedtransactions",
      "level": 2,
      "title": "Arquitetura de Coleta (getUnifiedTransactions)",
      "text": "O núcleo motor dos relatórios é o método unificador. Para evitar problemas de formatação múltipla e inconsistências, o sistema condensa o passado e o futuro em um único tubo de dados, mesclando: 1. **Transações Reais**: O histórico concreto do banco de dados (respeitando filtros de contas, período e tags). 2. **Transações Virtuais**: Instancia e \"rebobina\" a lógica das Recorrências ativas até a data de início do filtro, projetando datas futuras com a periodicidade adequada (`weekly`, `monthly`, `yearly`).  Essa coleção híbrida abastece todos os métodos subsequentes (gráficos), eliminando a necessidade de recalcular projeções de banco de dados para cada gráfico.",
      "line": 5
    },
    {
      "id": "relatorios-e-graficos-gerados",
      "level": 2,
      "title": "Relatórios e Gráficos Gerados",
      "text": "",
      "line": 13
    },
    {
      "id": "1-diagrama-de-sankey-fluxo-de-dinheiro",
      "level": 3,
      "title": "1. Diagrama de Sankey (Fluxo de Dinheiro)",
      "text": "Ilustra de forma orgânica de onde veio e para onde foi o dinheiro no período especificado: - **Achatamento de Itens (`flattenTransactionsForTags`)**: Para que uma única despesa em mercado possa refletir, por exemplo, R$50 de \"Açougue\", R$30 de \"Limpeza\" e R$20 de \"Bebidas\" (quebrando a transação através da tabela `financial_transaction_items`), o sistema expande cada item em uma pseudo-transação própria conectada ao *node* central. O resíduo fica associado à tag principal. - **Lógica de Construção**: Agrupa despesas e receitas pela Tag Primária e conecta tudo a um Nodo central (\"Fluxo de Caixa\"). Também integra o Saldo Anterior (antes do período) e resulta em um Nodo Final (\"Saldo Líquido\" ou \"Uso de Reservas/Déficit\").",
      "line": 15
    },
    {
      "id": "2-evolucao-de-saldo-e-caixa-regime-de-caixa",
      "level": 3,
      "title": "2. Evolução de Saldo e Caixa (Regime de Caixa)",
      "text": "Constrói gráficos de linha/área cumulativos alinhados estritamente ao **Regime de Caixa** (quando o dinheiro efetivamente entrou ou saiu das contas): - **Interpolação de Datas**: Independentemente de não haverem registros em um dia/mês, o sistema gera o array cobrindo todos os espaços do intervalo (`interval = daily, weekly, monthly, yearly`) para manter a continuidade do eixo X. - **Tratamento de Cartão de Crédito**: Para faturas quitadas, a dedução de saldo ocorre na data exata do pagamento (`paid_at`). Para faturas futuras ou abertas, o impacto é projetado na data de vencimento (`due_date`).",
      "line": 20
    },
    {
      "id": "3-analise-de-tags-e-drill-down-dinamico",
      "level": 3,
      "title": "3. Análise de Tags e Drill-down Dinâmico",
      "text": "Agrega a coleção de transações unificadas e fatiadas (`flattened`), fornecendo: - O total geral de Gastos vs Receitas no período selecionado. - Gastos concentrados agrupados pela Tag Primária (gráfico de pizza / donut e barras). - **Drill-down Interativo**: Ao selecionar tags específicas no filtro superior, tanto a tabela analítica de transações quanto os gráficos convergem instantaneamente para o conjunto fatiado, permitindo auditar o fluxo de micro-categorias. - **Net Tags (Tags Líquidas)**: Consolida o fluxo líquido de tags que possuem entradas e saídas simultâneas (ex: \"Freelance\", \"Viagem\", \"Reembolso\").",
      "line": 25
    },
    {
      "id": "filtros-e-escopos-inteligentes",
      "level": 2,
      "title": "Filtros e Escopos Inteligentes",
      "text": "",
      "line": 32
    },
    {
      "id": "isolamento-de-investimentos",
      "level": 3,
      "title": "Isolamento de Investimentos",
      "text": "O usuário pode optar por incluir ou excluir contas do tipo \"Investimento\". Ao ativar a exclusão: - Transações diretas em contas de investimento são removidas. - Transferências enviadas para corretoras são tratadas como alocação de capital e filtradas sem distorcer o fluxo de despesas de consumo do dia a dia.",
      "line": 34
    },
    {
      "id": "pagamentos-parciais-e-transferencias-internas",
      "level": 3,
      "title": "Pagamentos Parciais e Transferências Internas",
      "text": "Transações associadas a `PAGAMENTO_PARCIAL_ID` ou `TRANSFERENCIA_ID` são expurgadas dos cálculos de Evolução de Saldo para evitar contagem dupla de patrimônio (já que uma transferência entre contas correntes não gera riqueza nem custo real).",
      "line": 39
    }
  ],
  "sourcePath": "content/relatorios.md",
  "visuals": [],
  "apiVersion": 1
}