Desbloqueios Gratuitos (Beneficio de Nivel)

Desbloqueios gratuitos sao um beneficio de nivel de fidelidade que isenta a taxa de desbloqueio para um numero especificado de viagens a cada mes. Clientes de niveis mais altos recebem mais desbloqueios gratuitos, criando uma razao convincente para permanecer engajado com sua frota.

Visao Geral

Cada nivel de fidelidade pode incluir um numero configuravel de desbloqueios gratuitos por mes. Quando clientes iniciam uma viagem, o sistema automaticamente verifica seus beneficios de nivel e aplica um desbloqueio gratuito se disponivel, economizando a taxa de desbloqueio.

Principais Recursos

• Configuracao por nivel - Defina quantidades diferentes para cada nivel de fidelidade
• Reset mensal - Contador reinicia no inicio de cada mes
• Aplicacao automatica - Nenhuma acao necessaria dos clientes
• Rastreamento em tempo real - Clientes veem desbloqueios gratuitos restantes no app
• Rastreamento por viagem - Cada viagem registra se desbloqueio gratuito foi usado

Como Funciona

Cliente toca em "Desbloquear"
         ↓
Sistema verifica nivel de fidelidade
         ↓
Tem desbloqueios gratuitos restantes?
    ├── Sim → Pula taxa de desbloqueio
    │         Incrementa contador de uso
    │         Marca viagem como "usou desbloqueio gratuito"
    │         Cliente ve "Taxa de desbloqueio R$0"
    └── Nao  → Cobra taxa de desbloqueio normalmente
             Cliente paga da carteira

Configurando Desbloqueios Gratuitos

Configurando Niveis

Exemplo de Estrutura de Niveis

Reset Mensal

Contagens de desbloqueios gratuitos reiniciam automaticamente no inicio de cada mes calendario.

Logica de Reset

Novo Mes Comeca (ex: 1o de fevereiro)
         ↓
Cliente inicia primeira viagem do mes
         ↓
Sistema verifica: Data de reset e antes deste mes?
    ├── Sim → Reinicia contador para 0
    │         Define data de reset para 1o de fev
    └── Nao  → Usa contador existente

Notas Importantes

• Reset acontece na primeira viagem do novo mes, nao a meia-noite
• Desbloqueios gratuitos nao utilizados NAO acumulam
• Clientes sao notificados de sua nova cota mensal no app

Experiencia do Cliente

Antes de Iniciar Viagem

Clientes veem seu status de fidelidade:

• Nome e distintivo do nivel atual
• Desbloqueios gratuitos usados este mes
• Desbloqueios gratuitos restantes

Durante o Desbloqueio

Quando um desbloqueio gratuito esta disponivel:

1. Cliente toca em "Desbloquear" no veiculo
2. Sistema aplica desbloqueio gratuito automaticamente
3. Mensagem toast: "Desbloqueio gratuito aplicado! X restantes este mes"
4. Taxa de desbloqueio aparece como R$0 no recibo

Na Secao de Fidelidade

O aplicativo movel exibe:

• free_unlocks_used - Quantos usados este mes
• free_unlocks_remaining - Quantos restam para usar
• Barra de progresso visual mostrando uso

Campos de Configuracao de Nivel

Tabela loyalty_tiers

Tabela customer_loyalty

Detalhes de Implementacao

Verificar e Aplicar Desbloqueio Gratuito

Quando uma viagem inicia, o sistema:

1. Obter info do nivel - Buscar nivel atual do cliente e beneficios
2. Calcular restantes - desbloqueiosRestantes = tier.free_unlocks_per_month - free_unlocks_used_this_month
3. Verificar disponibilidade - Se desbloqueiosRestantes > 0
4. Aplicar beneficio - Incrementar contador, pular taxa de desbloqueio
5. Registrar na viagem - Definir used_free_unlock = true

// Logica simplificada do fluxo de desbloqueio
if (tierInfo.freeUnlocksRemaining > 0) {
  const freeUnlockUsed = await applyFreeUnlock(admin, customer.id)

  if (freeUnlockUsed) {
    // Pular cobranca de taxa de desbloqueio
    // Atualizar registro da viagem
    await admin.from('rides').update({
      used_free_unlock: true
    }).eq('id', ride.id)
  }
}

Funcao applyFreeUnlock

async function applyFreeUnlock(admin, customerId): Promise<boolean> {
  // 1. Obter registro de fidelidade do cliente
  // 2. Obter cota de desbloqueios gratuitos do nivel
  // 3. Verificar se reset mensal e necessario
  // 4. Verificar desbloqueios gratuitos disponiveis
  // 5. Incrementar contador
  // 6. Retornar sucesso
}

Referencia da API

Obter Status de Fidelidade (Mobile)

GET /api/mobile/loyalty

Resposta inclui:

{
  "tier_progress": {
    "free_unlocks_used": 3,
    "free_unlocks_remaining": 2
  },
  "tier": {
    "free_unlocks_per_month": 5
  }
}

Verificacao de Beneficios de Nivel

import { getTierBenefits } from '@/lib/billing/loyalty'

const benefits = await getTierBenefits(admin, customerId, accountId)
// Retorna: { canUseFreeUnlock: boolean, ... }

Melhores Praticas

Definindo Quantidades

1. Comece conservador - Inicie com contagens modestas de desbloqueios gratuitos
2. Crie gaps significativos - Cada nivel deve parecer uma melhoria
3. Considere a economia - Leve em conta o valor medio da taxa de desbloqueio
4. Equilibre com outros beneficios - Nao torne um nivel muito poderoso

Exemplos de Calculos

Taxa media de desbloqueio: R$1,50
Nivel Ouro: 5 desbloqueios gratuitos = R$7,50 de valor/mes
Nivel Platina: 10 desbloqueios gratuitos = R$15,00 de valor/mes

Comunicacao

1. Destaque o beneficio - Mostre desbloqueios gratuitos de forma proeminente nas descricoes de nivel
2. Mostre progresso - Exiba uso claramente no app
3. Notifique proximo da expiracao - Alerte clientes quando o mes esta terminando
4. Celebre economia - Mostre economia acumulada dos desbloqueios gratuitos

Solucao de Problemas

Desbloqueio Gratuito Nao Aplicado

1. Verifique configuracao do nivel - Confirme que free_unlocks_per_month > 0
2. Verifique contagem de uso - Pode ter usado todos os desbloqueios disponiveis
3. Verifique atribuicao de nivel - Cliente pode ainda nao se qualificar para o nivel
4. Verifique data de reset - Garanta que reset mensal ocorreu corretamente

Contagem Errada Exibida

1. Verifique banco de dados - Confira customer_loyalty.free_unlocks_used_this_month
2. Verifique logica de reset - free_unlocks_reset_at deve ser do mes atual
3. Revise viagens recentes - Procure por viagens com used_free_unlock = true

Problemas de Reset Mensal

1. Verifique gatilho de reset - Acontece na primeira viagem, nao automaticamente
2. Verifique comparacao de datas - Reset at deve ser comparado com inicio do mes
3. Reset manual - Funcao de banco de dados reset_monthly_free_unlocks pode ajudar

Combinando com Outros Beneficios

Desbloqueios gratuitos funcionam junto com outros beneficios de nivel:

Quando um desbloqueio gratuito e usado, unlock_discount_pct e ignorado para aquela viagem ja que a taxa ja e R$0.