# 📋 Documentação Técnica - Módulo de Rotas
## ERP SAAS para Transportadoras

---

## 🎯 Visão Geral do Módulo

O módulo **Rotas** é o núcleo operacional do sistema, conectando todos os elementos já existentes (motoristas, veículos, rastreamento) em um fluxo completo de gestão de viagens de transporte.

### Integração com Módulos Existentes:
- ✅ **Motoristas**: Atribuição automática e manual
- ✅ **Veículos**: Vinculação com telemetria em tempo real
- ✅ **Rastreamento**: Monitoramento GPS contínuo
- ✅ **App Mobile**: Sincronização bidirecional de status

### Localização no Sistema:
- **Sidebar**: "Rotas"
- **Ícone**: `fa-route`
- **Ordem**: Após "Veículos" e "Motoristas"

---

## 🏗️ Estrutura de Dados (camelCase)

### 📊 Entidade Principal: `Route`

```typescript
interface Route {
  // Identificação
  id: string;
  routeNumber: string; // Ex: "RT-2024-001234"
  
  // Classificação
  type: 'firstMile' | 'lineHaul' | 'lastMile';
  modal: 'rodoviario' | 'aereo' | 'aquaviario';
  priority: 'normal' | 'express' | 'urgent';
  
  // Participantes
  driverId: string;
  vehicleId: string;
  companyId: string;
  customerId: string;
  
  // Trajeto
  origin: {
    address: string;
    coordinates: { lat: number; lng: number };
    contact: string;
    phone: string;
  };
  destination: {
    address: string;
    coordinates: { lat: number; lng: number };
    contact: string;
    phone: string;
  };
  
  // Cronograma
  scheduledDeparture: Date;
  actualDeparture?: Date;
  estimatedArrival: Date;
  actualArrival?: Date;
  
  // Status operacional
  status: 'pending' | 'inProgress' | 'completed' | 'delayed' | 'cancelled';
  currentLocation?: { lat: number; lng: number };
  
  // Financeiro
  contractId: string;
  tablePricesId: string;
  totalValue: number;
  totalWeight: number; // em kg
  estimatedCost: number;
  actualCost?: number;
  
  // Produto
  productType: string; // Ex: "Medicamentos", "Eletrônicos", "Alimentos"
  
  // Metadados
  createdAt: Date;
  updatedAt: Date;
  createdBy: string;
}
```

### 📦 Entidades Relacionadas

#### `RouteStop` (Paradas da Rota) ⚠️ **ATUALIZADO - Ver especificação completa**
```typescript
interface RouteStop {
  id: string;
  routeId: string;
  sequence: number;
  type: 'pickup' | 'delivery' | 'rest' | 'fuel';
  
  location: {
    address: string;
    coordinates: { lat: number; lng: number };
    contact?: string;
    phone?: string;
    cep?: string;
    city?: string;
    state?: string;
  };
  
  scheduledTime: Date;
  actualTime?: Date;
  status: 'pending' | 'completed' | 'failed' | 'skipped';
  
  // Dados específicos de entrega/coleta
  packages?: number;
  weight?: number;
  volume?: number;
  referenceNumber?: string;
  
  // 📄 NOVO: Documento Fiscal Integrado
  fiscalDocument?: FiscalDocument;
  
  // Evidências do app mobile
  photos?: string[];
  signature?: string;
  notes?: string;
  completionEvidence?: {
    photoPackage: string;
    photoReceipt: string;
    digitalSignature: string;
    recipientName: string;
    completionTime: Date;
  };
}

// 📄 NOVA Interface para Documentos Fiscais
interface FiscalDocument {
  fiscalDocumentId: string;
  documentType: 'NFe' | 'NFCe';
  documentNumber: string;
  series: string | null;
  accessKey: string | null;
  issueDate: Date;
  totalValue: number;
  productType: string;
  status: 'pending' | 'validated' | 'error';
  createdAt: Date;
  updatedAt: Date;
}
```

