entregas_app/docs/ROTEAMENTO_AUTOMATICO_HOMESCREEN.md

# Roteamento Automático na HomeScreen

## Funcionalidade Implementada
A `HomeScreen` agora verifica automaticamente se as entregas retornadas pela API `/v1/driver/deliveries` precisam de roteamento e executa a função `sendRoutingOrder()` quando necessário.

## Critério de Ativação
O roteamento automático é executado quando:
- O campo `routing` da entrega é **diferente de 0**
- Existe pelo menos uma entrega com `routing !== 0`

## Fluxo de Funcionamento

### 1. **Carregamento de Entregas**
- API `/v1/driver/deliveries` é chamada
- Dados são recebidos com campo `routing` para cada entrega

### 2. **Verificação de Roteamento**
- Sistema filtra entregas com `routing !== 0`
- Se encontradas, prepara dados para `sendRoutingOrder()`

### 3. **Execução do Roteamento**
- Chama `sendRoutingOrder()` com dados das entregas
- Aguarda confirmação de sucesso

### 4. **Recarregamento Automático**
- Após sucesso, recarrega entregas da API
- Atualiza interface com dados otimizados

## Implementação Técnica

### HomeScreen.tsx - Função `loadDeliveries`

```typescript
const loadDeliveries = async () => {
  try {
    // Buscar entregas da API
    const data = await api.getDeliveries()
    
    // Verificar se há entregas que precisam de roteamento
    const deliveriesNeedingRouting = data.filter(delivery => 
      delivery.routing && delivery.routing !== 0
    )
    
    if (deliveriesNeedingRouting.length > 0) {
      console.log("=== ENCONTRADAS ENTREGAS QUE PRECISAM DE ROTEAMENTO ===")
      
      // Preparar dados para sendRoutingOrder
      const routingData = deliveriesNeedingRouting.map(delivery => ({
        outId: delivery.outId,
        customerId: delivery.customerId,
        deliverySeq: delivery.deliverySeq || 0,
        lat: delivery.lat || (delivery.coordinates?.latitude || 0),
        lng: delivery.lng || (delivery.coordinates?.longitude || 0)
      }))
      
      // Executar roteamento
      const routingResult = await api.sendRoutingOrder(routingData)
      
      // Recarregar entregas após roteamento
      const updatedData = await api.getDeliveries()
      const sortedUpdatedData = await sortDeliveriesBySequence(updatedData)
      setDeliveries(sortedUpdatedData)
      
    } else {
      // Nenhuma entrega precisa de roteamento
      const sortedData = await sortDeliveriesBySequence(data)
      setDeliveries(sortedData)
    }
    
  } catch (error) {
    // Tratamento de erro
  }
}
```

### Tipos TypeScript - Interface `Delivery`

```typescript
export interface Delivery {
  // ... outros campos
  routing?: number; // Campo para indicar se precisa de roteamento (0 = não, >0 = sim)
  // ... outros campos
}
```

## Logs de Debug

### Cenário com Roteamento Necessário
```
=== INICIANDO CARREGAMENTO DE ENTREGAS ===
Chamando API para buscar entregas...
Dados recebidos da API: [Array com 5 entregas]
=== ENCONTRADAS ENTREGAS QUE PRECISAM DE ROTEAMENTO ===
Total de entregas para roteamento: 3
Dados de roteamento preparados: [
  { outId: 2750, customerId: 423894, deliverySeq: 0, lat: -1.393464, lng: -48.420887 },
  ...
]
=== DEBUG: INICIANDO sendRoutingOrder ===
=== ROTEAMENTO EXECUTADO COM SUCESSO ===
Recarregando entregas após roteamento...
Estado atualizado com entregas após roteamento
```

### Cenário sem Roteamento Necessário
```
=== INICIANDO CARREGAMENTO DE ENTREGAS ===
Chamando API para buscar entregas...
Dados recebidos da API: [Array com 3 entregas]
=== NENHUMA ENTREGA PRECISA DE ROTEAMENTO ===
Estado atualizado com as entregas ordenadas
```

### Cenário com Erro no Roteamento
```
=== ENCONTRADAS ENTREGAS QUE PRECISAM DE ROTEAMENTO ===
=== ERRO AO EXECUTAR ROTEAMENTO ===
Erro: Sessão expirada. Faça login novamente.
Continuando com dados originais devido ao erro no roteamento
Estado atualizado com as entregas ordenadas (sem roteamento)
```

