Esquema de gamificación PostgreSQL: 5 tablas, 12 niveles

Puntos clave a recordar: Un sistema de gamificación sólido se basa en un esquema PostgreSQL dedicado con 5 tablas, RPC atómicas transaccionales y una progresión calibrada en 12 niveles. El secreto: aislar la gamificación en su propio esquema, limitar las rachas a 365 días para evitar la adicción y hacer que todo sea atómico para garantizar la coherencia de los datos.

La gamificación parece simple en la superficie. Puntos, insignias, una tabla de clasificación, parece fácil, ¿verdad? En realidad, tan pronto como empezamos a modelar seriamente, la complejidad explota. Para TAMSIV, quería un sistema completo: niveles, insignias, rachas, desafíos diarios, historial de puntos y un feed de actividad. Todo en PostgreSQL, con garantías transaccionales.

Así es como diseñé el esquema de gamificación de TAMSIV, tabla por tabla, decisión por decisión.

¿Por qué un esquema PostgreSQL dedicado para la gamificación?

TAMSIV ya utiliza dos esquemas en Supabase: privat para los datos del usuario (tareas, notas, eventos) y collaborative para las funcionalidades de grupo. Podría haber añadido las tablas de gamificación en privat. Pero no lo hice.

El esquema gamification es un esquema dedicado y aislado. ¿Por qué?

• Separación de responsabilidades: la gamificación tiene sus propias políticas RLS (Row Level Security), sus propias funciones RPC, sus propios índices. No hay mezcla con la lógica de negocio.
• Evolución independiente: puedo modificar el sistema de puntos o añadir insignias sin riesgo de romper la creación de tareas.
• Rendimiento: las consultas de gamificación (tabla de clasificación, ranking, estadísticas) no comparten los índices con las tablas de contenido.
• Seguridad: las políticas RLS de gamificación son más simples: un usuario solo ve sus propias estadísticas. No hay permisos de grupo que gestionar.

Este enfoque sigue el principio de separación de esquemas recomendado por PostgreSQL. Cada esquema es un espacio de nombres que aísla las tablas, funciones y políticas de seguridad.

¿Cuáles son las 5 tablas del esquema de gamificación?

El esquema completo se basa en 5 tablas interconectadas:

1. user_stats — el panel de control de cada jugador

Esta es la tabla central. Almacena el estado actual de cada usuario:

• total_points: la puntuación acumulada desde el principio
• current_level: el nivel actual (1 a 12+)
• current_streak: el número de días consecutivos de actividad
• max_streak: el récord personal de racha
• last_activity_date: la fecha de la última actividad (para el cálculo de la racha)
• streak_freeze_count: el número de "congelaciones" de racha disponibles

¿Por qué almacenar el nivel en lugar de calcularlo sobre la marcha? Porque la verificación del nivel implica una comparación con los umbrales, y esta verificación debe ser atómica con la adición de puntos. Si el cálculo se hiciera del lado del cliente, se correría el riesgo de inconsistencias.

2. user_badges — la colección de logros

Una relación muchos a muchos entre usuarios e insignias. Cada fila registra:

• El ID de la insignia (entre las 10 insignias disponibles)
• La fecha de obtención
• El contexto de obtención (qué acción desencadenó la insignia)

Las insignias en TAMSIV recompensan comportamientos específicos: primera nota de voz, 10 tareas completadas, 7 días de racha, etc. Nunca se retiran, una insignia obtenida es para siempre.

3. points_history — el registro de cada ganancia

Cada ganancia de puntos se registra individualmente. Esta tabla es esencial para:

• Análisis (¿qué acciones generan más puntos?)
• Depuración (¿un usuario disputa su puntuación? Tenemos el rastro)
• Desafíos diarios (verificación de condiciones)
• El feed de actividad (visualización cronológica de las ganancias)

4. daily_challenges — un desafío por día

Cada día, cada usuario recibe un desafío personalizado. La tabla almacena:

• El tipo de desafío (crear X tareas, usar la voz, completar una nota, etc.)
• El objetivo numérico (3 tareas, 5 notas, etc.)
• El progreso actual
• El estado (en curso, completado, expirado)

Los desafíos son generados por una función RPC que tiene en cuenta el nivel del usuario: un principiante recibe desafíos más simples que un jugador de nivel 10.