**📋 Especificação Completa**: Ver [ROUTE_STOPS_MODULE_SPECIFICATION.md](./ROUTE_STOPS_MODULE_SPECIFICATION.md)

#### `RouteCost` (Custos da Rota)
```typescript
interface RouteCost {
  id: string;
  routeId: string;
  
  type: 'fuel' | 'toll' | 'parking' | 'fine' | 'maintenance' | 'other';
  description: string;
  amount: number;
  currency: 'BRL';
  
  // Vinculação automática por telemetria
  autoDetected: boolean;
  vehicleTrackingEventId?: string;
  
  // Dados da transação
  transactionDate: Date;
  location?: { lat: number; lng: number };
  receiptPhoto?: string;
  
  // Aprovação
  status: 'pending' | 'approved' | 'rejected';
  approvedBy?: string;
  approvedAt?: Date;
}
```

#### `RouteDocument` (Documentos da Rota)
```typescript
interface RouteDocument {
  id: string;
  routeId: string;
  
  type: 'cte' | 'nfe' | 'deliveryProof' | 'receipt' | 'fine' | 'other';
  name: string;
  fileUrl: string;
  fileSize: number;
  mimeType: string;
  
  uploadedBy: string;
  uploadedAt: Date;
  source: 'web' | 'mobile' | 'automatic';
}
```

---

## 🖥️ Interface do Usuário

### 📋 Tela Principal - Lista de Rotas

**Layout baseado nas imagens de referência:**

#### Filtros Avançados:
```typescript
interface RouteFilters {
  dateRange: { start: Date; end: Date };
  status: RouteStatus[];
  driverId?: string;
  vehicleId?: string;
  type?: RouteType[];
  modal?: RouteModal[];
  originCity?: string;
  destinationCity?: string;
  customerId?: string;
  productType?: string;
}
```

#### Colunas da Tabela:
1. **Ações** (checkbox, editar)
2. **ID** (routeNumber)
3. **Tipo** (badge colorido: First Mile 🟢, Line Haul 🟠, Last Mile 🔵)
4. **Cliente/Embarcador**
5. **Origem → Destino**
6. **Status** (badge: Pendente, Em Trânsito, Entregue, Atrasada)
7. **Data/Hora Início**
8. **Motorista**
9. **Veículo** (placa)
10. **Valor** (totalValue)
11. **Peso** (totalWeight)
12. **Produto** (productType)

#### Estados de Status:
- 🟡 **Pending**: Rota criada, aguardando início
- 🔵 **InProgress**: Veículo em movimento
- 🟢 **Completed**: Rota finalizada com sucesso
- 🔴 **Delayed**: Passou do prazo estimado
- ⚫ **Cancelled**: Rota cancelada

### 📍 Tela de Detalhes da Rota

**Estrutura em abas (baseada no padrão do sistema):**

#### Aba 1: Dados Básicos
- Informações gerais da rota
- Origem e destino
- Cronograma planejado vs real
- Status atual
- Dados do contrato e tabela de preços

#### Aba 2: Localização
- **Mapa em tempo real** com posição atual do veículo
- Histórico de trajeto
- Paradas planejadas vs realizadas
- Alertas de desvio de rota

#### Aba 3: Paradas
- Lista de todas as paradas (coletas/entregas)
- Status de cada parada
- Evidências fotográficas do app mobile
- Assinaturas digitais

#### Aba 4: Custos
- Custos automáticos (combustível, pedágios)
- Custos manuais inseridos
- Aprovação de custos
- Margem de lucro da rota

#### Aba 5: Documentos
- CT-e, NF-e
- Fotos de entrega
- Comprovantes de custos
- Relatórios gerados

#### Aba 6: Histórico
- Log de alterações de status
- Comunicações com motorista
- Eventos de telemetria relevantes

---

## 📱 Integração com App Mobile

### Sincronização Bidirecional:

#### Do Web para Mobile:
- Nova rota atribuída ao motorista
- Alterações no cronograma
- Novas paradas adicionadas
- Instruções especiais