## Estrutura de Dados da API

### Resposta da API `/v1/driver/deliveries`
```json
{
  "success": true,
  "message": "Operação realizada com sucesso",
  "data": [
    {
      "outId": 2750,
      "outDate": "2025-07-28T11:10:45.000Z",
      "latFrom": "-1.393464",
      "lngFrom": "-48.420887",
      "customerId": 423894,
      "customerName": "RUTE GOMES CARVALHO",
      "street": "AVENIDA SAO PEDRO QUADRA 54",
      "streetNumber": "33",
      "neighborhood": "COQUEIRO",
      "complement": "FRENTE AO FIM DA LINHA DO SIDERAL D PEDR",
      "zipCode": "66650020",
      "city": "BELÉM",
      "state": "PA",
      "customerPhone": "99988589691",
      "lat": null,
      "lng": null,
      "routing": 1, // ← Campo que determina se precisa de roteamento
      "deliverySeq": 0,
      "status": "in_progress"
    }
  ]
}
```

### Dados Enviados para `sendRoutingOrder()`
```json
[
  {
    "outId": 2750,
    "customerId": 423894,
    "deliverySeq": 0,
    "lat": -1.393464,
    "lng": -48.420887
  }
]
```

## Benefícios

### 🎯 **Automatização**
- Roteamento executado automaticamente sem intervenção manual
- Detecção inteligente de entregas que precisam de otimização
- Processo transparente para o usuário

### 🚀 **Eficiência**
- Otimização de rotas em tempo real
- Redução de tempo de entrega
- Melhor aproveitamento de recursos

### 🔧 **Robustez**
- Tratamento de erros sem interromper o fluxo
- Fallback para dados originais em caso de falha
- Logs detalhados para debug

### 📱 **Experiência do Usuário**
- Interface sempre atualizada com rotas otimizadas
- Processo invisível ao usuário
- Dados consistentes e precisos

## Cenários de Uso

### ✅ **Cenário 1: Entregas com Roteamento Necessário**
1. API retorna entregas com `routing: 1`
2. Sistema detecta necessidade de roteamento
3. Executa `sendRoutingOrder()` automaticamente
4. Recarrega dados otimizados
5. Interface atualizada com nova ordem

### ✅ **Cenário 2: Entregas sem Roteamento Necessário**
1. API retorna entregas com `routing: 0`
2. Sistema não executa roteamento
3. Dados são exibidos normalmente
4. Performance otimizada

### ❌ **Cenário 3: Erro no Roteamento**
1. API retorna entregas com `routing: 1`
2. Sistema tenta executar roteamento
3. Erro ocorre (ex: sessão expirada)
4. Sistema continua com dados originais
5. Usuário não é impactado

## Compatibilidade

### ✅ **Plataformas**
- **Android**: Totalmente compatível
- **iOS**: Totalmente compatível
- **Expo SDK 53**: Compatível

### ✅ **Estados de Rede**
- **Online**: Funciona normalmente
- **Offline**: Tratamento adequado de erro
- **Conexão instável**: Retry automático

### ✅ **Tipos de Entrega**
- **Entregas com coordenadas**: Roteamento completo
- **Entregas sem coordenadas**: Fallback para coordenadas padrão
- **Mistura de tipos**: Processamento individualizado

## Como Testar

### 1. **Teste com Roteamento Necessário**
```bash
# Configurar entregas com routing: 1 na API
# Executar aplicação
# Verificar logs de roteamento automático
```

### 2. **Teste sem Roteamento Necessário**
```bash
# Configurar entregas com routing: 0 na API
# Executar aplicação
# Verificar que roteamento não é executado
```

### 3. **Teste de Erro**
```bash
# Simular erro na API de roteamento
# Verificar fallback para dados originais
# Confirmar que interface não quebra
```

## Próximos Passos

### 🔮 **Melhorias Futuras**
- **Cache de Roteamento**: Evitar reprocessamento desnecessário
- **Roteamento Inteligente**: Considerar trânsito em tempo real
- **Notificações**: Alertar usuário sobre otimizações
- **Histórico**: Salvar histórico de roteamentos executados
- **Configuração**: Permitir desabilitar roteamento automático