# Documentação técnica — Dashboards e extrato (movimentação)

**Última atualização:** 2026-06-08 — DFC/DRE gerenciais, middleware `plano.funcionalidade`, ajuda contextual (?).

Este documento descreve **todas as telas de dashboard** expostas em `routes/web.php`, os **controllers**, **views**, componentes **Livewire** associados, o **extrato por período**, o **DFC** (fluxo de caixa por hierarquia) e a **DRE gerencial** (drill-down contábil). Complementa **`Doc_Modulo_Financeiro.md`** (NF/parcelas, cartão, transferências) e **`Doc_Modulo_Produto_Servico.md`** (classificação DRE/DFC no catálogo).

**Índice geral:** **`Doc_INDICE.md`**.

**Middleware:** em geral `auth` + `single.session` (mesmo padrão do painel).

---

## 1. Mapa de rotas e nomes

| Rota GET | Nome da rota | Controller / destino | View principal |
|----------|--------------|----------------------|----------------|
| `/dashboard` | `dashboard` | `DashboardController@index` | `dashboard.index` — **Visão geral** |
| `/dashboardfinanceiro` | `dashboardfinanceiro` | `DashboardController@index` | **Mesma** que `/dashboard` (duplicata de URL) |
| `/dashboard/financeiro` | `dashboard.financeiro` | `DashboardFinanceiroController@index` | `dashboard.financeiro` — **Financeiro legado** (KPIs / DRE por texto) |
| `/dashboard/movimentacao` | `dashboard.movimentacao.index` | `DashboardMovimentacaoController@index` | Redireciona para busca com período padrão |
| `/dashboard/movimentacao/procurar` | `dashboard.movimentacao.search` | `DashboardMovimentacaoController@search` | `dashboard.movimentacao` — **Extrato + gráficos** |
| `/dashboard/dfc` | `dashboard.dfc.index` | `DashboardDfcController@index` | Redireciona para busca com período padrão |
| `/dashboard/dfc/procurar` | `dashboard.dfc.search` | `DashboardDfcController@search` | `dashboard.dfc` — **DFC** (FCO/FCI/FCF). Middleware **`plano.funcionalidade:dfc_gerencial`**. |
| `/dashboard/dre` | `dashboard.dre.index` | `DashboardDreController@index` | Redireciona para busca com período padrão |
| `/dashboard/dre/procurar` | `dashboard.dre.search` | `DashboardDreController@search` | `dashboard.dre` — **DRE gerencial** (hierarquia + `linhadre`). Middleware **`plano.funcionalidade:dre_gerencial`**. |
| `/dashboard/produto` | `dashboard.produto` | Closure | `dashboard.produto` |
| `/dashboard/evento` | `dashboard.evento` | Closure | `dashboard.evento` |
| `/dashboard/tags` | `dashboard.tags` | Closure | `dashboard.tags` |
| `/dashboard/veiculo` | `dashboard.veiculo.index` | `DashboardVeiculoController@index` | `dashboard.veiculo` |
| `/dashboard/veiculo/procurar` | `dashboard.veiculo.search` | `DashboardVeiculoController@search` | `dashboard.veiculo` |
| `/dashboard/veiculocusto` | `dashboard.veiculocusto.index` | `DashboardVeiculoCustoController@index` | `dashboard.veiculocusto` |
| `/dashboard/veiculocusto/procurar` | `dashboard.veiculocusto.search` | `DashboardVeiculoCustoController@search` | `dashboard.veiculocusto` |
| `/dashboard/campanha/ranking` | `dashboard.campanha.ranking` | `DashboardRankingCampanha@index` | `dashboard.campanha` |
| `/admin/tenants/dashboard` | `admin.tenants.dashboard` | `DashboardTenantController` + `DashboardAssinaturaService` | `admin.tenants.dashboard` — **Assinaturas SaaS** (somente `contrato.modalidade = RECORRENCIA`) |

