Como Funciona a Precificacao

Este guia completo explica como todo o sistema de precificacao calcula as cobranças de viagem, do inicio ao fim. Entender esse fluxo e essencial para operadores que desejam configurar precos de forma eficaz e resolver problemas de cobrança.

---

Lista de Verificacao de Configuracao

Antes que seu sistema de precificacao funcione corretamente, certifique-se de ter concluido estas etapas:

1. Verifique se cada modelo de veiculo existe para a subconta (localizacao) ativa
2. Defina uma regra de preco base por modelo com valores de desbloqueio, pausa, minimo e limite diario
3. Crie planos de assinatura que os usuarios podem comprar pelo aplicativo movel ou painel
4. Publique pacotes de viagem que concedem desbloqueios, minutos ou distancia pre-pagos
5. Configure regras de precos dinamicos para ajustes de horario, clima, demanda ou modelo especifico
6. Emita codigos promocionais e verifique seu escopo (global, subconta, tipo de veiculo) e limites
7. Teste sua configuracao usando os testes de API de precificacao para validar tudo de ponta a ponta

---

Ordem de Operacoes de Cobranca

Quando uma viagem e concluida, o sistema passa por estas etapas antes de cobrar o cliente:

┌─────────────────────────────────────────────────────────────────┐
│                     VIAGEM CONCLUIDA                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ ETAPA 1: Calcular Cobranças Base                                │
│   • Aplicar taxa de desbloqueio, tarifa de tempo, pausa, dist.  │
│   • Aplicar limite diario do veiculo                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ ETAPA 2: Aplicar Beneficios de Nivel                            │
│   • Verificar nivel de fidelidade do cliente                    │
│   • Aplicar porcentagem de desconto no desbloqueio              │
│   • Aplicar porcentagem de desconto por minuto                  │
│   • Usar desbloqueio gratis se elegivel e solicitado            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ ETAPA 3: Consumir Cotas de Assinatura                           │
│   • Encontrar compras de assinatura ativas                      │
│   • Deduzir desbloqueios, minutos, distancia da assinatura      │
│   • Rastrear uso para limites de assinatura                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ ETAPA 4: Consumir Pacotes de Viagem                             │
│   • Encontrar compras de pacote ativas (mais antigas primeiro)  │
│   • Deduzir desbloqueios, minutos, distancia restantes          │
│   • Registrar eventos de uso detalhados                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ ETAPA 5: Aplicar Precos Dinamicos                               │
│   • Avaliar regras de horario/clima/demanda                     │
│   • Aplicar multiplicadores e ajustes fixos                     │
│   • Processar regras por ordem de prioridade                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ ETAPA 6: Aplicar Codigo Promocional                             │
│   • Validar janelas de tempo, escopos, limites de uso           │
│   • Verificar requisitos de gasto minimo                        │
│   • Aplicar desconto percentual ou fixo                         │
│   • Aplicar limite maximo de desconto                           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ ETAPA 7: Ajustes Finais                                         │
│   • Reverificar limite diario contra o total final              │
│   • Aplicar preco minimo (se assinatura/pacote nao usado)       │
│   • Subtrair quaisquer cobranças parciais ja coletadas          │
│   • Calcular valor final devido                                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     COBRAR CLIENTE                              │
└─────────────────────────────────────────────────────────────────┘

---

Detalhamento das Etapas

Etapa 1: Calculo de Preco Base

A primeira etapa calcula as cobranças brutas com base na regra de preco do veiculo:

Entradas:

• Duracao da viagem (minutos ativos)
• Duracao da pausa (minutos pausados)
• Distancia percorrida (quilometros)
• Configuracao de preco do veiculo

Calculo:

Subtotal Base = Taxa de Desbloqueio
              + (Minutos Ativos × Tarifa por Minuto)
              + (Minutos de Pausa × Taxa de Pausa)
              + (Distancia KM × Tarifa por KM)

Aplicacao do Limite Diario: Se o subtotal exceder o limite diario, as cobranças sao reduzidas em ordem:

