# 📊 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

```typescript
// 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

```typescript
// 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)

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

### DashboardTabConfig

```typescript
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

```typescript
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

```typescript
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)

```typescript
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)

```typescript
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

```mermaid
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

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

### Métodos Principais

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

## 🎨 Customização Visual

### Cores dos KPIs

```typescript
// 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

```typescript
// 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

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

### Como Contribuir

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

## 📚 Referências

- [BaseDomainComponent](../architecture/BASE_DOMAIN_COMPONENT.md)
- [TabSystem](../tab-system/README.md)
- [Interfaces](../../shared/interfaces/)
- [Componentes](../../shared/components/)

---

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