Detalhes do painel operador: **`Doc_Modulo_Assinatura_Contrato.md`** § 4. Contratos comerciais: **`Doc_Modulo_Contrato.md`**.

---

## 2. Visão geral — `DashboardController` (`/dashboard`)

**Arquivo:** `app/Http/Controllers/DashboardController.php`  
**View:** `resources/views/dashboard/index.blade.php`

**Fonte de dados:** **`nfparcela`** com **`join` em `nf`** e **`nf.saida <> 'P'`** (exclui NF de **pedido**), alinhado ao extrato de movimentação e aos dashboards financeiro/movimentação.

`parcelasDashboardQuery($tipo, $statuses)` aplica esse join e filtro em todas as agregações que a utilizam.

- Filtros de status variam por card: em vários trechos **`PENDENTE` + `ATIVO`**; para totais do mês também **`PROGRAMADO`** e **`QUITADO`**; capital de giro usa **`PENDENTE`**, **`ATIVO`**, **`PROGRAMADO`**.
- **`tipo`:** `C` = crédito/receber; `D` = débito/pagar.

**Saldo atual (bancos/caixas):** `buildDailyBalancesFromParcelas` também exclui **`saida = 'P'`** ao montar snapshots de `saldoatual` por agência.

**Blocos principais:**

| Bloco | Lógica resumida |
|-------|------------------|
| **Saldo atual** | `buildDailyBalancesFromParcelas(hoje, hoje)`: percorre parcelas com `idempresa`, `idagencia`, `datatransacao` e `saldoatual` preenchidos, `status <> CANCELADO`; soma o último `saldoatual` por par empresa+agência até o dia. |
| **A receber / A pagar “hoje”** | Parcelas com **`datavencimento` = hoje**, tipos C/D, status padrão da query. |
| **Atrasadas** | `datavencimento` < hoje. |
| **Resultado / margem do mês** | No mês corrente, soma receitas e despesas com status `PENDENTE`, `PROGRAMADO`, `QUITADO`. |
| **Capital de giro líquido (30 dias)** | Recebíveis − pagáveis com vencimento entre hoje e +30 dias, status `PENDENTE`/`ATIVO`/`PROGRAMADO`. |
| **Fluxo de caixa projetado** | 30 dias: entradas/saídas previstas por `datavencimento` (crédito/débito), saldo projetado acumulado a partir do saldo atual. |
| **Histórico receitas × despesas** | Últimos 6 meses, parcelas **`QUITADO`**, por **`datatransacao`**. |
| **Inadimplentes (top 3)** | Créditos com vencimento &lt; hoje; link WhatsApp montado no controller. |
| **Próximos vencimentos a pagar** | Débitos entre amanhã e +7 dias. |

---

## 3. Dashboard financeiro (legado) — `DashboardFinanceiroController` (`/dashboard/financeiro`)

**Arquivo:** `app/Http/Controllers/Admin/DashboardFinanceiroController.php`  
**View:** `resources/views/dashboard/financeiro.blade.php`

**Menu:** Painéis → **Financeiro** (rótulo FN). A **DRE principal** do menu é **`/dashboard/dre`** (§ 5); esta tela permanece para KPIs, ponto de equilíbrio e DRE resumida por **texto da hierarquia** (`resolverNaturezaDre`).

**Objetivo:** visão **gerencial** a partir de NF **quitadas** (`nfparcela.status = QUITADO`), com as mesmas exclusões de **`paraDemonstrativoGerencial`** (`P`, `T`, `transferkey`). Não usa matriz hierárquica da DRE nova (§ 5); classifica linhas via `resolverNaturezaDre` / `DreNaturezaService` por texto e `linhadre` parcial nos joins.

**Filtros:** modal em `partials.filters` com `organizedFilters` JSON na query string; função global **`filter($request, $query, 'nfparcela')`**. Período padrão na primeira visita: **últimos 5 meses até hoje** em `datatransacao` (redirect com `organizedFilters`).

**Cálculos:**

