# 🚚 Módulo de Rotas - ERP SAAS PraFrota

## 📁 Arquivos da Documentação

### 📋 Documentação Principal
- **`ROUTES_MODULE_DOCUMENTATION.md`** - Documentação técnica completa do módulo
  - Estrutura de dados (interfaces TypeScript)
  - Fluxos operacionais
  - Integração com app mobile
  - Especificações de UI/UX
  - Aspectos técnicos e integrações

### 📊 Dados Mockados
- **`ROUTES_MOCK_DATA_COMPLETE.json`** - 500 rotas mockadas (765KB)
  - Dados realistas baseados nas especificações
  - Coordenadas reais das regiões (RJ, SP, MG, ES)
  - Placas de veículos extraídas do sistema real
  - Distribuição correta por tipo, status e região

### 🔄 Sistema de Fallback
- **`FALLBACK_IMPLEMENTATION_GUIDE.md`** - Guia completo de implementação
  - Sistema de fallback automático para dados mockados
  - Indicadores visuais de conectividade
  - Monitoramento de backend em tempo real
- **`FALLBACK_SIMPLE_EXAMPLE.ts`** - Exemplo simplificado para implementação rápida
  - Service com fallback automático
  - Exemplo de component e template
  - Instruções de configuração

### 🛠️ Scripts e Dados de Origem
- **`generate_routes_data.py`** - Script Python para gerar dados mockados
  - Configurável para diferentes quantidades
  - Baseado em dados reais do CSV
  - Distribuição estatística correta
- **`mercado-lives_export.csv`** - Dados reais de placas de veículos
  - Fonte dos dados para geração das rotas
  - Placas reais do sistema PraFrota

## 📍 Localização dos Arquivos

Todos os arquivos estão organizados em:
```
/projects/idt_app/docs/router/
├── ROUTES_MODULE_DOCUMENTATION.md
├── ROUTES_MOCK_DATA_COMPLETE.json
├── ROUTES_MOCK_DATA.json
├── ROUTES_README.md
├── generate_routes_data.py
└── mercado-lives_export.csv
```

## 🎯 Como Usar

### 1. Para Desenvolvedores Frontend

#### 🔄 Implementação com Fallback (Recomendado)
```typescript
// Service com fallback automático
@Injectable({ providedIn: 'root' })
export class RoutesService {
  private mockRoutes = require('./docs/router/ROUTES_MOCK_DATA_COMPLETE.json').routes;

  getRoutes(): Observable<any> {
    return this.http.get('/api/routes').pipe(
      catchError(() => {
        console.warn('Backend offline, usando dados mockados');
        return of({ data: this.mockRoutes, source: 'fallback' });
      })
    );
  }
}
```

#### 📊 Importação Direta dos Dados
```typescript
// Importar interface principal
interface Route {
  id: string;
  routeNumber: string;
  type: 'firstMile' | 'lineHaul' | 'lastMile';
  // ... outros campos (ver documentação)
}

// Usar dados mockados
import routesData from './docs/router/ROUTES_MOCK_DATA_COMPLETE.json';
const routes: Route[] = routesData.routes;
```

### 2. Para Backend/API
```json
// Estrutura de resposta da API
{
  "data": [...], // Array de rotas
  "pagination": {
    "total": 500,
    "page": 1,
    "limit": 50
  },
  "filters": {
    "type": ["firstMile", "lineHaul", "lastMile"],
    "status": ["pending", "inProgress", "completed", "delayed", "cancelled"]
  }
}
```

### 3. Para Testes
```javascript
// Usar dados mockados em testes
describe('Routes Module', () => {
  const mockRoutes = require('./docs/router/ROUTES_MOCK_DATA_COMPLETE.json').routes;
  
  it('should handle different route types', () => {
    const firstMileRoutes = mockRoutes.filter(r => r.type === 'firstMile');
    expect(firstMileRoutes.length).toBe(300);
  });
});
```

