# Dashboard – Visão Geral Técnica

Este documento descreve a arquitetura e os módulos do Dashboard, pontos de integração com APIs, comportamento de carregamento (lazy loading), acessibilidade, tema e como estender.

## Estrutura de Arquivos
- View: `views/dashboard/index.php`
- Módulos JS (lazy): `public/js/dashboard/`
  - `kpis.js` – KPIs principais
  - `charts.js` – Tendência e previsão
  - `realtime.js` – Painel em tempo real
  - `finance.js` – Contas a pagar/receber, filtros e resumo
  - `sellers.js` – Vendas por vendedor (gráfico e tabela)
  - `stock.js` – Alertas de estoque
  - `calendar.js` – Agenda/calendário interativo
  - `advanced-chart.js` – Gráfico avançado com comparativos

Layout base: `views/_layout.php` (tema claro/escuro e utilitários globais)

## Carregamento e Estado
- O `index.php` do dashboard define o estado global de filtros (`state.filters`) e thresholds de alertas.
- Cada seção possui `IntersectionObserver` para import dinâmico do respectivo módulo apenas quando estiver visível.
- Ao alterar filtros globais, módulos ativos são reexecutados (reaplicação com os filtros vigentes).

## Integrações de API (esperadas)
As rotas abaixo podem ser adaptadas ao backend; os módulos toleram ausência de API (fallback visual).

- Financeiro:
  - `GET /api/finance/payables?start=&end=&category=&per_page=50`
  - `GET /api/finance/receivables?start=&end=&category=&per_page=50`
- Vendedores:
  - `GET /api/sales/by-seller?start=&end=&channel=`
- Estoque:
  - `GET /api/stock/low?threshold=&limit=20`
- Agenda/Calendário:
  - `GET /api/events?start=&end=`
  - `POST /api/events` (criação de eventos)
- Gráfico Avançado:
  - `GET /api/sales/advanced?start=&end=&compare_start=&compare_end=&product=&region=&seller=&group_by=day`
  - `GET /api/sales/filters` (popular selects de produto/região/vendedor)

Autenticação/OAuth/JWT: os requests usam `credentials: 'include'` e, quando aplicável, utilitários do layout (`apiRequest`) para headers/persistência de sessão.

## Módulos – Resumo

- `finance.js`
  - Filtros independentes para pagar/receber; resumo de totais e próximos vencimentos.
  - Tolerância a schemas diferentes (`amount_cents` ou `amount`).
  - Acessibilidade: textos claros, feedback “Carregando…”, cabeçalhos consistentes.

- `sellers.js`
  - Gráfico simples de barras e tabela detalhada; exportação CSV.
  - Ajusta-se ao período/canal vindos dos filtros globais.

- `stock.js`
  - Lista de itens críticos/baixos/ok com cores; links para produto e reposição.
  - Threshold configurável em `state.thresholds.lowStock`.

- `calendar.js`
  - Visualizações mensal/semanal/diária com marcadores; tooltip e criação de eventos.
  - Borda e cores usam variáveis de tema (`--border-muted`).

- `advanced-chart.js`
  - Comparação de períodos (mês, trimestre, ano, custom), tipos linha/barra/pizza.
  - Filtros dinâmicos (produto, região, vendedor) via `GET /api/sales/filters` com fallback seguro.

## Tema e Design
- O layout define `applyTheme(theme)` e persiste a escolha (`localStorage`).
- Componentes usam variáveis CSS (`--color-white`, `--border-muted`, etc.) para compatibilidade com claro/escuro.
- Transições suaves em cores/bordas (0.25s) para reduzir _flicker_.

## Acessibilidade
- Navegação com labels e estados ARIA nas seções; foco preservado em interações de filtro.
- Tabelas com cabeçalhos semânticos; feedback de carregamento e estados vazios.

## Extensão de Módulos
1. Crie novo arquivo em `public/js/dashboard/NOME.js` exportando `initNOME(state, utils)`.
2. No `views/dashboard/index.php`, adicione a seção HTML e declare no mapeamento de imports dinâmicos.
3. Use `state.filters` para sincronizar filtros globais; respeite abortos de requests.
4. Prefira variáveis de tema e layouts responsivos (grid flexível e `minmax`).

## Troubleshooting
- Sem API: módulos exibem “Sem dados” e usam dados fake mínimos quando aplicável.
- Autenticação expirada: `apiRequest` tenta revalidar via cookie/admin token.
- CORS/cookies: garanta `credentials: 'include'` e headers adequados.