- **`obterLinhasGerenciais`:** join `nf` + `nfparcela` + `nfitem` + hierarquia `prodserv` → `grupoconta`; rateia valor da parcela proporcionalmente ao item: `(valoritem/totalnf) * valorparcela`.
- **`resolverNaturezaDre`:** classifica linha em `RECEITA_BRUTA`, `DEDUCOES`, `CUSTOS_VARIAVEIS`, `DESPESAS_FIXAS` por texto da hierarquia + tipo/saída da NF.
- **`obterEntradasCaixa`:** soma parcelas quitadas **`tipo = C`** (entradas).
- **`montarDreResumido`:** receita bruta (pode usar base “faturado”), deduções, receita líquida, custos variáveis, margem bruta, despesas fixas, resultado e margem operacional.
- **KPIs:** compara com **período anterior** de mesma duração (`calcularPeriodoAnterior`).
- **Ponto de equilíbrio** e **evolução mensal** (6 meses) derivados das mesmas regras.

**Telas:** cards de KPI, gráficos, tabelas DRE na view (Material Dashboard). Suporta seletor **`extrato_visao`** (unificado ou por agência), como DFC/DRE.

---

## 4. Dashboard DFC — `DashboardDfcController` (`/dashboard/dfc`)

**Arquivo:** `app/Http/Controllers/Admin/DashboardDfcController.php`  
**Serviço:** `App\Services\DfcHierarquiaService`  
**View:** `resources/views/dashboard/dfc.blade.php`  
**Ajuda contextual:** `dashboard/partials/dfc-ajuda-conteudos.blade.php`

**Menu:** Painéis → **DFC**.

**Plano:** rota protegida por **`plano.funcionalidade:dfc_gerencial`**. Tenant sem a funcionalidade é redirecionado para **`admin.plano-upgrade.index`** com mensagem de upgrade (middleware `CheckPlanoFuncionalidade`).

### 4.1 Rotas e período padrão

- **`index`:** sem `organizedFilters` nem `clear`, redireciona para **`dashboard.dfc.search`** com **`datatransacao` entre hoje − 3 meses e hoje**.
- **`search`:** aplica `filter($request, $query, 'nfparcela')` + monta demonstrativo.

### 4.2 Base de dados e exclusões

- Parcelas **`nfparcela.status = QUITADO`**; filtro principal em **`datatransacao`**.
- Join `nf` + `nfitem` + hierarquia produto/item/grupo; rateio: `(nfitem.valoritem / nf.totalnf) * nfparcela.valor`.
- **Sinal:** parcela **`tipo = C`** → valor de caixa positivo; **`D`** → negativo.
- Exclusões via **`Nf::scopeParaDemonstrativoGerencial`**: pedido (`P`), pagamento de fatura de cartão (`T`) e **transferência entre contas** (`transferkey` preenchido).
- Classificação **FCO / FCI / FCF** por **`grupoconta.tipo_fluxo`** (cadastro em Catálogo → Grupo Conta; padrões em **`classificacao_contabil_padrao`** — ver **`Doc_Modulo_Produto_Servico.md`**).

### 4.3 Saídas na tela

| Bloco | Origem |
|-------|--------|
| Cards FCO, FCI, FCF, resultado de caixa | `montarResumoFluxo` + comparação com período anterior (mesma duração em dias antes do filtro) |
| Gráfico mensal empilhado | `resumoFluxo['grafico']` |
| Tabela hierárquica | `montarDemonstrativo` → `linhas_matriz` (grupo → subgrupo → categoria → subcategoria → itens) |
| Visão por mês | Query `dfc_visao=mes` → `montarDemonstrativoPorMes` |

### 4.4 Visão por agência

Parâmetro **`extrato_visao`**: `unificado` (padrão) ou ID numérico de **`idagencia`** — partial `extrato-visao-selector.blade.php`. Filtra parcelas pela agência quando não unificado.

---

## 5. Dashboard DRE gerencial — `DashboardDreController` (`/dashboard/dre`)

