# 🚀 Getting Started - Dashboard Tab System

## 👋 Bem-vindo, Novo Desenvolvedor!

Este guia te ajudará a entender e usar o **Dashboard Tab System** - uma funcionalidade que adiciona automaticamente uma aba de dashboard antes da lista em qualquer domínio.

## 🎯 O que é o Dashboard Tab System?

É um sistema que permite adicionar uma aba de **"Dashboard de [Domínio]"** antes da aba **"Lista de [Domínio]"** com apenas uma linha de código!

### Antes vs Depois

**Antes** (sem dashboard):
```
[Lista de Motoristas] [Editar: João] [Editar: Maria]
```

**Depois** (com dashboard):
```
[Dashboard de Motoristas] [Lista de Motoristas] [Editar: João] [Editar: Maria]
```

## 🚀 Como Usar (Super Simples!)

### 1. Configuração Mínima (1 linha!)

```typescript
// Em qualquer arquivo *.component.ts que estende BaseDomainComponent
protected override getDomainConfig(): DomainConfig {
  return {
    domain: 'vehicle',
    title: 'Veículos',
    entityName: 'veículo',
    subTabs: ['dados'],
    showDashboardTab: true, // ✅ SÓ ISSO! 
    columns: [...]
  };
}
```

**Pronto!** Agora você tem:
- ✅ Aba "Dashboard de Veículos" 
- ✅ KPIs automáticos (Total, Ativos, Recentes)
- ✅ Lista dos últimos 5 itens
- ✅ Design responsivo e dark mode

### 2. Configuração Avançada (Opcional)

```typescript
protected override getDomainConfig(): DomainConfig {
  return {
    domain: 'driver',
    title: 'Motoristas',
    entityName: 'motorista',
    subTabs: ['dados', 'documentos'],
    showDashboardTab: true,
    dashboardConfig: {
      title: 'Painel de Motoristas', // Título customizado
      customKPIs: [
        {
          id: 'drivers-with-license',
          label: 'Com CNH Válida',
          value: '85%',
          icon: 'fas fa-id-card',
          color: 'success',
          trend: 'up',
          change: '+3%'
        },
        {
          id: 'drivers-premium',
          label: 'Motoristas Premium',
          value: 42,
          icon: 'fas fa-crown',
          color: 'warning',
          trend: 'stable'
        }
      ]
    },
    columns: [...]
  };
}
```

## 📊 KPIs Automáticos (Grátis!)

O sistema gera automaticamente estes KPIs baseados nos seus dados:

### 1. 📋 Total de Registros
- **O que mostra**: Quantidade total de itens
- **Baseado em**: `totalItems` do seu service
- **Exemplo**: "Total de Motoristas: 150"

### 2. ✅ Registros Ativos  
- **O que mostra**: Itens com status ativo
- **Baseado em**: Campo `status = 'Ativo'|'active'|'Active'`
- **Exemplo**: "Motoristas Ativos: 142"

### 3. 🆕 Registros Recentes
- **O que mostra**: Itens criados nos últimos 7 dias
- **Baseado em**: Campo `created_at`
- **Exemplo**: "Novos (7 dias): 8"

## 🎨 Cores dos KPIs

```typescript
color: 'primary'  // 🔵 Azul (padrão)
color: 'success'  // 🟢 Verde (positivo)
color: 'warning'  // 🟡 Amarelo (atenção)
color: 'danger'   // 🔴 Vermelho (crítico)
color: 'info'     // 🔷 Azul claro (informativo)
```

## 🎯 Ícones Recomendados

```typescript
// Totais e listas
'fas fa-list'         // Total geral
'fas fa-users'        // Usuários/Motoristas
'fas fa-car'          // Veículos
'fas fa-building'     // Empresas

// Status e estados
'fas fa-check-circle' // Ativos/Válidos
'fas fa-plus-circle'  // Novos/Recentes
'fas fa-clock'        // Pendentes
'fas fa-times-circle' // Inativos/Inválidos

// Especiais
'fas fa-crown'        // Premium/VIP
'fas fa-star'         // Favoritos
'fas fa-chart-line'   // Crescimento
'fas fa-dollar-sign'  // Financeiro
'fas fa-id-card'      // Documentos
```

## 📱 Exemplos Práticos

### Exemplo 1: Veículos (Simples)
```typescript
export class VehiclesComponent extends BaseDomainComponent<Vehicle> {
  protected override getDomainConfig(): DomainConfig {
    return {
      domain: 'vehicle',
      title: 'Veículos',
      entityName: 'veículo',
      subTabs: ['dados', 'documentos'],
      showDashboardTab: true, // ✅ Só isso!
      columns: [
        { field: "license_plate", header: "Placa", sortable: true },
        { field: "brand", header: "Marca", sortable: true }
      ]
    };
  }
}
```

### Exemplo 2: Clientes (Avançado)
```typescript
export class ClientsComponent extends BaseDomainComponent<Client> {
  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: 'monthly-revenue',
            label: 'Receita Mensal',
            value: 'R$ 125K',
            icon: 'fas fa-dollar-sign',
            color: 'primary',
            trend: 'up',
            change: '+8.5%'
          }
        ]
      },
      columns: [
        { field: "name", header: "Nome", sortable: true },
        { field: "email", header: "Email", sortable: true }
      ]
    };
  }
}
```

## 🔧 Troubleshooting

### ❓ Dashboard não aparece?
**Verifique:**
1. ✅ `showDashboardTab: true` está no `getDomainConfig()`
2. ✅ Componente estende `BaseDomainComponent`
3. ✅ Build foi executado após a mudança

### ❓ KPIs automáticos não aparecem?
**Possíveis causas:**
1. Service não retorna `totalItems`
2. Dados não têm campo `status` ou `created_at`
3. Dados estão vazios

### ❓ KPI customizado não aparece?
**Verifique:**
1. ✅ `customKPIs` está dentro de `dashboardConfig`
2. ✅ Todos os campos obrigatórios estão preenchidos
3. ✅ `id` é único

## 🎓 Próximos Passos

1. **Teste**: Adicione `showDashboardTab: true` em um domínio existente
2. **Customize**: Adicione KPIs específicos do seu domínio
3. **Explore**: Veja outros domínios como `drivers.component.ts`
4. **Contribua**: Sugira melhorias e novos tipos de KPI

## 📚 Documentação Completa

- [Dashboard Tab System Guide](./components/DASHBOARD_TAB_SYSTEM.md)
- [BaseDomainComponent](./architecture/BASE_DOMAIN_COMPONENT.md)
- [Cursor Rules](./.cursorrules)

## 💡 Dicas Pro

1. **Comece simples**: Use só `showDashboardTab: true` primeiro
2. **Ícones**: Use FontAwesome 5 (fas fa-*)
3. **Cores**: `success` para positivo, `warning` para atenção
4. **Valores**: Use formatação amigável ('85%', 'R$ 125K')
5. **Trends**: `up` = verde, `down` = vermelho, `stable` = amarelo

---

**Bem-vindo ao time!** 🎉  
Se tiver dúvidas, consulte a documentação ou pergunte para a equipe.

**Happy Coding!** 🚀