# 🛰️ Sistema de Rastreamento em Tempo Real

## Visão Geral

O Sistema de Rastreamento em Tempo Real permite monitorar as viagens em andamento coletando dados GPS da tabela de viagens e exibindo no mapa em tempo real.

## Arquivos Principais

### 1. API de Rastreamento
- **Arquivo:** `backend-php/api/relatorios/rastreamento-tempo-real.php`
- **Função:** API que coleta dados GPS das viagens ativas
- **Endpoints:**
  - `?acao=rastreamento` - Lista viagens em andamento
  - `?acao=pontos_gps&viagem_id=X` - Pontos GPS de uma viagem específica
  - `?acao=stats` - Estatísticas gerais

### 2. Interface de Rastreamento
- **Arquivo:** `backend-php/admin/rastreamento-tempo-real.html`
- **Função:** Interface moderna com mapa interativo
- **Características:**
  - Atualização automática a cada 10 segundos
  - Mapa com marcadores coloridos (verde = com GPS, laranja = sem GPS)
  - Lista de viagens ativas na lateral
  - Controles para centralizar mapa e mostrar trajetos
  - Painel de debug em tempo real

### 3. Simulador de GPS
- **Arquivo:** `backend-php/simular-gps-tempo-real.php`
- **Função:** Simula dados GPS para demonstração
- **Funcionalidades:**
  - Criar viagens de teste
  - Simular movimento GPS
  - Modo automático para simulação contínua

## Como Usar

### 1. Acessar o Rastreamento
1. Acesse o dashboard: `backend-php/admin/dashboard.html`
2. Clique em **"Rastreamento Live"** (ícone com antena pulsante)
3. O sistema abrirá a tela de rastreamento em tempo real

### 2. Criar Dados de Teste
Para demonstrar o funcionamento:

1. Acesse: `backend-php/simular-gps-tempo-real.php`
2. Clique em **"Criar Nova Viagem de Teste"**
3. Clique em **"Simular Movimento"** para adicionar pontos GPS
4. Use **"Modo Automático"** para simulação contínua
5. Volte ao rastreamento para ver os dados atualizando

### 3. Funcionamento em Produção
Para viagens reais, o app Android deve:
1. Salvar pontos GPS na tabela `trajeto_pontos`
2. Manter a viagem ativa (sem `data_fim`)
3. O sistema automaticamente detectará e exibirá no mapa

## Estrutura do Banco

### Tabela `viagens`
```sql
- id (chave primária)
- tecnico_id (motorista)
- veiculo_id
- cliente
- data_inicio
- data_fim (NULL = viagem ativa)
- latitude_inicial
- longitude_inicial
```

### Tabela `trajeto_pontos`
```sql
- id (chave primária)
- viagem_id (FK para viagens)
- latitude
- longitude
- timestamp_ponto
- velocidade
- precisao
```

## Recursos da Interface

### Mapa Interativo
- **Marcadores Verdes:** Viagens com dados GPS atualizados
- **Marcadores Laranjas:** Viagens sem GPS ou com dados antigos
- **Popup:** Clique no marcador para ver detalhes da viagem
- **Trajetos:** Botão para mostrar/ocultar linhas do percurso

### Controles
- **Atualização Automática:** Liga/desliga atualização a cada 10s
- **Centralizar:** Ajusta zoom para mostrar todas as viagens
- **Trajetos:** Mostra/oculta linhas dos percursos
- **Stats:** Carrega estatísticas detalhadas

### Lista de Viagens
- Mostra todas as viagens ativas
- Cards clicáveis para focar no mapa
- Informações: cliente, motorista, veículo, duração, velocidade
- Status visual (com/sem GPS)

### Painel de Debug
- Log em tempo real das operações
- Informações de conexão com banco
- Contadores de viagens e atualizações

## API Response Format

### Rastreamento
```json
{
  "sucesso": true,
  "dados": [
    {
      "id": 123,
      "cliente": "Cliente XYZ",
      "motorista_nome": "João Silva",
      "veiculo_completo": "Civic - ABC1234",
      "duracao_minutos": 45,
      "posicao_atual": {
        "latitude": -10.9472,
        "longitude": -37.0731,
        "timestamp": "2024-01-15 14:30:00",
        "velocidade": 35.5,
        "precisao": 4.2,
        "fonte": "trajeto_pontos"
      },
      "total_pontos_gps": 25,
      "status": "com_gps",
      "tempo_ultima_atualizacao_segundos": 30
    }
  ],
  "total_viagens": 1,
  "timestamp": "2024-01-15 14:30:15"
}
```

### Pontos GPS
```json
{
  "sucesso": true,
  "viagem_id": 123,
  "pontos": [
    {
      "latitude": -10.9472,
      "longitude": -37.0731,
      "timestamp": "2024-01-15 14:00:00",
      "velocidade": 25.3,
      "precisao": 3.8
    }
  ],
  "total_pontos": 25
}
```

## Configuração

### Conexão com Banco
A API tenta automaticamente diferentes configurações:
1. `pinheir3` / `080880Gelboy` / `pinheir3_controle_frotasV1.1`
2. `root` / `080880Gelboy` / `pinheir3_controle_frotasV1.1`
3. `pinheir3` / `` / `pinheir3_controle_frotasV1.1`
4. `root` / `` / `controle_frotas`

### Atualização
- **Automática:** A cada 10 segundos (configurável)
- **Manual:** Botão "Atualizar" ou F5
- **Indicador:** Mostra status da atualização no canto superior direito

## Troubleshooting

### Problema: Mapa não carrega
- Verificar conexão com internet (usa OpenStreetMap)
- Verificar console do navegador (F12)

### Problema: Dados não aparecem
1. Verificar conexão com banco via debug panel
2. Usar simulador para criar dados de teste
3. Verificar se há viagens ativas (data_fim IS NULL)

### Problema: GPS desatualizado
- Verificar se app Android está salvando pontos na tabela `trajeto_pontos`
- Pontos mais antigos que 10 minutos podem aparecer como "sem GPS"

## Integração com App Android

Para integração completa, o app Android deve:

1. **Ao iniciar viagem:**
   ```sql
   INSERT INTO viagens (..., data_inicio, latitude_inicial, longitude_inicial) 
   VALUES (..., NOW(), lat, lng)
   ```

2. **Durante a viagem (a cada 30s-1min):**
   ```sql
   INSERT INTO trajeto_pontos (viagem_id, latitude, longitude, timestamp_ponto, velocidade, precisao)
   VALUES (id_viagem, lat, lng, NOW(), velocidade_kmh, precisao_metros)
   ```

3. **Ao finalizar viagem:**
   ```sql
   UPDATE viagens SET data_fim = NOW(), latitude_final = lat, longitude_final = lng
   WHERE id = id_viagem
   ```

## Performance

- **Otimizações:** Índices nas tabelas para consultas rápidas
- **Caching:** Dados atualizados apenas quando necessário
- **Fallbacks:** Sistema usa posição inicial se não há pontos GPS recentes
- **Limpeza:** Considerar arquivamento de pontos GPS antigos 
