Reembolsos Automaticos

O sistema de reembolso automatico detecta viagens que provavelmente falharam ou apresentaram mau funcionamento e reembolsa automaticamente os clientes em suas carteiras. Isso ajuda a manter a satisfacao do cliente quando veiculos apresentam problemas, nao destravam corretamente ou ocorrem outros problemas que resultam em viagens muito curtas e mal-sucedidas.

Como Funciona

Fluxo de Reembolso Automatico

Quando uma viagem termina, o sistema avalia se ela se qualifica para reembolso automatico:

Por Que o Atraso?

O sistema aguarda um numero configuravel de minutos antes de processar o reembolso. Este atraso permite:

1. Dados de telemetria atrasados atualizarem as metricas da viagem
2. Sincronizacao de dados IoT completar com distancia/duracao final
3. Processamento backend finalizar calculos da viagem

Isso evita reembolsos prematuros baseados em dados incompletos.

Criterios de Elegibilidade

Uma viagem se qualifica para reembolso automatico se TODOS os seguintes forem verdadeiros:

O Que e Verificado

A avaliacao de elegibilidade usa os seguintes dados da viagem:

• Duracao em segundos
• Distancia em metros
• Custo total
• Valor cobrado
• Status do pagamento

Configuracao

Acesso as Configuracoes

Configure reembolsos automaticos no painel de administracao:

1. Navegue ate Configuracoes
2. Clique na aba Viagens
3. Encontre a secao Reembolsos Automaticos

Opcoes de Configuracao

Valores Recomendados por Caso de Uso

Conservador (Menos Reembolsos)

Use estas configuracoes se quiser minimizar reembolsos automaticos e preferir revisao manual:

Padrao (Equilibrado)

As configuracoes padrao equilibram satisfacao do cliente com supervisao operacional:

Generoso (Mais Reembolsos)

Use estas configuracoes para maxima satisfacao do cliente:

Status dos Jobs

Jobs de reembolso automatico passam por estes status:

Detalhes do Cron Job

O cron de reembolso automatico executa a cada 5 minutos via Vercel Cron.

Comportamento de Processamento

Cada execucao do cron:

1. Processa ate 25 jobs por execucao
2. Processa apenas jobs onde scheduled_for ≤ NOW()
3. Usa bloqueio otimista para evitar processamento duplicado
4. Limpa jobs expirados com mais de 7 dias

Formato de Resposta

O endpoint cron retorna estatisticas de processamento:

{
  "success": true,
  "timestamp": "2025-01-19T12:00:00Z",
  "duration_ms": 1234,
  "processed": 15,
  "succeeded": 12,
  "cancelled": 2,
  "failed": 1,
  "total_refunded_usd": 24.50
}

Painel de Administracao

Acesse o painel de reembolsos automaticos em Painel > Reembolsos > Automaticos.

Recursos do Painel

Cartoes de Estatisticas

• Jobs Pendentes - Numero de jobs aguardando processamento
• Sucesso (24h) - Reembolsos bem-sucedidos nas ultimas 24 horas
• Total Reembolsado (24h) - Valor em dinheiro reembolsado
• Taxa de Sucesso - Porcentagem de jobs bem-sucedidos

Tabela de Jobs Pendentes

• Link da viagem
• Link do cliente
• Metricas da viagem (duracao, distancia)
• Valor do reembolso
• Horario agendado de processamento
• Acao de cancelar

Alerta de Jobs com Falha

• Exibido de forma destacada quando jobs precisam de atencao
• Acoes de repetir e cancelar

Tabela de Reembolsos Recentes

• Reembolsos processados nas ultimas 24 horas
• Valor, cliente, detalhes da viagem
• ID do job para solucao de problemas

Acoes Disponiveis

Detalhes do Processo de Reembolso

O Que Acontece Durante o Reembolso

1. Bloqueio do Job Adquirido - Status definido como processing
2. Configuracoes Validadas - Verificar se reembolso automatico ainda esta ativado
3. Viagem Recuperada - Obter metricas mais recentes da viagem
4. Elegibilidade Reavaliada - Confirmar que ainda esta dentro dos limites
5. Valor Reembolsavel Calculado - Valor realmente pago menos ja reembolsado
6. Carteira Creditada - Saldo da carteira do cliente aumentado
7. Transacao de Carteira Criada - Trilha de auditoria registrada
8. Viagem Atualizada - Marcada como reembolsada se totalmente reembolsada
9. Notificacao Enviada - Notificacao push para o cliente
10. Job Concluido - Status definido como succeeded