1. Taxas de tempo reduzidas primeiro
2. Taxas de pausa reduzidas segundo
3. Taxas de distancia reduzidas terceiro
4. Taxa de desbloqueio reduzida por ultimo (apenas se necessario)

Etapa 2: Beneficios de Nivel de Fidelidade

Para clientes com status de nivel de fidelidade, descontos significativos podem ser aplicados:

Tipos de Beneficios de Nivel:

Ordem de Aplicacao:

1. Verificar desbloqueio gratis - Se o cliente solicitar e tiver desbloqueios gratis restantes
2. Aplicar desconto no desbloqueio - Porcentagem de desconto (apenas se desbloqueio gratis nao usado)
3. Aplicar desconto por minuto - Porcentagem de desconto em todas as taxas de tempo

Calculo:

Se Desbloqueio Gratis Usado:
  Desconto Desbloqueio = Taxa de Desbloqueio Total (100% coberto)
Senao:
  Desconto Desbloqueio = Taxa Desbloqueio × (unlock_discount_pct / 100)

Desconto Tempo = Taxa Tempo × (per_minute_discount_pct / 100)

Desconto Total Nivel = Desconto Desbloqueio + Desconto Tempo
Apos Nivel = Subtotal Base - Desconto Total Nivel

Exemplo (Nivel Premium):

Cobranças Base:
  Desbloqueio:  R$ 7,50
  Tempo:        R$ 29,25
  Subtotal:     R$ 36,75

Beneficios Nivel Premium (20% desbloqueio, 15% tempo):
  Desconto Desbloqueio: R$ 7,50 × 0,20 = R$ 1,50
  Desconto Tempo:       R$ 29,25 × 0,15 = R$ 4,39
  Desconto Total:       R$ 5,89

Apos Nivel: R$ 36,75 - R$ 5,89 = R$ 30,86

Exemplo de Desbloqueio Gratis:

Cobranças Base:
  Desbloqueio:  R$ 7,50
  Tempo:        R$ 29,25
  Subtotal:     R$ 36,75

Nivel Premium (Desbloqueio Gratis Usado):
  Desconto Desbloqueio: R$ 7,50 (valor total)
  Desconto Tempo:       R$ 29,25 × 0,15 = R$ 4,39
  Desconto Total:       R$ 11,89

Apos Nivel: R$ 36,75 - R$ 11,89 = R$ 24,86

Descontos de nivel sao rastreados separadamente para relatorios e aparecem nos recibos dos clientes.

Etapa 3: Consumo de Assinatura

Assinaturas ativas sao consumidas antes dos pacotes de viagem:

Cotas de Assinatura:

• Desbloqueios incluidos (por dia ou total)
• Minutos de viagem (por dia ou total)
• Minutos de pausa (por dia ou total)
• Distancia de viagem (por dia ou total)

Tipos de Limite:

Correspondencia:

• Assinaturas especificas de subconta correspondem primeiro
• Assinaturas globais usadas como fallback
• Assinatura mais antiga consumida primeiro

Etapa 4: Consumo de Pacote de Viagem

Cobranças restantes apos assinaturas sao cobertas por pacotes de viagem:

Conteudo do Pacote:

• Desbloqueios pre-pagos
• Minutos pre-pagos
• Minutos de pausa pre-pagos
• Distancia pre-paga

Logica de Consumo:

1. Encontrar todas as compras de pacote ativas para o cliente
2. Filtrar por subconta (se pacote for especifico de localizacao)
3. Ordenar por data de compra (mais antigo primeiro)
4. Consumir cotas ate esgotar ou cobranças cobertas

Rastreamento de Uso: Cada consumo e registrado com:

• UUID da viagem
• Minutos usados
• Distancia usada
• Desbloqueio usado (booleano)
• Desconto aplicado (centavos)
• Timestamp

Etapa 5: Ajustes de Precos Dinamicos

Apos pacotes, regras de precos dinamicos sao avaliadas:

Avaliacao de Regras:

1. Filtrar regras ativas para o modelo do veiculo
2. Verificar janelas de tempo (para regras baseadas em tempo)
3. Verificar condicoes climaticas (para regras baseadas em clima)
4. Verificar limites de demanda (para regras baseadas em demanda)
5. Ordenar por prioridade (maior primeiro)
6. Aplicar cada regra correspondente sequencialmente

