Documentação

Português

English
Español

Português

English
Español

Appearance

Clube de Recompensas — Níveis ​

Pré-requisitos de acesso

  • Permissão (módulo): viewRewardsProgram (para ler) / manageRewardsLevels (para criar/editar/excluir/reordenar)
  • Licença/Feature: REWARDS_CLUB
  • Contêiner do menu: GERAL → grupo Clube de Recompensas

O que é / quando usar ​

Gerencia os níveis (tiers) do clube de forma totalmente dinâmica: você cria quantos níveis quiser, com nome livre, threshold (limiar de entrada), cor, ícone e lista de benefícios. A ordem é definida por drag-and-drop. Cada nível pode ter uma NFT de tier gerada inline.

Use ao desenhar a escada de fidelidade (ex.: Bronze → Prata → Ouro → Diamante) e ao ajustar limiares/benefícios ao longo do tempo.

Pré-condições ​

  • Permissão: viewRewardsProgram para ler; manageRewardsLevels para editar (permissão dupla: enum CPM + módulo dinâmico no DB).
  • Licença/Feature: REWARDS_CLUB.
  • Dependências de outras telas: o Programa define a métrica e o fiat de referência — isso muda como o threshold é exibido: em pts quando a métrica é POINTS, ou na moeda de referência quando é financeira.

Passo a passo ​

  1. Acesse o menu Clube de Recompensas → Níveis (/rewards-club/levels).
  2. A lista mostra os níveis ordenados; arraste pelas alças para reordenar (persiste automaticamente).
  3. Clique em Novo (ou em um nível para editar) — abre o drawer lateral.
  4. Preencha código do tier, nome, descrição, threshold, cor, ícone e benefícios.
  5. Salve. Para gerar a NFT do nível, use o botão Gerar NFT na linha.

Campos ​

CampoO que éObrigatório?Efeito no sistema/backend
Tier (tier)Código do nível (string livre, ex.: OURO)SimNormalizado para MAIÚSCULAS com _ no lugar de espaços. É a chave do nível (junto do programa). Não pode duplicar ao criar.
Nome (customName → name)Nome exibido do nívelSimRótulo amigável do tier.
Descrição (description)Texto descritivoNãoTexto livre.
Threshold (threshold → minThresholdFiat)Limiar mínimo para entrar no nívelSimComparado com a métrica do programa. Exibido em pts (métrica POINTS) ou na moeda de referência (métrica financeira). Trafega como string BigNumber.
Cor (badgeColor → colorHex)Cor do badge (hex)SimCor visual do nível; há paleta sugerida em ciclo.
Ícone (iconName)Ícone do badge (Material Icons)NãoQuick-picker com sugestões (troféu, medalha, diamante…).
Benefícios (benefits[])Lista de benefícios do nívelNãoEditor por linhas. Linhas no formato chave: valor viram benefícios estruturados (ex.: indicationBonusPercent: 5); as demais viram um label.
Ordem (order → sortOrder)Posição do nívelSim (gerenciada)Definida por drag-and-drop; renumerada em múltiplos de 10 (10, 20, 30…) para facilitar inserções futuras.
NFT do tier (tierNftAssetId)Asset NFT que representa o nívelNãoundefined = ainda não gerado. O botão Gerar NFT cria o asset via tknLib (idempotente).

Ações e modais ​

  • Reordenar (drag-and-drop): persiste a nova ordem via PATCH .../levels/reorder imediatamente (atualização otimista; em erro, recarrega para desfazer).
  • Salvar nível: PUT /v1/rewards-club/admin/levels/:tier. Exige step-up (senha + MFA). Valida tier obrigatório, ausência de duplicidade ao criar, e nome preenchido.
  • Excluir nível: DELETE .../levels/:tier com step-up. Bloqueado se houver usuários no tier — o backend responde ok=false + reason=USERS_IN_TIER + usersInTier, e a UI mostra quantos usuários impedem a exclusão.
  • Gerar NFT: POST .../levels/:tier/generate-nft. Idempotente: se já existir, retorna alreadyExists=true e apenas vincula o assetId.

Regras de negócio / cuidados ​

Atenção

  • Não é possível excluir um nível que tenha usuários posicionados nele — esvazie/migre os usuários antes. Isso protege a integridade do tier engine.
  • A NFT do tier deve ser bloqueada para venda/revenda (block_sell e block_resell) — é um selo, não um ativo negociável. A geração inline já cria o asset adequado.
  • A exibição do threshold depende da métrica do Programa: confira lá antes de definir limiares (pts vs. fiat).

Irreversível

  • Gerar NFT cria um asset on-chain via tknLib. A operação é idempotente (não duplica), mas o asset criado representa o nível permanentemente — trate o tierNftAssetId como definitivo para aquele tier.
  • Valores financeiros: thresholds trafegam como string BigNumber — sem arredondamento.

Exemplos ​

Cenário 1 — Escada financeira em BRL

Programa com métrica DEPOSIT_VOLUME, janela LIFETIME, fiat BRL.

  1. Crie Bronze (threshold 0), Prata (5000), Ouro (20000), Diamante (100000).
  2. Defina cores/ícones distintos; adicione benefícios (ex.: indicationBonusPercent: 5 no Ouro).
  3. Arraste para garantir a ordem Bronze < Prata < Ouro < Diamante.
  4. Gere a NFT de cada nível pelo botão inline.
Cenário 2 — Escada por pontos

Programa com métrica POINTS.

  1. Os thresholds passam a ser exibidos em pts. Defina, ex.: Bronze 0, Prata 1000, Ouro 5000.
  2. Garanta missões pontuadoras em Missões para que os usuários acumulem pontos.
Cenário 3 — Tentativa de exclusão bloqueada

Ao excluir "Prata" com 37 usuários no tier:

  1. A confirmação é aceita, mas o backend retorna USERS_IN_TIER com usersInTier=37.
  2. A UI informa que 37 usuários impedem a exclusão.
  3. Ajuste thresholds/recompute para migrar os usuários e tente novamente.

Telas relacionadas ​