Estatisticas do Banco de Dados

O recurso de Estatisticas do Banco de Dados fornece aos administradores do sistema uma visao geral de alto nivel das contagens de registros do banco de dados e atividades de importacao. Esses dados ajudam a monitorar a saude do sistema, acompanhar o crescimento e verificar operacoes de importacao de dados.

Acessando Estatisticas do Banco de Dados

Navegue ate Admin > Ferramentas de Banco de Dados na navegacao de admin. As estatisticas sao exibidas no topo da pagina em cartoes de resumo.

Visao Geral

As Estatisticas do Banco de Dados exibem quatro metricas principais:

Entendendo Cada Metrica

Total de Clientes

O que conta: Todas as linhas na tabela customers

Inclui:

• Clientes ativos
• Clientes bloqueados
• Clientes com sinalizacoes de verificacao de identidade
• Todos os status e estados

NAO inclui:

• Registros excluidos permanentemente (se houver)
• Registros excluidos de forma reversivel SAO incluidos na contagem

Formato: Numero com separadores de milhar (ex: "12.450")

Total de Viagens

O que conta: Todas as linhas na tabela rides

Inclui:

• Viagens ativas
• Viagens concluidas
• Viagens canceladas
• Viagens pausadas
• Todos os status de viagem

NAO inclui:

• Registros excluidos permanentemente (se houver)

Formato: Numero com separadores de milhar (ex: "156.789")

Total de Veiculos

O que conta: Todas as linhas na tabela vehicles

Inclui:

• Veiculos disponiveis
• Veiculos em uso
• Veiculos em manutencao
• Veiculos offline
• Todos os status

Formato: Numero com separadores de milhar (ex: "342")

Ultima Importacao

O que mostra: Timestamp da operacao de importacao de dados mais recente

Tipos de importacao rastreados:

• customers_csv_import - Importacoes CSV de clientes
• rides_csv_import - Importacoes CSV de viagens
• csv_import - Importacoes CSV gerais
• manual_sync - Operacoes de sincronizacao da API do Stripe

Formato: String de data e hora localizada (ex: "25/12/2025, 14:30:45")

Se nao houver importacoes: Exibe "Nunca"

Como as Estatisticas Sao Calculadas

Consultas em Tempo Real

Cada estatistica e calculada em tempo real via consultas ao banco de dados:

1. Contagem de Clientes: SELECT COUNT(*) FROM customers
2. Contagem de Viagens: SELECT COUNT(*) FROM rides
3. Contagem de Veiculos: SELECT COUNT(*) FROM vehicles
4. Ultima Importacao: SELECT processed_at FROM stripe_webhook_logs WHERE event_type IN (...) ORDER BY processed_at DESC LIMIT 1

Desempenho das Consultas

• Usa a operacao otimizada COUNT(*) do PostgreSQL
• Opcao head: true retorna apenas metadados (sem dados de linha)
• Colunas indexadas suportam buscas rapidas
• Tempo de resposta tipico: 200-500ms

A Pagina de Ferramentas de Banco de Dados

Layout da Pagina

A pagina de Ferramentas de Banco de Dados e dividida em secoes:

1. Cartoes de Estatisticas (topo) - As quatro metricas descritas acima
2. Grade de Ferramentas de Importacao - Botoes para importacoes de clientes, viagens e Stripe
3. Secao de Ajuda - Instrucoes e requisitos de formato de arquivo

Exibicao dos Cartoes de Estatisticas

Cada cartao mostra:

• Icone: Indicador visual com fundo colorido
• Valor: Valor numerico ou de data grande
• Rotulo: Descricao da metrica

Comportamento de Atualizacao

Estatisticas:

• Carregam na visita a pagina
• Atualizacao manual necessaria para updates
• Sem atualizacao automatica (para reduzir carga do servidor)

Interpretacao de Dados

Monitorando o Crescimento

Acompanhe metricas ao longo do tempo para monitorar:

• Taxas de aquisicao de clientes
• Tendencias de volume de viagens
• Expansao da frota

Verificando Importacoes

Apos executar uma importacao:

Identificando Problemas

Controles de Acesso

Estado Atual

A API de Estatisticas do Banco de Dados (/api/admin/database/stats) e acessivel sem verificacao explicita de funcao.

Acesso Recomendado

Integracao com Ferramentas de Importacao

Verificacao Pre-Importacao

Antes de executar qualquer importacao:

1. Anote as contagens atuais dos cartoes de estatisticas
2. Calcule as contagens esperadas pos-importacao
3. Prossiga com a importacao

Verificacao Pos-Importacao

Apos a conclusao da importacao:

