Documentação

Español

Português
English

Español

Português
English

Appearance

Club de Recompensas — Niveles ​

Requisitos de acceso

  • Permiso (módulo): viewRewardsProgram (para leer) / manageRewardsLevels (para crear/editar/eliminar/reordenar)
  • Licencia/Feature: REWARDS_CLUB
  • Contenedor del menú: GENERAL → grupo Club de Recompensas

Qué es / cuándo usar ​

Gestiona los niveles (tiers) del club de forma totalmente dinámica: puedes crear tantos niveles como quieras, con nombre libre, threshold (umbral de entrada), color, ícono y lista de beneficios. El orden se define por drag-and-drop. Cada nivel puede tener un NFT de nivel generado inline.

Úsalo al diseñar la escalera de fidelidad (ej.: Bronce → Plata → Oro → Diamante) y al ajustar umbrales/beneficios a lo largo del tiempo.

Pre-condiciones ​

  • Permiso: viewRewardsProgram para leer; manageRewardsLevels para editar (permiso doble: enum CPM + módulo dinámico en la DB).
  • Licencia/Feature: REWARDS_CLUB.
  • Dependencias de otras pantallas: el Programa define la métrica y el fiat de referencia — esto cambia cómo se muestra el threshold: en pts cuando la métrica es POINTS, o en la moneda de referencia cuando es financiera.

Paso a paso ​

  1. Accede al menú Club de Recompensas → Niveles (/rewards-club/levels).
  2. La lista muestra los niveles ordenados; arrastra por las asas para reordenar (persiste automáticamente).
  3. Haz clic en Nuevo (o en un nivel para editar) — abre el drawer lateral.
  4. Completa el código del nivel, nombre, descripción, threshold, color, ícono y beneficios.
  5. Guarda. Para generar el NFT del nivel, usa el botón Generar NFT en la fila.

Campos ​

CampoQué es¿Obligatorio?Efecto en el sistema/backend
Nivel (tier)Código del nivel (string libre, ej.: ORO)SíNormalizado a MAYÚSCULAS con _ en lugar de espacios. Es la clave del nivel (junto al programa). No puede duplicarse al crear.
Nombre (customName → name)Nombre mostrado del nivelSíEtiqueta amigable del nivel.
Descripción (description)Texto descriptivoNoTexto libre.
Threshold (threshold → minThresholdFiat)Umbral mínimo para entrar en el nivelSíComparado con la métrica del programa. Mostrado en pts (métrica POINTS) o en la moneda de referencia (métrica financiera). Se transmite como string BigNumber.
Color (badgeColor → colorHex)Color del badge (hex)SíColor visual del nivel; hay paleta sugerida en ciclo.
Ícono (iconName)Ícono del badge (Material Icons)NoQuick-picker con sugerencias (trofeo, medalla, diamante…).
Beneficios (benefits[])Lista de beneficios del nivelNoEditor por líneas. Las líneas en formato clave: valor se convierten en beneficios estructurados (ej.: indicationBonusPercent: 5); las demás se convierten en un label.
Orden (order → sortOrder)Posición del nivelSí (gestionado)Definido por drag-and-drop; renumerado en múltiplos de 10 (10, 20, 30…) para facilitar inserciones futuras.
NFT del nivel (tierNftAssetId)Activo NFT que representa el nivelNoundefined = aún no generado. El botón Generar NFT crea el activo via tknLib (idempotente).

Acciones y modales ​

  • Reordenar (drag-and-drop): persiste el nuevo orden via PATCH .../levels/reorder inmediatamente (actualización optimista; en error, recarga para deshacer).
  • Guardar nivel: PUT /v1/rewards-club/admin/levels/:tier. Requiere step-up (contraseña + MFA). Valida nivel obligatorio, ausencia de duplicidad al crear, y nombre completado.
  • Eliminar nivel: DELETE .../levels/:tier con step-up. Bloqueado si hay usuarios en el nivel — el backend responde ok=false + reason=USERS_IN_TIER + usersInTier, y la UI muestra cuántos usuarios impiden la eliminación.
  • Generar NFT: POST .../levels/:tier/generate-nft. Idempotente: si ya existe, retorna alreadyExists=true y solo vincula el assetId.

Reglas de negocio / precauciones ​

Atención

  • No es posible eliminar un nivel que tenga usuarios posicionados en él — vacía/migra los usuarios primero. Esto protege la integridad del tier engine.
  • El NFT de nivel debe estar bloqueado para venta/reventa (block_sell y block_resell) — es un sello, no un activo negociable. La generación inline ya crea el activo adecuado.
  • La visualización del threshold depende de la métrica del Programa: verifica allí antes de definir umbrales (pts vs. fiat).

Irreversible

  • Generar NFT crea un activo on-chain via tknLib. La operación es idempotente (no duplica), pero el activo creado representa el nivel permanentemente — trata el tierNftAssetId como definitivo para ese nivel.
  • Valores financieros: los thresholds se transmiten como string BigNumber — sin redondeo.

Ejemplos ​

Escenario 1 — Escalera financiera en BRL

Programa con métrica DEPOSIT_VOLUME, ventana LIFETIME, fiat BRL.

  1. Crea Bronce (threshold 0), Plata (5000), Oro (20000), Diamante (100000).
  2. Define colores/íconos distintos; agrega beneficios (ej.: indicationBonusPercent: 5 en Oro).
  3. Arrastra para garantizar el orden Bronce < Plata < Oro < Diamante.
  4. Genera el NFT de cada nivel con el botón inline.
Escenario 2 — Escalera por puntos

Programa con métrica POINTS.

  1. Los thresholds pasan a mostrarse en pts. Define, ej.: Bronce 0, Plata 1000, Oro 5000.
  2. Asegúrate de tener misiones que otorguen puntos en Misiones para que los usuarios acumulen puntos.
Escenario 3 — Intento de eliminación bloqueado

Al eliminar "Plata" con 37 usuarios en el nivel:

  1. La confirmación es aceptada, pero el backend retorna USERS_IN_TIER con usersInTier=37.
  2. La UI informa que 37 usuarios impiden la eliminación.
  3. Ajusta los thresholds/recomputa para migrar los usuarios y vuelve a intentarlo.

Pantallas relacionadas ​