Skip to main content
Traducción. Autoritativo: fs-loy-0010-tiers.md.

​
Contexto

Los niveles son el mecanismo de retención de un programa: le dan al member algo que perder. Eso los convierte también en la feature más cargada emocionalmente del módulo — un descenso que el member no vio venir es un ticket de soporte y muchas veces un cliente que se va. Dos decisiones cargan casi todo el peso. La ventana de calificación —doce meses móviles versus año calendario— cambia la sensación completa del programa: móvil es continua y justa, calendario crea un empujón de fin de año y un precipicio en enero. Y la política de descenso, que necesita un período de gracia no por corrección sino porque bajar a alguien en el instante en que cae bajo un umbral es una falla de producto aunque sea aritméticamente correcto. Para esto existen los puntos de estatus (ADR-011). Calificar con puntos canjeables significaría que un member pierde estatus por gastar, lo que castiga exactamente el comportamiento que el programa busca.

​
Alcance (normativo)

  • loyalty.tier_definitions: niveles ordenados con umbrales contra una métrica de calificación.
  • loyalty.tier_qualification_metrics: paramétrica, semillas is_system points_earned, spend, event_count.
  • Modos de ventana rolling_days y calendar_year.
  • loyalty.tier_memberships con historia completa: entrada, salida, razón.
  • Política de descenso explícita con período de gracia configurable.
  • loyalty.tier_overrides: multiplicadores de acumulación, precios de recompensas y extensión de expiración por nivel.
  • Recomputación guiada por eventos del libro, con una red de seguridad programada.

​
Fuera de alcance (normativo)

  • Notificaciones de nivel. Esta feature emite los eventos; las campañas son messaging.
  • Asignación manual de nivel por el personal — una feature de consola posterior, con su propia semántica de auditoría.
  • Visibilidad de recompensas gateada por nivel más allá del override de precio, que es asunto de FS-LOY-0005.

​
Comportamiento (normativo)

  1. Los niveles se ordenan por level, único por programa, con umbrales estrictamente crecientes. Dos niveles en el mismo level están PROHIBIDOS.
  2. La calificación usa la métrica configurada sobre la ventana configurada. Los puntos canjeables nunca califican: gastar no debe costar estatus.
  3. Los ascensos son inmediatos al cruzar un umbral. Un member nunca debería esperar por una buena noticia.
  4. Los descensos nunca son inmediatos. El member entra en un período de gracia; si vuelve a calificar antes de que termine, no se registra descenso alguno. Solo al vencer se aplica y se emite.
  5. La historia de membresía es append-only. El nivel de un member en cualquier fecha pasada debe ser reconstruible — eso es lo que responde “por qué me cobraron ese precio”.
  6. tier_overrides aplican en el momento de la transacción, no retroactivamente. Llegar a Gold no revalúa el canje de ayer.
  7. La recomputación es guiada por eventos en las escrituras del libro y reverificada por un job programado según el tier de frescura del tenant. Una divergencia se alerta, nunca se corrige en silencio. 7b. Cuando la moneda de estatus está configurada para expirar (OQ-LOY-02, FS-LOY-0002), la métrica de calificación baja sola y un member puede descender sin haber dejado de comprar. En esa configuración el período de gracia y el evento tier.grace_started son obligatorios, y members/me/tier DEBE mostrar la caída proyectada y su fecha antes de que ocurra. Una flexibilidad que sorprende a un member es un ticket de soporte, no una feature.
  8. tier_qualification_metrics no es extensible por tenant: la métrica gobierna lógica del sistema.

​
Datos (normativo)

​
API (normativo)

members/me/tier devuelve el nivel actual, el progreso hacia el siguiente y —cuando está en gracia— la fecha en que se aplicaría el descenso. Ocultar esa fecha sería la decisión más hostil con el usuario disponible aquí.

​
Eventos (normativo)

loyalty.tier.upgraded y loyalty.tier.downgraded, ambos disponibles como webhooks salientes. Entrar en gracia no emite evento en F1; si debería hacerlo es una pregunta abierta más abajo.

​
Criterios de aceptación (normativo)

  1. Cruzar un umbral asciende dentro de 5 s p95 desde la escritura calificante del libro y emite una vez.
  2. Caer bajo un umbral inicia la gracia y no desciende. Volver a calificar dentro de la gracia no registra descenso alguno.
  3. El vencimiento de la gracia desciende y emite exactamente una vez.
  4. Corrección de ventana móvil: un member cuya actividad calificante tiene 366 días deja de contarla, verificado contra una línea de tiempo sembrada.
  5. La historia de membresía reconstruye el nivel que tenía en cualquier fecha pasada.
  6. Un multiplicador de override aplica a las acumulaciones posteriores al ascenso y no a las anteriores.
  7. Negativo: canjear puntos nunca baja la métrica de calificación de un member.

​
Ejecución

Pipeline asíncrono, guiado por eventos del libro; la recomputación de red de seguridad es un job programado con fan-out por tenant.

​
Preguntas abiertas

Ninguna pendiente. Toda pregunta que llevaba este spec quedó respondida en el registro consolidado (../../../../design/open-questions-v1.md, v1.1) y se incorporó a las secciones normativas de arriba.

​
Changelog

​
Registro de entrega

Aún no implementado.