Ferramentas de Importação de Dados

As Ferramentas de Importação de Dados permitem a importação em massa de dados de clientes, corridas e veículos a partir de arquivos CSV. Este guia cobre todas as capacidades de importação, requisitos de formato de arquivo e melhores práticas para uma migração de dados bem-sucedida.

Acessando Ferramentas de Importação de Dados

Navegue até Admin > Ferramentas de Banco de Dados para acessar a interface de importação.

Requisitos:

• Acesso de Admin ao sistema
• Arquivos CSV formatados corretamente
• Dados que correspondam ao schema esperado

Visão Geral

Tipos de Importação Disponíveis

Fluxo de Importação

---

Importação de Clientes

Acessando Importação de Clientes

Em Ferramentas de Banco de Dados, localize o card "Importação de Clientes" e clique para acessar.

Requisitos de Formato CSV

Delimitador: Ponto e vírgula (;)

Colunas Obrigatórias:

• ID - Identificador único (torna-se original_id)

Colunas Suportadas:

Processo de Importação

Arquivos Pequenos (< 4 MB):

1. Clique em "Selecionar Arquivo" ou arraste e solte
2. Clique em "Importar"
3. O processamento acontece de forma síncrona
4. Os resultados são exibidos imediatamente

Arquivos Grandes (4+ MB):

1. O upload inicia o processamento em lote
2. O arquivo é dividido em lotes de 500 linhas
3. O progresso é rastreado via jobs de importação
4. Notificação quando completo

Resultados da Importação

Após a importação ser concluída, você verá:

• Processados: Total de linhas lidas do arquivo
• Importados: Novos registros criados
• Atualizados: Registros existentes atualizados
• Erros: Linhas que falharam na importação

Detalhes de Erros: Os primeiros 10 erros são mostrados com:

• Número da linha
• ID do cliente (se disponível)
• Mensagem de erro

---

Importação de Corridas

Acessando Importação de Corridas

Em Ferramentas de Banco de Dados, localize o card "Importação de Corridas" e clique para acessar.

Requisitos de Formato CSV

Delimitador: Ponto e vírgula (;)

Colunas Principais:

Colunas Adicionais (50+ no total):

• IDs de zona (estacionamento, pago, proibido, bônus, limite de velocidade, proibido)
• Coordenadas de localização (posições de início/fim)
• Detalhes de assinatura
• Informações de pacote de preços
• Dados de precificação dinâmica

Comportamento da Importação

A importação de corridas automaticamente:

1. Cria clientes ausentes (se o User ID for fornecido)
2. Cria veículos ausentes (se o Vehicle ID for fornecido)
3. Vincula corridas a clientes e veículos existentes
4. Trata corridas duplicadas via upsert no ID da corrida

Resultados da Importação

Após a importação:

• Verifique as contagens totais nas Estatísticas do Banco de Dados
• Verifique a criação de clientes e veículos
• Revise quaisquer mensagens de erro

---

Importação de Veículos

Formato

A importação de veículos usa formato JSON (não CSV):

[
  {
    "vehicle_number": "VH-001",
    "iot_imei": "123456789012345",
    "vin": "1HGBH41JXMN109186",
    "vehicle_model": "Scooter Pro"
  },
  {
    "vehicle_number": "VH-002",
    "iot_imei": "123456789012346"
  }
]

Campos Obrigatórios

• vehicle_number - Obrigatório - Identificador único para o veículo

Campos Opcionais

• iot_imei - Número IMEI do dispositivo IoT
• vin - Número de Identificação do Veículo
• vehicle_model - Nome ou ID do modelo
• Campos adicionais conforme necessário

Resultado da Importação

Retorna resultados por veículo:

• Status de sucesso ou falha
• Mensagem de erro para linhas com falha
• Vinculação automática a dispositivos IoT por IMEI

---

Importação de Dispositivos IoT

Formato

A importação de dispositivos IoT usa formato JSON:

[
  {
    "imei": "123456789012345",
    "device_type": "Rastreador",
    "firmware_version": "2.1.0"
  }
]

Campos Obrigatórios

• imei - Obrigatório - Número IMEI do dispositivo

Vinculação a Veículos

Após a importação, os dispositivos podem ser vinculados a veículos:

• Manualmente via edição de veículo
• Automaticamente se o veículo tiver IMEI correspondente
• Via requisição PUT para a API

---

Rastreamento de Jobs de Importação

Como os Jobs Funcionam

Para arquivos grandes e importações em segundo plano:

