# 🛠️ Utilities - Shared Utils

Coleção de utilitários reutilizáveis para uso em todo o projeto PraFrota.

## 📅 DateRangeUtils

Utilities para manipulação de ranges de datas em formato ISO 8601.

### 🚀 Uso Rápido (Recomendado)

```typescript
import { DateRangeShortcuts } from '../../shared/utils/date-range.utils';

// ✅ Mês atual
const filters = DateRangeShortcuts.currentMonth();
// Resultado: { date_start: '2025-01-01', date_end: '2025-01-31' }

// ✅ Últimos 30 dias
const last30 = DateRangeShortcuts.last30Days();

// ✅ Ano atual
const yearFilters = DateRangeShortcuts.currentYear();
```

### 🎯 Casos de Uso Comuns

#### **Dashboard e Relatórios**
```typescript
// ✅ ANTES (incorreto)
const response = await service.getData(1, 500, {
  date_start: '2025-07-01&date_end=2025-07-31' // ❌ Formato inválido
});

// ✅ DEPOIS (correto)
const dateFilters = DateRangeShortcuts.currentMonth();
const response = await service.getData(1, 500, dateFilters);
```

#### **Filtros de Data Personalizados**
```typescript
import { DateRangeUtils } from '../../shared/utils/date-range.utils';

// Mês específico
const julyFilters = DateRangeUtils.getMonthRange(2025, 7);
// { start: '2025-07-01', end: '2025-07-31' }

// Range personalizado
const customRange = DateRangeUtils.getCustomRangeAsApiParams(
  new Date('2025-01-15'),
  new Date('2025-02-15')
);
```

### 📋 API Completa

#### **DateRangeShortcuts (Recomendado)**
```typescript
DateRangeShortcuts.currentMonth()  // Mês atual
DateRangeShortcuts.currentYear()   // Ano atual
DateRangeShortcuts.last30Days()    // Últimos 30 dias
DateRangeShortcuts.last7Days()     // Últimos 7 dias
DateRangeShortcuts.yesterday()     // Ontem
DateRangeShortcuts.today()         // Hoje
```

#### **DateRangeUtils (Avançado)**
```typescript
// Ranges básicos
DateRangeUtils.getCurrentMonthRange()
DateRangeUtils.getMonthRange(year, month)
DateRangeUtils.getLastNDaysRange(days)
DateRangeUtils.getCurrentYearRange()
DateRangeUtils.getCustomRange(startDate, endDate)

// Para APIs (retorna { date_start, date_end })
DateRangeUtils.getCurrentMonthAsApiParams()
DateRangeUtils.getCustomRangeAsApiParams(startDate, endDate)
DateRangeUtils.getLastNDaysAsApiParams(days)

// Formatação
DateRangeUtils.formatToISO(date)        // '2025-01-15'
DateRangeUtils.formatToISODateTime(date) // '2025-01-15T10:30:00.000Z'
```

### ✅ Benefícios

1. **✅ Formato ISO 8601 garantido** - Sem erros de validação no backend
2. **✅ Consistência** - Mesmo padrão em todo o projeto
3. **✅ Reutilização** - Utilities prontas para casos comuns
4. **✅ Manutenibilidade** - Centralização da lógica de datas
5. **✅ Type Safety** - Interfaces TypeScript bem definidas

### 🎯 Migração

Se você tem código como:
```typescript
// ❌ ANTES
{date_start: '2025-07-01&date_end=2025-07-31'}
{date_start: '2025-01-01', date_end: '2025-01-31'}
```

Migre para:
```typescript
// ✅ DEPOIS
const filters = DateRangeShortcuts.currentMonth();
const filters = DateRangeUtils.getMonthRange(2025, 1);
```

---

## 🔄 Próximas Utilities Planejadas

- **CurrencyUtils**: Formatação de moedas
- **ValidationUtils**: Validações comuns (CPF, CNPJ, etc.)
- **FileUtils**: Manipulação de arquivos
- **StringUtils**: Manipulação de strings 