# 📊 Guia de Personalização de Dashboard de Aba

Este guia mostra como personalizar o dashboard de aba para qualquer domínio no sistema PraFrota.

## 🎯 Visão Geral

O sistema de dashboard permite criar painéis personalizados para cada domínio, com:
- **KPIs automáticos** (Total, Ativos, Recentes)
- **KPIs customizados** (específicos do domínio)
- **Gráficos personalizados** (barras, linhas, pizza)
- **Itens recentes** (últimos registros)

## 🚀 Como Implementar

### 1. Habilitar Dashboard no DomainConfig

```typescript
protected override getDomainConfig(): DomainConfig {
  return {
    domain: 'tollparking',
    title: 'Pedágio & Estacionamento',
    showDashboardTab: true, // ✅ Habilitar dashboard
    dashboardConfig: {
      title: 'Dashboard de Pedágio & Estacionamento',
      showKPIs: true,
      showCharts: true,
      showRecentItems: true,
      customKPIs: this.getCustomKPIs(),      // ✅ KPIs personalizados
      customCharts: this.getCustomCharts()   // ✅ Gráficos personalizados
    },
    // ... resto da configuração
  };
}
```

### 2. Implementar KPIs Customizados

```typescript
private getCustomKPIs(): DashboardKPI[] {
  if (!this.entities || this.entities.length === 0) {
    return [];
  }

  // Calcular métricas específicas do domínio
  const last3MonthsData = this.getLast3MonthsData();
  const topVehiclesByValue = this.getTopVehiclesByValue(10);
  const monthlyEvolution = this.getMonthlyEvolution();

  return [
    {
      id: 'top-vehicle-value',
      label: 'Maior Gasto (Veículo)',
      value: `R$ ${topVehiclesByValue[0]?.totalValue.toLocaleString('pt-BR')}`,
      icon: 'fas fa-trophy',
      color: 'warning',
      trend: 'up',
      change: topVehiclesByValue[0]?.license_plate || '-'
    },
    {
      id: 'monthly-evolution',
      label: 'Evolução Mensal',
      value: monthlyEvolution.trend === 'up' ? '↗️' : '↘️',
      icon: 'fas fa-chart-line',
      color: monthlyEvolution.trend === 'up' ? 'success' : 'danger',
      trend: monthlyEvolution.trend,
      change: `${monthlyEvolution.percentage}%`
    }
    // ... mais KPIs
  ];
}
```

### 3. Implementar Gráficos Customizados

```typescript
private getCustomCharts(): DashboardChart[] {
  if (!this.entities || this.entities.length === 0) {
    return [];
  }

  const topVehicles = this.getTopVehiclesByValue(10);
  const monthlyData = this.getMonthlyEvolutionData();
  const typeDistribution = this.getTypeDistribution();

  return [
    {
      id: 'top-vehicles-chart',
      title: 'Top 10 Veículos por Valor Total',
      type: 'bar',
      data: topVehicles.map(v => ({
        label: v.license_plate,
        value: v.totalValue,
        count: v.count,
        avgValue: v.avgValue
      }))
    },
    {
      id: 'monthly-evolution-chart',
      title: 'Evolução dos Últimos 3 Meses',
      type: 'line',
      data: monthlyData
    },
    {
      id: 'type-distribution-chart',
      title: 'Distribuição por Tipo',
      type: 'pie',
      data: typeDistribution
    }
  ];
}
```

## 📈 Exemplo Completo: TollparkingComponent

O `TollparkingComponent` implementa um dashboard personalizado com:

### KPIs Implementados:
1. **Maior Gasto (Veículo)**: Mostra o veículo com maior gasto total
2. **Evolução Mensal**: Compara mês atual vs anterior com tendência
3. **Veículos Ativos**: Quantidade de veículos únicos nos últimos 3 meses
4. **Gasto Médio Mensal**: Média de gastos dos últimos 3 meses

### Gráficos Implementados:
1. **Top 10 Veículos por Valor**: Ranking dos veículos com maiores gastos
2. **Evolução dos Últimos 3 Meses**: Linha temporal de gastos
3. **Distribuição por Tipo**: Pizza mostrando pedágio vs estacionamento

### Métodos de Cálculo:
- `getLast3MonthsData()`: Dados dos últimos 90 dias
- `getCurrentMonthData()`: Dados do mês atual
- `getPreviousMonthData()`: Dados do mês anterior
- `getTopVehiclesByValue()`: Ranking de veículos por gasto
- `getMonthlyEvolution()`: Cálculo de tendência mensal
- `getTypeDistribution()`: Distribuição por categoria

## 🎨 Tipos de KPI

