9.4 KiB

Raw Blame History

📊 Dashboard Tab System - Guia Completo

🎯 Visão Geral

O Dashboard Tab System é uma extensão do framework BaseDomainComponent que permite adicionar uma aba de dashboard antes da aba de lista em qualquer domínio. Esta funcionalidade oferece uma visão geral com KPIs, gráficos e itens recentes de forma automática e customizável.

✨ Características

✅ Aba Dashboard antes da Lista: Ordem automática (Dashboard → Lista → Edições)
✅ KPIs Automáticos: Total, Ativos, Recentes (últimos 7 dias)
✅ KPIs Customizados: Definidos por domínio
✅ Itens Recentes: Últimos 5 registros automaticamente
✅ Gráficos Customizados: Placeholder para implementações futuras
✅ Design Responsivo: Funciona em desktop e mobile
✅ Dark Mode: Suporte completo
✅ Configuração Simples: Apenas uma flag no DomainConfig

🚀 Como Usar

1. Habilitar Dashboard em um Domínio

// exemplo: drivers.component.ts
protected override getDomainConfig(): DomainConfig {
  return {
    domain: 'driver',
    title: 'Motoristas',
    entityName: 'motorista',
    subTabs: ['dados', 'photos', 'documents'],
    
    // ✅ NOVO: Habilitar aba Dashboard
    showDashboardTab: true,
    
    // ✅ NOVO: Configuração opcional do dashboard
    dashboardConfig: {
      title: 'Dashboard de Motoristas', // Opcional
      showKPIs: true,                   // default: true
      showCharts: true,                 // default: true
      showRecentItems: true,            // default: true
      customKPIs: [
        {
          id: 'drivers-with-license',
          label: 'Com CNH Válida',
          value: '85%',
          icon: 'fas fa-id-card',
          color: 'success',
          trend: 'up',
          change: '+3%'
        }
      ]
    },
    
    columns: [...]
  };
}

2. Configuração Mínima

// Configuração mínima - apenas habilitar
protected override getDomainConfig(): DomainConfig {
  return {
    domain: 'vehicle',
    title: 'Veículos',
    entityName: 'veículo',
    subTabs: ['dados'],
    showDashboardTab: true, // ✅ Só isso já funciona!
    columns: [...]
  };
}

📋 Interfaces e Tipos

DomainConfig (Estendido)

export interface DomainConfig {
  // ... propriedades existentes ...
  showDashboardTab?: boolean;        // Mostrar aba Dashboard (default: false)
  dashboardConfig?: DashboardTabConfig; // Configuração específica do dashboard
}

DashboardTabConfig

export interface DashboardTabConfig {
  title?: string;                    // Título customizado (default: 'Dashboard de [Title]')
  showKPIs?: boolean;               // Mostrar KPIs principais (default: true)
  showCharts?: boolean;             // Mostrar gráficos (default: true)
  showRecentItems?: boolean;        // Mostrar itens recentes (default: true)
  customKPIs?: DashboardKPI[];      // KPIs customizados
  customCharts?: DashboardChart[];  // Gráficos customizados
}

DashboardKPI

export interface DashboardKPI {
  id: string;                       // Identificador único
  label: string;                    // Rótulo do KPI
  value: string | number;           // Valor (formatado automaticamente)
  icon: string;                     // Ícone FontAwesome
  color: 'primary' | 'success' | 'warning' | 'danger' | 'info';
  trend?: 'up' | 'down' | 'stable'; // Tendência (opcional)
  change?: string;                  // Mudança percentual (opcional)
}

DashboardChart

export interface DashboardChart {
  id: string;                       // Identificador único
  title: string;                    // Título do gráfico
  type: 'bar' | 'line' | 'pie' | 'donut'; // Tipo do gráfico
  data: any[];                      // Dados do gráfico
  config?: any;                     // Configurações específicas
}

🎨 KPIs Automáticos

O sistema gera automaticamente os seguintes KPIs baseados nos dados:

1. Total de Registros

Label: "Total de [Title]"
Valor: totalItems
Ícone: fas fa-list
Cor: primary

2. Registros Ativos (se existir campo `status`)

Label: "[Title] Ativos"
Valor: Contagem de itens com status = 'Ativo'|'active'|'Active'
Ícone: fas fa-check-circle
Cor: success
Tendência: stable

3. Registros Recentes (últimos 7 dias)

Label: "Novos (7 dias)"
Valor: Contagem de itens com created_at nos últimos 7 dias
Ícone: fas fa-plus-circle
Cor: info
Tendência: up

🎯 Exemplos Práticos

Exemplo 1: Dashboard Simples (Veículos)