Aplicacao de Ajuste:

Para cada regra aplicavel:
  Se percentual: Subtotal = Subtotal × (1 + percent/100)
  Se multiplicador: Subtotal = Subtotal × multiplicador
  Entao: Subtotal = Subtotal + ajuste_fixo

Etapa 6: Aplicacao de Codigo Promocional

Se um codigo promocional foi fornecido:

Verificacoes de Validacao:

1. Codigo existe e esta ativo
2. Hora atual dentro de valid_from e valid_until
3. Usos globais nao excederam max_uses
4. Usos do cliente nao excederam max_uses_per_customer
5. Subconta corresponde (se com escopo)
6. Tipo de veiculo corresponde (se com escopo)
7. Subtotal atende ao valor minimo da viagem

Calculo do Desconto:

Se percentual:
  Desconto = Subtotal × (percent / 100)
Se fixo:
  Desconto = Valor Fixo

Se max_discount_cents definido:
  Desconto = MIN(Desconto, max_discount_cents)

Desconto Final = MIN(Desconto, Subtotal)  // Nao pode exceder subtotal

Etapa 7: Ajustes Finais

A etapa final aplica limites protetivos:

Reverificacao do Limite Diario: Apos todos os descontos e sobretaxas, o limite diario e verificado:

Se Final > Limite Diario:
  Final = Limite Diario

Preco Minimo: Aplicado apenas quando nenhum desconto de assinatura ou pacote foi usado:

Se Final < Minimo E nenhum_beneficio_usado:
  Final = Minimo

Subtracao de Valor Ja Cobrado: Para viagens com cobranças parciais (ex: valores de retencao):

Valor Devido = Final - Ja Cobrado

---

O Fluxo Completo de Calculo

Aqui esta um exemplo passo a passo com numeros reais:

Cenario: E-Bike Premium, viagem de 25 minutos durante pico

Dados:

• Veiculo: E-Bike Premium
• Preco Base: R$ 7,50 desbloqueio, R$ 2,45/min, R$ 150 limite diario
• Assinatura: Nenhuma
• Pacote: "Pacote 10 minutos" com 3 desbloqueios e 20 minutos restantes
• Regra Dinamica: "Pico Fim de Semana" +25% com R$ 5,00 fixo
• Codigo Promo: "ANDEJA" 20% de desconto, max R$ 10,00

Etapa 1: Cobranças Base

Desbloqueio:    R$ 7,50
Tempo:          25 × R$ 2,45 = R$ 61,25
Subtotal:       R$ 68,75

Etapa 2: Beneficios de Nivel

Sem beneficios de nivel
Subtotal:       R$ 68,75

Etapa 3: Assinatura

Sem assinatura ativa
Subtotal:       R$ 68,75

Etapa 4: Consumo de Pacote

Pacote cobre: 1 desbloqueio (R$ 7,50) + 20 minutos (R$ 49,00)
Desconto do pacote: R$ 56,50
Restante: 5 minutos × R$ 2,45 = R$ 12,25
Subtotal:       R$ 12,25

Etapa 5: Precos Dinamicos

Pico Fim de Semana (+25%): R$ 12,25 × 1,25 = R$ 15,31
Sobretaxa fixa: R$ 15,31 + R$ 5,00 = R$ 20,31
Subtotal:       R$ 20,31

Etapa 6: Codigo Promocional

ANDEJA 20%: R$ 20,31 × 0,20 = R$ 4,06
Limitado a R$ 10,00: R$ 4,06 (abaixo do limite)
Subtotal:       R$ 20,31 - R$ 4,06 = R$ 16,25

Etapa 7: Final

Verificacao limite diario: R$ 16,25 < R$ 150 ✓
Verificacao minimo: Pulado (pacote usado)
Valor Final Devido: R$ 16,25

---

Cenarios de Configuracao

Cenario 1: Apenas Preco Base

Configuracao:

• Veiculo: Patinete Padrao
• Desbloqueio: R$ 5,00
• Por minuto: R$ 1,95
• Sem pacotes, assinaturas ou promos