Notificacao do Cliente

Quando um reembolso automatico e emitido, clientes recebem:

Notificacao Push:

• Titulo: "Reembolso de Viagem Emitido"
• Texto: "Uma viagem recente foi automaticamente reembolsada para sua carteira."

Transacao de Carteira:

• Tipo: Credito
• Descricao: "Reembolso automatico de viagem"
• Referencia: UUID da viagem

Motivos de Cancelamento

Jobs podem ser cancelados por varios motivos:

Reembolsos Manuais

Alem dos reembolsos automaticos, operadores podem emitir reembolsos manuais atraves do painel.

Tipos de Reembolso

Modos de Reembolso

Processando um Reembolso Manual

Requisitos de Permissao

Reembolsos requerem a permissao ride:refund. As seguintes funcoes podem processar reembolsos:

• super_admin
• global_admin
• admin
• general_manager
• franchisee_manager
• fleet_manager
• customer_support

Nota: Analistas e Tecnicos de Servico nao podem processar reembolsos.

Monitoramento

Visualizar Jobs Pendentes

SELECT
  id,
  ride_uuid,
  customer_uuid,
  status,
  scheduled_for,
  attempts,
  created_at
FROM ride_auto_refund_jobs
WHERE status = 'pending'
ORDER BY scheduled_for ASC;

Visualizar Reembolsos Automaticos Recentes

SELECT
  r.id,
  r.ride_uuid,
  r.customer_uuid,
  r.amount,
  r.processed_at,
  r.metadata->>'job_id' as job_id
FROM ride_refunds r
WHERE r.metadata->>'automatic_refund' = 'true'
  AND r.processed_at > NOW() - INTERVAL '24 hours'
ORDER BY r.processed_at DESC;

Verificar Jobs com Falha

SELECT
  id,
  ride_uuid,
  customer_uuid,
  attempts,
  last_error,
  created_at
FROM ride_auto_refund_jobs
WHERE status = 'failed'
ORDER BY updated_at DESC
LIMIT 20;

Solucao de Problemas

Jobs Nao Estao Sendo Criados

Verificacao 1: Reembolso automatico esta ativado?

• Navegue ate Configuracoes > Viagens > Reembolsos Automaticos
• Verifique se o interruptor esta ligado

Verificacao 2: Metricas da viagem estao dentro dos limites?

• Verifique duracao da viagem (deve ser ≤ max_ride_duration_minutes)
• Verifique distancia da viagem (deve ser ≤ max_total_distance_m)

Verificacao 3: Viagem tem um cliente?

• Verifique se a viagem esta associada a um cliente valido

Jobs Travados em Pendente

Verificacao 1: O cron esta executando?

• Verifique se Vercel Cron esta configurado
• Verifique os logs de execucao do cron no painel Vercel

Verificacao 2: Jobs estao agendados para o futuro?

• Jobs so sao processados quando scheduled_for ≤ NOW()

Verificacao 3: Verifique logs de funcao Vercel para erros

Jobs Falhando

Erros Comuns e Solucoes:

Otimizacao de Performance

Frotas de Alto Volume

Para frotas com muitas viagens, considere:

1. Aumentar frequencia do cron - Executar a cada 2-3 minutos em vez de 5
2. Aumentar tamanho do lote - Processar 50-100 jobs por execucao
3. Monitorar acumulo de fila - Configurar alertas para contagem de jobs pendentes

Otimizacao de Banco de Dados

Garanta que estes indices existam para performance otima:

-- Busca de jobs pendentes
CREATE INDEX CONCURRENTLY IF NOT EXISTS
  idx_ride_auto_refund_jobs_pending_scheduled
  ON ride_auto_refund_jobs (scheduled_for)
  WHERE status = 'pending';

-- Busca de carteira de cliente
CREATE INDEX CONCURRENTLY IF NOT EXISTS
  idx_customers_wallet
  ON customers (id, wallet_balance);

Alertas Recomendados

Configure alertas para:

1. Alta taxa de falha - Alertar se jobs com falha > 10% dos processados
2. Acumulo de fila - Alertar se jobs pendentes > 100
3. Atraso de processamento - Alertar se jobs estao > 30 minutos atrasados
4. Falhas de execucao - Alertar se endpoint cron retorna 500

Proximos Passos

• Configuracao Stripe - Configurar integracao Stripe
• Metodos de Pagamento - Gerenciar cartoes de clientes
• Cobrancas de Danos - Cobrar clientes por danos