5. feed_activity — el flujo social

El feed de actividad muestra las acciones recientes: insignias obtenidas, niveles alcanzados, rachas notables. Es la dimensión social de la gamificación: ver que otros usuarios progresan motiva.

¿Cómo funcionan los 12 niveles de progresión?

El sistema de niveles es el corazón de la gamificación. Los umbrales de puntos para cada nivel:

[0, 100, 250, 500, 1000, 2000, 3500, 5500, 8000, 12000, 17500, 25000]

Esta progresión sigue una curva exponencial suavizada. Los primeros niveles son voluntariamente fáciles:

• Niveles 1-3 (0 a 250 puntos): alcanzables en 2-3 días de uso normal. Esta es la fase de onboarding: el usuario descubre el sistema y recibe gratificaciones rápidas.
• Niveles 4-7 (500 a 3500 puntos): la fase de compromiso. 1 a 4 semanas. El usuario ha integrado TAMSIV en su rutina.
• Niveles 8-10 (5500 a 12000 puntos): la fase de maestría. Varios meses. Estos niveles son una señal de fuerte retención.
• Niveles 11-12 (17500 a 25000 puntos): los "logradores". Menos del 5% de los usuarios los alcanzan.

¿Más allá del nivel 12? Una fórmula matemática toma el relevo: umbral = 25000 + (nivel - 12) * 10000. Esto evita codificar cientos de niveles a la vez que permite una progresión infinita.

Esta calibración se inspira en el trabajo de Yu-kai Chou sobre el framework Octalysis, que recomienda recompensas inmediatas al principio del recorrido y una dificultad progresiva para mantener el compromiso a largo plazo.

¿Por qué las funciones RPC deben ser atómicas?

Cuando un usuario completa una tarea en TAMSIV, esto es lo que debe suceder en el lado de la gamificación:

1. Añadir los puntos correspondientes
2. Verificar si se ha alcanzado el umbral del siguiente nivel
3. Actualizar la racha (día consecutivo de actividad)
4. Verificar si se han desbloqueado nuevas insignias
5. Actualizar el progreso del desafío diario
6. Registrar el historial de puntos

Si el paso 3 falla después de que el paso 1 haya tenido éxito, los datos son inconsistentes. Por eso, todas estas operaciones están encapsuladas en funciones PostgreSQL transaccionales. O todo tiene éxito, o todo falla.

La función principal record_task_completed orquesta todo en una sola transacción:

• add_gamification_points — añade los puntos y registra el historial
• check_and_update_streak — actualiza la racha con gestión de zonas horarias
• check_and_unlock_badges — verifica las condiciones de cada insignia

En el frontend, el GamificationService (singleton) llama a estas RPC y gestiona las notificaciones locales para las insignias, los niveles y los hitos de racha.

¿Cómo gestionar las rachas sin volver adictos a los usuarios?

Las rachas son el mecanismo de gamificación más potente, y el más peligroso. Una racha de 100 días crea una presión enorme para no "romperla". Por eso he puesto salvaguardias:

• Límite de 365 días: después de un año, la racha se reinicia. Una racha de 500 días ya no es gamificación, es adicción por diseño.
• Congelaciones de racha: el usuario puede "congelar" su racha por un día (vacaciones, enfermedad). El número de congelaciones disponibles aumenta con el nivel.
• Sin castigo: perder una racha no quita puntos ni insignias. Simplemente reinicia el contador.

La gestión de las zonas horarias es un rompecabezas técnico. Un usuario en París y un usuario en Tokio no tienen el mismo "día". La detección de la ruptura de la racha se realiza comparando last_activity_date con la fecha actual en la zona horaria del usuario, no en UTC.

¿Cómo consume el frontend la gamificación?

El GamificationService es un singleton que centraliza todas las interacciones del frontend con el esquema de gamificación:

• Llamadas RPC: cada finalización de tarea o creación de nota desencadena una llamada a record_task_completed o record_memo_created.
• Notificaciones locales: a través de NotificationService.notifyAchievement(), el usuario es notificado de insignias, subidas de nivel e hitos de racha.
• Caché optimizado: las estadísticas del usuario se almacenan en caché localmente para evitar una llamada a Supabase cada vez que se muestra el perfil.
• Feed en tiempo real: el feed de actividad utiliza Supabase Realtime para mostrar los logros de otros usuarios en directo.