Viagem de 15 minutos:

Desbloqueio:    R$ 5,00
Tempo:          15 × R$ 1,95 = R$ 29,25
Total:          R$ 34,25

Cenario 2: Cobertura Total por Pacote

Configuracao:

• Pacote: "Impulso 15 Minutos" - 1 desbloqueio, 20 minutos

Viagem de 18 minutos:

Base:           R$ 5,00 + (18 × R$ 1,95) = R$ 40,10
Pacote:         Cobre desbloqueio (R$ 5,00) + 18 min (R$ 35,10)
Desconto:       R$ 40,10
Valor Devido:   R$ 0,00

Todo uso registrado, 2 minutos restam no pacote.

Cenario 3: Pico + Promo Combinados

Configuracao:

• Patinete Premium: R$ 7,50 desbloqueio, R$ 2,45/min
• Dinamico: "Pico Fim de Semana" +25% + R$ 5,00 fixo
• Promo: "ANDEJA" 20% de desconto, limitado a R$ 10,00

Viagem de 25 minutos:

Base:           R$ 7,50 + (25 × R$ 2,45) = R$ 68,75
Pico 25%:       R$ 68,75 × 1,25 = R$ 85,94
Fixo:           R$ 85,94 + R$ 5,00 = R$ 90,94
Promo 20%:      R$ 90,94 × 0,20 = R$ 18,19 → Limitado a R$ 10,00
Final:          R$ 90,94 - R$ 10,00 = R$ 80,94

---

Perguntas Frequentes

Pacotes e codigos promocionais podem ser combinados?

Sim. Pacotes sao consumidos primeiro, reduzindo o subtotal. Entao codigos promocionais sao aplicados ao saldo restante. Isso significa que os clientes obtem o melhor desconto possivel.

O que acontece se eu tiver multiplos pacotes?

O sistema usa o pacote mais antigo primeiro (FIFO - Primeiro a Entrar, Primeiro a Sair). Uma vez que um pacote e esgotado, o proximo e usado.

Posso usar tanto preco por minuto quanto por distancia?

Nao, voce deve escolher um ou outro por modelo de veiculo. O sistema usa o campo que tiver um valor maior que zero.

Como testo precos com seguranca?

1. Crie uma subconta de teste com regras de preco de teste
2. Use os testes de API de precificacao: npm run test:pricing
3. Revise o detalhamento detalhado na saida do teste
4. Nunca teste em dados de producao

Por que o preco minimo nao foi aplicado?

O preco minimo e pulado quando descontos de assinatura ou pacote sao usados. Clientes com beneficios pagos nao devem ser penalizados com cobranças minimas.

Como o limite diario interage com pacotes?

O limite diario se aplica as cobranças base antes dos descontos de pacote. Se um usuario tem um pacote, o calculo do limite ainda considera as cobranças base totais, mas o usuario so paga o valor pos-pacote.

---

Referencia Tecnica

Funcoes Principais

Tabelas do Banco de Dados

Estrutura do Resultado

A funcao buildRidePricing retorna:

{
  base: {
    unlockFeeCents: number
    timeFeeCents: number
    pauseFeeCents: number
    distanceFeeCents: number
    subtotalCents: number
    dailyCapApplied: boolean
  }
  tier: {
    tierName: string | null
    unlockDiscountCents: number
    timeDiscountCents: number
    freeUnlockUsed: boolean
    totalDiscountCents: number
  } | null
  subscription: {
    discountCents: number
    purchaseId: string
    usageEvent: object
  } | null
  package: {
    discountCents: number
    purchaseId: string
    usageEvent: object
  } | null
  dynamic: {
    subtotalBefore: number
    finalSubtotal: number
    multiplier: number
    adjustmentCents: number
    appliedRules: array
  }
  promo: {
    discountCents: number
    code: string
    promoId: string
  } | null
  totals: {
    baseSubtotalCents: number
    tierDiscountCents: number
    subscriptionDiscountCents: number
    packageDiscountCents: number
    dynamicAdjustmentCents: number
    promoDiscountCents: number
    finalCents: number
    amountDueCents: number
  }
}

---