HandyCafe Docs
owner

Niveis de Fidelidade

O sistema de niveis de fidelidade recompensa clientes regulares com descontos automaticos baseados em sua atividade acumulada. Conforme os membros usam a lan house (gastando dinheiro, fazendo login, comprando pacotes ou fazendo pedidos) eles ganham pontos de fidelidade. Quando o total de pontos ultrapassa o limite de um nivel, eles avancam para um nivel superior e recebem um desconto maior nos precos das sessoes.

Estrutura do Nivel

Cada nivel de fidelidade e definido por quatro campos:

Campo Descricao
code Um codigo curto e unico para o nivel (ex.: silver, gold, vip). Usado internamente para identificacao e em respostas da API.
name Um nome de exibicao legivel (ex.: "Membro Prata", "Membro Ouro"). Mostrado no perfil do membro e na tela de bloqueio do cliente.
threshold_points O numero minimo de pontos de fidelidade que um membro deve acumular para se qualificar para este nivel.
discount_bps O desconto aplicado ao preco das sessoes, expresso em pontos base. 100 BPS equivale a 1%. Um valor de 500 significa 5% de desconto.

Os niveis sao ordenados pelo valor de threshold_points. Um membro pertence ao nivel mais alto para o qual atende o limite de pontos.

Descontos em Pontos Base (BPS)

Os descontos sao expressos em pontos base (BPS) ao inves de porcentagens para evitar erros de arredondamento de ponto flutuante em calculos financeiros. Um ponto base equivale a 0,01%, ou um centesimo de porcento.

Valores comuns de desconto:

Valor BPS Porcentagem Exemplo em tarifa de 1000 unidades/hora
250 2,5% Membro paga 975 por hora
500 5% Membro paga 950 por hora
1000 10% Membro paga 900 por hora
1500 15% Membro paga 850 por hora
2000 20% Membro paga 800 por hora

Quando um membro com desconto de nivel inicia uma sessao, o motor de precos reduz a tarifa base por hora pelo discount_bps do nivel antes de calcular os custos dos segmentos.

Eventos de Fidelidade

Membros ganham pontos atraves de eventos de fidelidade. Cada evento registra uma alteracao de pontos e a atividade que a acionou:

Tipo de Evento Descricao Pontos Tipicos
spend O membro pagou por uma sessao (pos-paga ou deducao de carteira). Os pontos sao proporcionais ao valor gasto. Varia conforme o valor gasto
usage O membro usou um PC ou console para uma sessao, independente do pagamento. Os pontos sao baseados na duracao do uso. Varia conforme os minutos usados
visit O membro fez login em um PC cliente. Um bonus fixo por visita, incentivando a frequencia regular. Fixo por visita
topup O membro adicionou fundos a sua carteira. Os pontos refletem o valor da recarga. Varia conforme o valor da recarga
order O membro fez um pedido de produto (comida, bebidas, etc.). Os pontos sao proporcionais ao total do pedido. Varia conforme o total do pedido
adjustment Um ajuste manual de pontos feito por um administrador. Usado para correcoes, promocoes ou recompensas especiais. Qualquer valor (positivo ou negativo)

Cada registro de evento de fidelidade inclui:

  • points_delta: O numero de pontos ganhos (positivo) ou perdidos (negativo) neste evento.
  • amount_minor: O valor monetario associado ao evento (em unidades menores de moeda), se aplicavel.
  • minutes_delta: O numero de minutos associados ao evento, se aplicavel.
  • source_entity / source_entity_id: Uma referencia a sessao, pedido ou transacao que gerou o evento.
  • event_at: O timestamp de quando o evento ocorreu.

Progressao de Nivel

A progressao de nivel funciona da seguinte forma:

  1. Um membro realiza uma atividade (sessao, compra, login, etc.).
  2. O sistema cria um evento de fidelidade com o points_delta correspondente.
  3. O total de pontos do membro e recalculado como a soma de todos os valores points_delta dos seus eventos de fidelidade.
  4. O sistema verifica se o novo total atinge o limite para um nivel superior.
  5. Se o membro se qualifica para um novo nivel, o campo tier e atualizado e o novo desconto entra em vigor na proxima sessao.

A atribuicao de nivel tambem pode ser definida manualmente por um administrador, sobrescrevendo o calculo automatico.

Como Descontos de Nivel se Aplicam ao Preco das Sessoes

Quando o motor de precos calcula o custo de um segmento de sessao para um membro:

  1. O preco base por hora e determinado pela faixa de precos ativa.
  2. Se o membro tem um nivel com valor discount_bps, o preco base e reduzido: preco_descontado = preco_base * (10000 - discount_bps) / 10000.
  3. Adicionalmente, descontos individuais no nivel do membro (member_discount_bps no registro do membro) sao aplicados se presentes.
  4. A tarifa final descontada e usada para calcular o custo do segmento.

Descontos de nivel e descontos individuais do membro podem acumular, concedendo ao membro o beneficio combinado de ambos.

Criando e Gerenciando Niveis

Para criar um novo nivel:

  1. Navegue ate Configuracoes e abra a secao Precos (ou a area dedicada de gerenciamento de niveis).
  2. Clique em Adicionar Nivel.
  3. Informe o codigo (unico, minusculo), nome (rotulo de exibicao), pontos limite e desconto BPS.
  4. Salve o nivel.

Para editar um nivel existente, selecione-o na lista e modifique qualquer campo. Alteracoes no discount_bps de um nivel entram em vigor para todos os membros atribuidos a esse nivel a partir da proxima sessao.

Para excluir um nivel, remova-o da lista. Membros que estavam atribuidos ao nivel excluido voltarao para o proximo nivel inferior para o qual se qualificam com base nos seus pontos.

Exemplo de Configuracao de Niveis

Uma configuracao tipica de tres niveis pode ser assim:

Codigo Nome Pontos Limite Desconto BPS
bronze Bronze 0 0
silver Prata 500 500
gold Ouro 2000 1000
vip VIP 5000 1500

Nesta configuracao, um novo membro comeca no Bronze (sem desconto). Apos acumular 500 pontos de visitas, gastos e pedidos, ele automaticamente sobe para Prata com 5% de desconto. Com 2000 pontos atinge Ouro (10%) e com 5000 pontos alcanca o status VIP (15%).