**Arquivo:** `app/Http/Controllers/Admin/DashboardDreController.php`  
**Serviços:** `DreHierarquiaService`, `DreNaturezaService`  
**View:** `resources/views/dashboard/dre.blade.php`  
**Ajuda contextual:** `dashboard/partials/dre-ajuda-conteudos.blade.php`

**Menu:** Painéis → **DRE**.

**Plano:** rota protegida por **`plano.funcionalidade:dre_gerencial`**. Sem a funcionalidade no plano → redirecionamento para **Evoluir plano** (mesmo middleware do DFC).

### 5.1 Rotas e período padrão

Mesmo padrão do DFC: redirect inicial com **últimos 3 meses** em `datatransacao`; busca em **`dashboard.dre.search`**.

### 5.2 Base de dados e exclusões

- Parcelas **quitadas**, rateio proporcional por item (igual DFC).
- Mesmas exclusões do DFC (**`ParaDemonstrativoGerencial`**): `P`, `T` e NFs com **`transferkey`** (transferência entre agências da mesma empresa).
- Linhas classificadas por **`idlinhadre`** / natureza DRE (`LinhaDre`, `grupoconta.idlinhadre`, exceções em `prodservtipo.idlinhadre` e `classificacao_contabil_padrao`).
- **`obterEntradasCaixa`:** soma parcelas quitadas **`tipo = C`** para base de receita bruta no resumo.

### 5.3 Saídas na tela

| Bloco | Origem |
|-------|--------|
| Cards executivos (receita, margens, variação) | `montarResumoExecutivo` |
| `dre_resumido` | `DreNaturezaService::montarDreResumido` (receita bruta, deduções, custos, despesas fixas, resultado) |
| Tabela / matriz | `montarDemonstrativo` — drill-down contábil |
| Visão mensal | Query `dre_visao=mes` |

### 5.4 Diferença DFC × DRE × Financeiro legado

| Tela | Foco | Exclui `T`? | Classificação |
|------|------|-------------|---------------|
| **DFC** | Caixa quitado por atividade FCO/FCI/FCF | `P`, `T`, `transferkey` | `tipo_fluxo` no grupo conta |
| **DRE** | Resultado gerencial por linha DRE | `P`, `T`, `transferkey` | `idlinhadre` / natureza |
| **Financeiro legado** | KPIs e DRE por texto da árvore | `P`, `T`, `transferkey` | `resolverNaturezaDre` / `linhadre` nos joins |

---

## 6. Dashboard movimentação e **extrato por período**

**Arquivo:** `app/Http/Controllers/Admin/DashboardMovimentacaoController.php`  
**View:** `resources/views/dashboard/movimentacao.blade.php`

### 6.1 Rotas e fluxo

- **`GET /dashboard/movimentacao`** (`index`): se **não** há `organizedFilters` nem `clear`, **redireciona** para **`dashboard.movimentacao.search`** com filtro padrão: **`datatransacao` entre “agora − 3 meses” e hoje** (últimos **3 meses**).
- Com `?clear=true`, o `index` monta a lista com esse mesmo intervalo fixo de 3 meses **sem** passar pelo redirect de filtros.
- **`GET /dashboard/movimentacao/procurar`** (`search`): aplica **`filter($request, $query, 'nfparcela')`** conforme modal de filtros (empresa, agência, datas, etc.).

### 6.2 Critérios da query do extrato

Para **`listaParcelas`** (linhas do extrato):

- Join `nfparcela` + `nf`.
- **`nf.saida <> 'P'`** (exclui NF de pedido).
- **`nfparcela.status = 'QUITADO'`** — só movimentos **efetivados** (transação registrada).
- Ordenação: **`datatransacao` descendente** (mais recente primeiro).
- Eager load: `nf.pessoa`, `nf.fornecedor`, `nf.cliente`, `nf.nfitem.grupoitem`.

Ou seja: o **extrato** é o **razão de parcelas quitadas** no período filtrado, com rastro da NF e pessoa.