#### Do Mobile para Web:
- Início/fim da rota
- Check-in em paradas
- Fotos de entrega
- Assinaturas digitais
- Ocorrências (atraso, problema)

### Eventos do App Mobile:
```typescript
interface MobileRouteEvent {
  id: string;
  routeId: string;
  driverId: string;
  
  type: 'routeStarted' | 'stopArrived' | 'deliveryCompleted' | 
        'pickupCompleted' | 'routeCompleted' | 'incidentReported';
  
  timestamp: Date;
  location: { lat: number; lng: number };
  
  data: {
    photos?: string[];
    signature?: string;
    recipientName?: string;
    notes?: string;
    incidentType?: string;
  };
}
```

---

## 🔄 Fluxo Operacional

### 1. Criação da Rota
1. **Planejamento**: Definir origem, destino, paradas
2. **Atribuição**: Selecionar motorista e veículo
3. **Cronograma**: Definir horários de partida e chegada
4. **Contrato**: Vincular contractId e tablePricesId
5. **Aprovação**: Validar rota antes do envio

### 2. Execução da Rota
1. **Notificação**: Motorista recebe rota no app
2. **Início**: Motorista confirma saída
3. **Monitoramento**: Tracking GPS contínuo
4. **Paradas**: Check-in/out em cada localização
5. **Evidências**: Fotos e assinaturas coletadas

### 3. Finalização
1. **Chegada**: Confirmação de entrega final
2. **Custos**: Reconciliação de gastos
3. **Documentação**: Upload de comprovantes
4. **Fechamento**: Análise financeira da rota

---

## 💰 Gestão Financeira

### Custos Automáticos (via Telemetria):
- **Combustível**: Baseado em consumo real do veículo
- **Pedágios**: Detecção automática por localização
- **Tempo de motor ligado**: Custos operacionais

### Custos Manuais:
- Estacionamentos
- Refeições
- Manutenções emergenciais
- Multas

### Receitas:
- Valor do frete (totalValue)
- Taxas adicionais
- Bonificações por performance

### Indicadores:
- **Margem da Rota**: (totalValue - actualCost) / totalValue
- **Custo por KM**: actualCost / Distância percorrida
- **Custo por KG**: actualCost / totalWeight
- **ROI por Veículo**: Análise de rentabilidade

---

## 🚨 Alertas e Notificações

### Alertas Automáticos:
- **Atraso**: Rota com mais de 30min de atraso
- **Desvio**: Veículo fora da rota planejada
- **Parada Prolongada**: Mais de 2h parado sem justificativa
- **Combustível**: Nível baixo detectado

### Notificações para Stakeholders:
- **Cliente**: Status de entrega atualizado
- **Motorista**: Novas instruções ou alterações
- **Gestor**: Relatórios de performance
- **Financeiro**: Custos que excedem orçamento

---

## 📊 Relatórios e Analytics

### Dashboards:
1. **Operacional**: Rotas em andamento, atrasos, performance
2. **Financeiro**: Custos, receitas, margens por período
3. **Motoristas**: Ranking, eficiência, cumprimento de prazos
4. **Veículos**: Utilização, consumo, manutenções

### Relatórios Exportáveis:
- Relatório de rota individual (PDF)
- Planilha de custos por período
- Análise de performance de motoristas
- Relatório de compliance (documentação)

---

## 🔧 Aspectos Técnicos

### APIs Necessárias:
- **Geocoding**: Conversão endereço ↔ coordenadas
- **Routing**: Cálculo de rotas otimizadas
- **Telemetria**: Integração com rastreadores
- **CTe/NFe**: Integração com SEFAZ para documentos fiscais

### Integrações:
- **ERP Clientes**: Importação automática de pedidos
- **Sistemas de Pagamento**: Cobrança automática
- **WhatsApp Business**: Notificações para clientes
- **Sistemas de Combustível**: Cartões corporativos