### Cores Disponíveis:
- `primary`: Azul (padrão do sistema)
- `success`: Verde (positivo, crescimento)
- `warning`: Amarelo (atenção, destaque)
- `danger`: Vermelho (crítico, decréscimo)
- `info`: Azul claro (informativo)

### Tendências:
- `up`: Crescimento (seta para cima)
- `down`: Decréscimo (seta para baixo)
- `stable`: Estável (seta horizontal)

### Ícones Recomendados:
- `fas fa-trophy`: Rankings, destaques
- `fas fa-chart-line`: Evolução, tendências
- `fas fa-car`: Veículos
- `fas fa-calculator`: Cálculos, médias
- `fas fa-dollar-sign`: Valores financeiros
- `fas fa-users`: Usuários, motoristas
- `fas fa-clock`: Tempo, recentes

## 🎯 Tipos de Gráfico

### Disponíveis:
- `bar`: Gráfico de barras (comparações)
- `line`: Gráfico de linha (evolução temporal)
- `pie`: Gráfico de pizza (distribuições)

### Estrutura de Dados:
```typescript
// Para gráficos de barra e linha
data: [
  {
    label: 'ABC-1234',
    value: 1500.50,
    count: 15,
    // ... outros campos
  }
]

// Para gráfico de pizza
data: [
  {
    label: 'Pedágio',
    value: 5000,
    count: 50,
    percentage: '60.5'
  }
]
```

## 🔧 Métodos Auxiliares Comuns

### Filtrar por Período:
```typescript
private getDataByPeriod(startDate: Date, endDate: Date) {
  return this.entities.filter((item: any) => {
    const itemDate = new Date(item.date || item.created_at);
    return itemDate >= startDate && itemDate <= endDate;
  });
}
```

### Agrupar por Campo:
```typescript
private groupByField(field: string) {
  const groups = new Map();
  
  this.entities.forEach((item: any) => {
    const key = item[field];
    if (!groups.has(key)) {
      groups.set(key, {
        key,
        items: [],
        totalValue: 0,
        count: 0
      });
    }
    
    const group = groups.get(key);
    group.items.push(item);
    group.totalValue += Number(item.value) || 0;
    group.count += 1;
  });

  return Array.from(groups.values());
}
```

### Calcular Tendência:
```typescript
private calculateTrend(current: number, previous: number) {
  if (previous === 0) return 'stable';
  
  const change = ((current - previous) / previous) * 100;
  
  return change > 5 ? 'up' : change < -5 ? 'down' : 'stable';
}
```

## 📱 Responsividade

O dashboard é automaticamente responsivo:
- **Desktop**: Grid de 3-4 colunas
- **Tablet**: Grid de 2 colunas
- **Mobile**: Grid de 1 coluna

## 🎯 Boas Práticas

### KPIs:
1. **Máximo 6 KPIs**: Para não sobrecarregar a tela
2. **Valores relevantes**: Focar nas métricas mais importantes
3. **Atualização dinâmica**: KPIs devem refletir dados atuais
4. **Formatação adequada**: Usar formatação brasileira para números

### Gráficos:
1. **Máximo 3 gráficos**: Para performance e usabilidade
2. **Dados suficientes**: Verificar se há dados antes de renderizar
3. **Títulos descritivos**: Títulos claros e objetivos
4. **Cores consistentes**: Usar paleta de cores do sistema

### Performance:
1. **Cache de cálculos**: Evitar recalcular a cada render
2. **Lazy loading**: Carregar dados sob demanda
3. **Debounce**: Para atualizações em tempo real

## 🔄 Atualização Automática

O dashboard é atualizado automaticamente quando:
- Dados são carregados (`entities` mudança)
- Filtros são aplicados
- Aba é reaberta

## 📊 Exemplo de Uso

```typescript
// No component do domínio
export class MyDomainComponent extends BaseDomainComponent<MyEntity> {
  
  protected override getDomainConfig(): DomainConfig {
    return {
      // ... configuração básica
      showDashboardTab: true,
      dashboardConfig: {
        customKPIs: this.getMyKPIs(),
        customCharts: this.getMyCharts()
      }
    };
  }

  private getMyKPIs(): DashboardKPI[] {
    // Implementar KPIs específicos do domínio
  }

  private getMyCharts(): DashboardChart[] {
    // Implementar gráficos específicos do domínio
  }
}
```

## 🎉 Resultado

Com essa implementação, você terá um dashboard personalizado que:
- ✅ Mostra métricas relevantes do domínio
- ✅ Apresenta evolução temporal dos dados
- ✅ Destaca informações importantes
- ✅ É responsivo e performático
- ✅ Segue padrões visuais do sistema

---

**💡 Dica**: Use o `TollparkingComponent` como referência para implementar dashboards em outros domínios!