protected override getDomainConfig(): DomainConfig {
  return {
    domain: 'vehicle',
    title: 'Veículos',
    entityName: 'veículo',
    subTabs: ['dados', 'documentos'],
    showDashboardTab: true,
    columns: [
      { field: "license_plate", header: "Placa", sortable: true },
      { field: "brand", header: "Marca", sortable: true },
      { field: "model", header: "Modelo", sortable: true }
    ]
  };
}

Resultado: Dashboard com KPIs automáticos + últimos 5 veículos.

Exemplo 2: Dashboard Avançado (Clientes)

protected override getDomainConfig(): DomainConfig {
  return {
    domain: 'client',
    title: 'Clientes',
    entityName: 'cliente',
    subTabs: ['dados', 'contratos'],
    showDashboardTab: true,
    dashboardConfig: {
      title: 'Painel de Clientes',
      customKPIs: [
        {
          id: 'premium-clients',
          label: 'Clientes Premium',
          value: 45,
          icon: 'fas fa-crown',
          color: 'warning',
          trend: 'up',
          change: '+12%'
        },
        {
          id: 'active-contracts',
          label: 'Contratos Ativos',
          value: '89%',
          icon: 'fas fa-file-contract',
          color: 'success',
          trend: 'stable'
        },
        {
          id: 'monthly-revenue',
          label: 'Receita Mensal',
          value: 'R$ 125K',
          icon: 'fas fa-dollar-sign',
          color: 'primary',
          trend: 'up',
          change: '+8.5%'
        }
      ]
    },
    columns: [...]
  };
}

Resultado: Dashboard com KPIs automáticos + 3 KPIs customizados + itens recentes.

🔧 Arquitetura Técnica

Fluxo de Criação das Abas

graph TD
    A[loadEntities] --> B{Primeira vez?}
    B -->|Sim| C[createInitialTabs]
    B -->|Não| D[updateTabsData]
    
    C --> E{showDashboardTab?}
    E -->|Sim| F[createDashboardTab]
    E -->|Não| G[createListTab]
    F --> G
    
    D --> H{Dashboard existe?}
    H -->|Sim| I[updateDashboardTabData]
    H -->|Não| J[updateListTabData]
    I --> J

Componentes Envolvidos

BaseDomainComponent: Lógica de criação e gerenciamento das abas
TabSystemComponent: Renderização das abas e roteamento de conteúdo
DomainDashboardComponent: Componente visual do dashboard
DomainConfig: Interface de configuração

Métodos Principais

// BaseDomainComponent
private async createDashboardTab(): Promise<void>
private generateAutomaticKPIs(): DashboardKPI[]
private async createInitialTabs(): Promise<void>
private updateDashboardTabData(): void

🎨 Customização Visual

Cores dos KPIs

// Cores disponíveis
type KPIColor = 'primary' | 'success' | 'warning' | 'danger' | 'info';

// Mapeamento visual
primary: var(--idt-primary-color)  // Azul
success: var(--idt-success)        // Verde
warning: var(--idt-warning)        // Amarelo/Laranja
danger:  var(--idt-danger)         // Vermelho
info:    var(--idt-info)           // Azul claro

Ícones Recomendados

// KPIs comuns
'fas fa-list'           // Total
'fas fa-check-circle'   // Ativos
'fas fa-plus-circle'    // Novos
'fas fa-users'          // Usuários
'fas fa-car'            // Veículos
'fas fa-building'       // Empresas
'fas fa-dollar-sign'    // Financeiro
'fas fa-chart-line'     // Crescimento
'fas fa-crown'          // Premium
'fas fa-star'           // Favoritos

📱 Responsividade

O dashboard é totalmente responsivo:

Desktop: Grid de 3-4 colunas para KPIs
Tablet: Grid de 2 colunas
Mobile: Grid de 1 coluna

🌙 Dark Mode

Suporte completo ao dark mode com:

Cores adaptadas automaticamente
Contrastes adequados
Ícones e bordas ajustados

🔄 Atualização Automática

O dashboard é atualizado automaticamente quando:

Dados são recarregados (loadEntities)
Filtros são aplicados
Paginação é alterada
Novos itens são criados/editados

🚀 Próximos Passos

Funcionalidades Futuras

Gráficos Reais: Integração com bibliotecas de gráficos (Chart.js, D3.js)
Filtros no Dashboard: Filtros específicos para KPIs
Exportação: Exportar dados do dashboard
Widgets Customizados: Componentes específicos por domínio
Refresh Manual: Botão de atualização manual

Como Contribuir

Adicione novos tipos de KPIs automáticos
Implemente gráficos específicos por domínio
Crie widgets customizados
Melhore a responsividade
Adicione animações e transições

📚 Referências

Criado em: Janeiro 2025
Versão: 1.0
Autor: Sistema PraFrota
Branch: feature/dashboard-tab-system

9.4 KiB Raw Blame History