1. Atualize a pagina de Ferramentas de Banco de Dados
2. Verifique se as contagens aumentaram na quantidade esperada
3. Verifique se o timestamp "Ultima Importacao" foi atualizado
4. Revise os detalhes do trabalho de importacao para erros

Detalhes Tecnicos

Endpoint da API

URL: GET /api/admin/database/stats

Formato de Resposta:

{
  "totalCustomers": 12450,
  "totalRides": 156789,
  "totalVehicles": 342,
  "lastImport": "2025-12-25T14:23:15.000Z"
}

Cache

• Sem cache implementado: Consultas novas em cada requisicao
• Cabecalhos Cache-Control: no-cache, no-store, must-revalidate definidos
• Modo force-dynamic previne cache estatico do Next.js

Tratamento de Erros

Se as consultas ao banco de dados falharem:

• Retorna status HTTP 500
• Mensagem de erro incluida na resposta
• Cartoes de estatisticas mostram "0" ou "Nunca" como fallbacks

Tabelas do Banco de Dados

Tabela customers

Tabela principal para registros de clientes com mais de 40 campos incluindo:

• Informacoes pessoais
• Detalhes de contato
• Status de verificacao de identidade
• Saldo da carteira
• Estatisticas de historico de viagens

Tabela rides

Tabela principal para registros de viagens com mais de 50 campos incluindo:

• Timestamps da viagem
• Distancia e duracao
• Informacoes de precos
• Referencias de cliente e veiculo
• Informacoes de zona

Tabela vehicles

Tabela principal para registros de veiculos com mais de 45 campos incluindo:

• Identificacao do veiculo
• Vinculacao de dispositivo IoT
• Status da bateria
• Dados de localizacao
• Status e disponibilidade

Tabela stripe_webhook_logs

Log de auditoria para eventos do Stripe e importacoes:

• event_id: Identificador unico do evento
• event_type: Tipo de evento (tipo de importacao para estatisticas)
• processed_at: Timestamp do processamento
• status: Status do processamento

Melhores Praticas

Monitoramento Regular

1. Verificacao diaria: Olhe as contagens durante as operacoes diarias
2. Pre/pos-importacao: Sempre verifique as contagens em torno de operacoes de importacao
3. Investigacao de anomalias: Investigue mudancas inesperadas nas contagens

Documentacao

Mantenha registros de:

• Contagens esperadas apos cada importacao
• Timestamp de importacoes importantes
• Quaisquer discrepancias de contagem e resolucoes

Higiene de Importacao

1. Teste importacoes primeiro: Use arquivos de teste pequenos antes de importacoes grandes
2. Registre a linha de base: Anote as contagens antes de cada importacao
3. Verifique o sucesso: Sempre verifique as contagens pos-importacao

Solucao de Problemas

Estatisticas Nao Carregando

Possiveis Causas:

• Problemas de conexao com o banco de dados
• Endpoint da API inacessivel
• Timeout de rede

Solucoes:

• Atualize a pagina
• Verifique o console do navegador para erros
• Verifique a conectividade do banco de dados

Contagens Nao Correspondem ao Esperado

Possiveis Causas:

• Importacao teve erros (importacao parcial)
• Registros duplicados foram ignorados
• Filtros aplicados durante a importacao

Solucoes:

• Verifique os detalhes de erro do trabalho de importacao
• Revise os logs de importacao
• Verifique a integridade dos dados de origem

Ultima Importacao Mostra "Nunca"

Possivel Causa: Nenhum evento de importacao registrado em stripe_webhook_logs

Dados Desatualizados Apos Importacao

Causa: A pagina precisa ser atualizada apos a conclusao da importacao

Solucao: Atualize manualmente a pagina apos a conclusao das operacoes de importacao

Limitacoes

Limitacoes Atuais

1. Sem dados historicos: Apenas contagens atuais, sem tendencias
2. Sem composicao por status: Apenas contagens totais
3. Sem filtragem por subconta: Mostra todos os registros de todas as subcontas
4. Sem funcionalidade de exportacao: Nao e possivel exportar estatisticas

Nao Incluido

• Filtragem de exclusao reversivel (registros deleted_at sao contados)
• Contagens baseadas em status (ex: viagens ativas vs. concluidas)
• Dados de series temporais
• Composicoes por subconta

Proximos Passos

Agora que voce entende as Estatisticas do Banco de Dados, explore estes topicos relacionados:

• Painel de Analytics - Visualize metricas e graficos operacionais
• Analytics de Identidade - Metricas de verificacao de clientes
• Integracao Stripe - Configuracao de pagamento e importacao