### 6.3 Totais e saldos do painel “Extrato por período”

**Arquivo parcial:** `resources/views/dashboard/partials/nf-parcela-movimentacao.blade.php`

| Variável | Origem no controller |
|----------|----------------------|
| **`totalCredito`** | Soma `parcela.valor` onde `tipo = 'C'`. |
| **`totalDebito`** | Soma onde `tipo = 'D'`. |
| **`totalLucro`** | `totalCredito - totalDebito` (no período filtrado). |
| **`saldoAtual`** | `obterSaldoAtualFiltrado`: **`saldoatual` da parcela mais recente** da lista (primeiro item após ordenação DESC). |
| **`saldoInicial`** | **`saldoinicial` da parcela mais antiga** da lista (último item na ordem DESC). |

A view também calcula **`$saldoPeriodo = saldoInicial + totalCredito - totalDebito`** para exibição coerente com o período.

**Importante:** `saldoAtual` / `saldoInicial` dependem dos campos **`saldoinicial`** / **`saldoatual`** preenchidos nas parcelas (tipicamente quando há **`idagencia`** e movimentação financeira). Sem isso, os cards podem mostrar zero mesmo com crédito/débito.

### 6.4 Gráficos de despesas

- Base: NF + parcelas quitadas + itens, **`nfparcela.tipo = 'D'`** (só **despesa**).
- Agregações por **subcategoria** (`prodservtipo`) e **categoria** (`item`).
- Valor: `SUM((nfitem.valoritem/nf.totalnf) * nfparcela.valor)`.
- Partial: `dashboard.partials.graph-movimentacao`.
- Lista detalhada: `dashboard.partials.lista-nf-parcela-movimentacao`.

### 6.5 Filtros (UI)

`@include('partials.filters', ['route' => route('dashboard.movimentacao.search'), ...])`:

- Empresa (`idempresa`, múltiplo)
- Agência (`idagencia`, múltiplo)
- **Data da transação** (`datatransacao`), padrão sugerido: últimos 3 meses

---

## 7. Dashboard veículo (diesel / abastecimento)

**Controller:** `DashboardVeiculoController`  
**View:** `resources/views/dashboard/veiculo.blade.php`

- **`index`:** apenas carrega listas (`empresas`, `veiculos`, `contratos`); gráficos/valores vazios até filtrar.
- **`search`:** NF **`scopePedido`** (`saida = P`) + itens com **`idprodserv` IN (20, 31)** — **IDs fixos no código** (produtos “diesel” na instalação atual).

**Dados calculados:** totais de pedidos, médias de consumo (`calcularMediaConsumo`, `calcularMediaConsumoPorMes` — helpers globais), média por veículo, lista de abastecimento com `ultimokm` via `getUltimoKmAntesDe`.

**Risco operacional:** se os IDs 20/31 não forem diesel no tenant, o dashboard fica incorreto — documentar na operação ou parametrizar no futuro.

---

## 8. Dashboard veículo custo

**Controller:** `DashboardVeiculoCustoController`  
**View:** `resources/views/dashboard/veiculocusto.blade.php`

- **`search`:** pedidos com itens **`idprodserv` NOT IN (20, 31)** e **`idprodservtipo = 2`** (tipo fixo no código), além de `nf.idprodservtipo = 2` na listagem de pedidos.
- Foco em **custos** associados ao veículo (não diesel), com lista `getListaPedidos` e agregações análogas à tela de veículo.

Mesma ressalva: **IDs e tipo numérico amarrados ao banco atual**.

---

## 9. Dashboard produto

**Rota:** closure → `dashboard.produto`

**Livewire:**

- Diesel: `PedidoDieselComponent`, `ProdutoEstoqueDieselComponent`, `GraphPedidoDieselComponent`
- Cimento: `PedidoCimentoComponent`, `ProdutoEstoqueCimentoComponent`, `GraphPedidoCimentoComponent`

Combina **pedidos** e **estoque** por família de produto na UI.