### Performance:
- Cache de rotas ativas para consulta rápida
- Indexação por data, status, motorista, veículo
- Compressão de imagens do mobile
- Sincronização offline no app mobile

---

## 🎯 Próximos Passos de Implementação

### Fase 1 - MVP:
1. ✅ CRUD básico de rotas
2. ✅ Atribuição motorista/veículo
3. ✅ Tracking GPS básico
4. ✅ Status manual no app mobile

### Fase 2 - Operacional:
1. 🔄 Sistema de paradas
2. 🔄 Upload de evidências (fotos/assinaturas)
3. 🔄 Gestão de custos
4. 🔄 Relatórios básicos

### Fase 3 - Avançado:
1. ⏳ Alertas automáticos
2. ⏳ Otimização de rotas
3. ⏳ Integração fiscal (CTe)
4. ⏳ Analytics avançados

---

## 📋 Checklist de Funcionalidades

### Interface Web:
- [ ] Lista de rotas com filtros avançados
- [ ] Formulário de criação/edição de rota
- [ ] Visualização em mapa (tempo real)
- [ ] Gestão de paradas
- [ ] Upload de documentos
- [ ] Relatórios financeiros
- [ ] Dashboard operacional

### App Mobile:
- [ ] Lista de rotas do motorista
- [ ] Navegação integrada
- [ ] Check-in/out em paradas
- [ ] Captura de fotos
- [ ] Assinatura digital
- [ ] Relatório de ocorrências
- [ ] Modo offline

### Integrações:
- [ ] API de rastreamento
- [ ] Geocoding/routing
- [ ] Sincronização web ↔ mobile
- [ ] Notificações push
- [ ] Integração financeira
- [ ] Backup automático

---

## 📈 Dados Mockados (500 Rotas)

### Distribuição por Tipo:
- **First Mile**: 60% (300 rotas) - Coleta em centros de distribuição
- **Line Haul**: 25% (125 rotas) - Transporte entre cidades
- **Last Mile**: 15% (75 rotas) - Entrega final (Mercado Livre, Shopee, Amazon)

### Distribuição por Modal:
- **Rodoviário**: 95% (475 rotas)
- **Aéreo**: 3% (15 rotas)
- **Aquaviário**: 2% (10 rotas)

### Distribuição por Status:
- **Pending**: 10% (50 rotas)
- **InProgress**: 40% (200 rotas)
- **Completed**: 35% (175 rotas)
- **Delayed**: 10% (50 rotas)
- **Cancelled**: 5% (25 rotas)

### Regiões Contempladas:
- **Rio de Janeiro**: 30% (150 rotas)
- **São Paulo**: 35% (175 rotas)
- **Minas Gerais**: 25% (125 rotas)
- **Vitória/ES**: 10% (50 rotas)

### Tipos de Produtos:
- Medicamentos
- Eletrônicos
- Alimentos Perecíveis
- Alimentos Não Perecíveis
- Roupas e Acessórios
- Livros e Papelaria
- Casa e Decoração
- Cosméticos
- Automotive
- Brinquedos

### Características das Rotas Last Mile:
- **Endereços residenciais** em bairros urbanos
- **Marketplace**: Mercado Livre (40%), Shopee (35%), Amazon (25%)
- **Veículos menores**: Van, Veículo de Passeio, Rental Utilitário
- **Peso médio**: 2-15kg por entrega
- **Valor médio**: R$ 25,00 - R$ 150,00

### Placas de Veículos Reais:
Utilizando dados do arquivo `mercado-lives_export.csv`:
- TAS4J92, MSO5821, TAS2F98, RJZ7H79, TAO3J98
- TAN6I73, SGD4H03, NGF2A53, TAS2F32, RTT1B46
- EZQ2E60, TDZ4J93, SGL8D98, TAS2F83, RVC0J58
- E mais 250+ placas reais do sistema

---

Esta documentação serve como base para o desenvolvimento do módulo de Rotas, mantendo consistência com os padrões já estabelecidos no sistema e aproveitando as integrações existentes.