1. Job Criado: O sistema cria um registro em import_jobs
2. Status: Processando: O arquivo está sendo analisado e importado
3. Atualizações de Progresso: A contagem de linhas processadas aumenta
4. Conclusão: O status muda para completed ou completed_with_errors

Status dos Jobs

Visualizando Jobs Ativos

Na página de Importação Stripe, os jobs ativos são exibidos com:

• Barra de progresso (processados/total de linhas)
• Indicador de status
• Contagens de Importados/Atualizados/Ignorados/Erros
• Hora de início e nome do arquivo

Polling de Jobs

O sistema consulta a cada 2 segundos por atualizações de jobs enquanto você está na página de importação.

---

Tratamento de Erros

Erros Comuns

Limites de Erros

• O processamento para após 100 erros consecutivos
• Os primeiros 10 detalhes de erros são mostrados na UI
• Log de erros completo disponível no registro do job de importação

Tratando Importações Parciais

Se a importação parar no meio:

1. Anote a última linha bem-sucedida
2. Corrija os erros nas linhas restantes
3. Reimporte apenas os dados restantes
4. Ou limpe e reimporte tudo

---

Diretrizes de Tamanho de Arquivo

Dicas para Arquivos Grandes

1. Divida arquivos muito grandes: Quebre em chunks de 50.000 linhas
2. Teste primeiro: Importe uma pequena amostra antes da importação completa
3. Horários de baixo tráfego: Execute importações grandes durante períodos de baixo tráfego
4. Monitore o progresso: Acompanhe o status do job para identificar problemas

---

Tabelas de Staging

Como o Staging Funciona

1. Dados CSV são carregados em uma tabela de staging (ex: users_import)
2. A função RPC transforma e valida os dados
3. Registros válidos são inseridos/atualizados na tabela principal
4. A tabela de staging é limpa (ou retida para auditoria)

Tabelas de Staging

---

Melhores Práticas

Antes da Importação

1. Faça backup dos dados existentes: Exporte os dados atuais primeiro
2. Valide o formato CSV: Verifique delimitador, codificação, cabeçalhos
3. Teste com amostra: Importe 10-20 linhas primeiro
4. Anote as contagens atuais: Registre estatísticas para comparação

Durante a Importação

1. Não navegue para outra página: Fique na página para importações síncronas
2. Monitore o progresso: Acompanhe o status do job para importações grandes
3. Anote quaisquer erros: Tire screenshots ou registre mensagens de erro

Após a Importação

1. Verifique as contagens: Confira as Estatísticas do Banco de Dados
2. Verifique registros aleatórios: Revise alguns registros importados
3. Teste a funcionalidade: Garanta que os dados importados funcionam corretamente
4. Documente a importação: Registre o que foi importado e quando

---

Transformação de Dados

Transformações Automáticas

Durante a importação, os dados são automaticamente:

• Aparados de espaços em branco
• Strings vazias convertidas para NULL
• Datas analisadas para timestamps
• Números analisados a partir de strings
• Strings booleanas (TRUE/FALSE/Yes/No) convertidas

Preparação Manual

Antes da importação, garanta:

• Sem linhas de cabeçalho extras
• Formatos de data consistentes
• Formatos de e-mail válidos
• Números de telefone formatados consistentemente
• Sem caracteres especiais em IDs

---

Solução de Problemas

Upload de Arquivo Falha

Possíveis Causas:

• Arquivo muito grande
• Tipo de arquivo errado
• Timeout de rede

Soluções:

• Reduza o tamanho do arquivo
• Garanta a extensão .csv
• Verifique a conexão de rede

Importação Conclui mas Sem Novos Registros

Possíveis Causas:

• Todos os registros já existem
• Coluna ID mapeia para registros existentes
• Upsert atualizou em vez de inserir

Soluções:

• Verifique atualizações (não apenas inserções)
• Verifique os valores da coluna ID
• Revise as estatísticas de importação cuidadosamente

Muitos Registros Falhando

Possíveis Causas:

• Delimitador errado (vírgula vs ponto e vírgula)
• Incompatibilidade de nome de coluna
• Problemas de formato de dados

Soluções:

• Verifique o delimitador ponto e vírgula
• Confira se os cabeçalhos das colunas correspondem exatamente
• Valide os formatos de dados

---

Próximos Passos

• Recursos de Super Admin - Aprenda sobre administração da plataforma
• Sincronização de Dados Stripe - Importe dados de pagamento do Stripe
• Guia de Início Rápido - Comece com o gerenciamento de frota