testes/Modulos Angular/projects/idt_app/docs/router/ROUTES_MODULE_DOCUMENTATION.md

📋 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

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

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

RouteCost (Custos da Rota)

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)

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:

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:

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.