La integración en el Dictáfono es transparente: cuando la IA crea una tarea por voz, el hook useTaskDetail llama automáticamente al GamificationService al finalizar. El usuario no tiene que hacer nada, los puntos caen naturalmente.

¿Qué métricas monitorear para ajustar la gamificación?

La tabla points_history permite analizar finamente:

• Distribución de niveles: si el 80% de los usuarios están atascados en el nivel 3, los umbrales son demasiado altos.
• Tasa de finalización de desafíos: por debajo del 30%, los desafíos son demasiado difíciles. Por encima del 90%, demasiado fáciles.
• Racha promedio: un indicador directo de la retención diaria.
• Insignias más raras: las insignias que nadie obtiene deben ser reevaluadas.

Todo es visible en el panel de administración con gráficos de Recharts. Esto permite ajustar los umbrales en producción sin volver a desplegar.

¿Cómo evitar las trampas clásicas de la gamificación?

La gamificación mal diseñada hace más daño que bien. Aquí están las trampas que evité:

• Sin tabla de clasificación pública: las clasificaciones públicas desmoralizan al 95% de los usuarios para motivar al 5% superior. TAMSIV muestra el progreso personal, no la competencia.
• Sin gamificación punitiva: perder puntos por inactividad es un patrón oscuro. En TAMSIV, la inactividad no tiene ninguna consecuencia negativa.
• Puntos significativos: cada punto corresponde a una acción real (tarea creada, nota grabada, racha mantenida). No hay puntos gratuitos por "iniciar sesión".
• Retroalimentación inmediata: las notificaciones de insignias y subidas de nivel llegan instantáneamente, no al final del día.

¿Cómo aplicar este esquema a tu propio proyecto?

Si quieres implementar un sistema de gamificación similar, aquí tienes los principios:

1. Aísla el esquema: no mezcles gamificación y lógica de negocio. Un esquema dedicado facilita las migraciones y la depuración.
2. Todo atómico: cada acción de usuario que impacta la gamificación debe ser una transacción única.
3. Calibra la progresión: prueba los umbrales de nivel con datos reales. Los primeros niveles deben ser alcanzables en días, no en semanas.
4. Prevé el mantenimiento: la tabla points_history crece rápidamente. Prevé una política de retención o archivo.
5. Mide todo: sin análisis, no sabrás si tu gamificación motiva o frustra a tus usuarios.

Preguntas frecuentes

¿Cuánto tiempo se tarda en implementar un sistema de gamificación completo?

Para TAMSIV, el esquema y las RPC tardaron aproximadamente 4 días. La integración del frontend (GamificationService, notificaciones, UI) añadió 3 días adicionales. Lo más largo es la calibración de los umbrales de nivel, que requiere datos de uso reales.

¿PostgreSQL es adecuado para la gamificación o se necesita Redis?

PostgreSQL es más que suficiente para una aplicación del tamaño de TAMSIV. Las funciones transaccionales garantizan la coherencia, y los índices en user_stats hacen que las consultas sean rápidas. Redis solo sería útil para una tabla de clasificación en tiempo real con millones de usuarios, lo cual no es el caso aquí.

¿Cómo evitar que la gamificación se convierta en un patrón oscuro?

Tres reglas: no castigar la inactividad, no presionar socialmente a través de una tabla de clasificación pública y un límite en las rachas. La gamificación debe recompensar la acción, no castigar la ausencia. La congelación de rachas es un mecanismo de seguridad esencial.

¿Los puntos deben ser los mismos para todas las acciones?

No. En TAMSIV, completar una tarea vale más que crear una nota, y usar la voz da un bono. La escala refleja el valor de cada acción para el usuario. Una escala plana (todo vale 10 puntos) no crea ninguna jerarquía de comportamiento.

¿Se deben mostrar los puntos en tiempo real o con retraso?

En tiempo real, siempre. La retroalimentación inmediata es la base de una gamificación efectiva. En TAMSIV, los puntos se muestran instantáneamente después de cada acción, con una animación y un sonido opcional. El retraso mata la dopamina.