---

## 10. Dashboard evento

**View:** `dashboard.evento`

- Calendário: `CalendarEventoComponent`
- Painel lateral: `EventoComponent`

Ver **`Doc_Modulo_Evento.md`**.

---

## 11. Dashboard tags

**View:** `dashboard.tags`

- Calendário: `CalendarTagComponent`
- Indicadores/listas: `TagComponent`

Ver **`Doc_Modulo_Tags.md`**.

---

## 12. Ranking de campanhas

**Controller:** `DashboardRankingCampanha@index`  
**View:** `dashboard.campanha`  
**Livewire:** `RankingCampanha` — abas ranking, vendas, produtos, conquistas; models `Campanha`, `CampanhaVenda`, `CampanhaProdutoMetrica`, `CampanhaPonto`, `CampanhaBadge`.

Automação de pontos por NF: **`Doc_Jobs_e_Agendamento.md`**.

---

## 13. Conciliação de agência (API no painel)

Rotas em `routes/web.php` (POST/GET, não são “página” de menu isolada; usadas no fluxo de extrato/financeiro):

| Rota | Nome | Uso |
|------|------|-----|
| `POST /dashboard/conciliacao-agencia/conciliar` | `dashboard.conciliacao-agencia.conciliar` | Trava período em `agencia.conciliado_ate` |
| `POST /dashboard/conciliacao-agencia/reabrir` | `dashboard.conciliacao-agencia.reabrir` | Reabre com auditoria |
| `GET .../historico/{idagencia}` | `...historico` | Histórico |
| `GET .../auditoria-reabertura/{idagencia}/{data}` | `...auditoria-reabertura` | Detalhe de reabertura |

Serviço: **`ConciliacaoAgenciaService`** — detalhes em **`Doc_Modulo_Financeiro.md`** § 1.11.

---

## 14. Referência rápida de arquivos

| Arquivo | Função |
|---------|--------|
| `app/Http/Controllers/DashboardController.php` | Visão geral / saldo / projeções |
| `app/Http/Controllers/Admin/DashboardFinanceiroController.php` | Financeiro legado — KPIs / DRE por texto |
| `app/Http/Controllers/Admin/DashboardDfcController.php` | **DFC** |
| `app/Http/Controllers/Admin/DashboardDreController.php` | **DRE gerencial** |
| `app/Services/DfcHierarquiaService.php` | Query, FCO/FCI/FCF, matriz e gráfico DFC |
| `app/Services/DreHierarquiaService.php` | Query e matriz DRE |
| `app/Services/DreNaturezaService.php` | Resumo DRE (naturezas por `linhadre`) |
| `app/Http/Controllers/Admin/DashboardMovimentacaoController.php` | **Extrato** (parcelas quitadas) |
| `app/Http/Controllers/Admin/ConciliacaoAgenciaController.php` | Conciliação AJAX |
| `app/Http/Controllers/Admin/DashboardVeiculoController.php` | Pedidos diesel (IDs fixos) |
| `app/Http/Controllers/Admin/DashboardVeiculoCustoController.php` | Custos de frota (tipo fixo) |
| `app/Http/Controllers/DashboardRankingCampanha.php` | Shell da página campanha |
| `resources/views/dashboard/dfc.blade.php`, `dre.blade.php` | Layouts DFC/DRE |
| `resources/views/dashboard/partials/extrato-visao-selector.blade.php` | Seletor unificado / agência |
| `resources/views/dashboard/movimentacao.blade.php` | Layout extrato + filtros |
| `routes/web.php` | Definição das rotas listadas na § 1 |

---

*Documento baseado na leitura do código. Regras finas de `filter()` / `organizedFilters` estão nos helpers globais e nas partials de filtro.*

**Histórico:** visão geral exclui pedidos (`nf.saida <> 'P'`). Inclusão das telas **DFC** e **DRE** (`DashboardDfcController`, `DashboardDreController`) e distinção do financeiro legado.