### 4. Para Regenerar Dados
```bash
# Navegar para a pasta
cd /Users/ceogrouppra/projects/front/web/angular/projects/idt_app/docs/router

# Executar script de geração
python3 generate_routes_data.py

# Arquivo gerado: ROUTES_MOCK_DATA_COMPLETE.json
```

## 📈 Estatísticas dos Dados Mockados

### Distribuição por Tipo:
- **First Mile**: 300 rotas (60%) - Coleta em centros de distribuição
- **Line Haul**: 126 rotas (25%) - Transporte entre cidades  
- **Last Mile**: 74 rotas (15%) - Entrega final (marketplaces)

### Distribuição por Status:
- **Em Progresso**: 203 rotas (40%)
- **Completadas**: 162 rotas (32%)
- **Atrasadas**: 58 rotas (12%)
- **Pendentes**: 49 rotas (10%)
- **Canceladas**: 28 rotas (6%)

### Distribuição por Região:
- **São Paulo**: 187 rotas (37%)
- **Rio de Janeiro**: 150 rotas (30%)
- **Minas Gerais**: 120 rotas (24%)
- **Vitória/ES**: 43 rotas (9%)

## 🚀 Próximos Passos

### Implementação Frontend:
1. **Criar componente Routes** seguindo padrão `BaseDomainComponent`
2. **Implementar filtros avançados** conforme especificação
3. **Adicionar visualização em mapa** para tracking
4. **Desenvolver sistema de abas** para detalhes da rota

### Implementação Backend:
1. **Criar endpoints REST** para CRUD de rotas
2. **Implementar filtros e paginação** server-side
3. **Integrar com APIs externas** (geocoding, routing)
4. **Desenvolver sistema de notificações** push

### Integração Mobile:
1. **Sincronização bidirecional** web ↔ mobile
2. **Implementar eventos de rota** (início, paradas, fim)
3. **Sistema de evidências** (fotos, assinaturas)
4. **Modo offline** para áreas sem cobertura

## 🔧 Configuração do Ambiente

### Dependências Frontend:
```bash
npm install @angular/google-maps
npm install leaflet @types/leaflet
npm install date-fns
```

### Variáveis de Ambiente:
```typescript
// environment.ts
export const environment = {
  googleMapsApiKey: 'YOUR_GOOGLE_MAPS_API_KEY',
  routingApiUrl: 'https://api.routing.service.com',
  geocodingApiUrl: 'https://api.geocoding.service.com'
};
```

## 📱 Sidebar do Sistema

O módulo "Rotas" deve ser adicionado ao sidebar com:
- **Label**: "Rotas"
- **Ícone**: `fa-route`
- **Posição**: Após "Veículos" e "Motoristas"
- **Permissões**: Baseadas no perfil do usuário

## 🎨 Padrões de UI

### Badges de Status:
- 🟡 **Pending**: `badge-warning`
- 🔵 **InProgress**: `badge-primary` 
- 🟢 **Completed**: `badge-success`
- 🔴 **Delayed**: `badge-danger`
- ⚫ **Cancelled**: `badge-secondary`

### Badges de Tipo:
- 🟢 **First Mile**: `badge-success`
- 🟠 **Line Haul**: `badge-warning`
- 🔵 **Last Mile**: `badge-info`

## 🔍 Campos de Busca Recomendados

### Filtros Principais:
- Período (data início/fim)
- Status da rota
- Tipo de rota
- Motorista
- Veículo (placa)
- Cliente/Embarcador
- Cidade origem/destino

### Ordenação:
- Data criação (mais recente primeiro)
- Status (em progresso primeiro)
- Valor (maior primeiro)
- Distância

## 📞 Contato e Suporte

Para dúvidas sobre a implementação do módulo de Rotas:
- **Documentação**: Consulte `router/ROUTES_MODULE_DOCUMENTATION.md`
- **Dados de Teste**: Use `router/ROUTES_MOCK_DATA_COMPLETE.json`
- **Geração de Dados**: Execute `cd router && python3 generate_routes_data.py`

---

**Versão**: 1.0  
**Última Atualização**: 28/12/2024  
**Localização**: `/projects/idt_app/docs/router/`  
**Autor**: ERP SAAS PraFrota Team