trading-platform/docs/02-definicion-modulos/OQI-002-education/requerimientos/RF-EDU-006-gamificacion.md

id	title	type	status	priority	module	epic	version	created_date	updated_date
RF-EDU-006	Sistema de Gamificacion	Requirement	Done	Media	education	OQI-002	1.0	2025-12-05	2026-01-04

RF-EDU-006: Sistema de Gamificación

Versión: 1.0.0 Fecha: 2025-12-05 Épica: OQI-002 - Módulo Educativo Prioridad: P2 Story Points: 8

---

Descripción

El sistema debe implementar mecánicas de gamificación que aumenten el engagement y motivación de los usuarios mediante puntos de experiencia (XP), niveles, badges, logros, leaderboards y recompensas, creando una experiencia de aprendizaje más inmersiva y competitiva.

---

Requisitos Funcionales

RF-EDU-006.1: Sistema de XP (Puntos de Experiencia)

El sistema debe otorgar XP por las siguientes acciones:

Acción	XP	Frecuencia
Completar lección de video	10	Por lección
Completar lección de artículo	15	Por lección
Completar módulo	50	Por módulo
Completar curso	200	Por curso
Aprobar quiz (primera vez)	30	Por quiz
Aprobar quiz con 100%	50	Por quiz
Racha de 7 días consecutivos	100	Por milestone
Racha de 30 días consecutivos	500	Por milestone
Tomar notas en lección	5	Máx 1 por lección
Descargar recursos	2	Máx 1 por lección
Compartir certificado	25	Por certificado
Referir a un amigo que se registre	100	Por referido
Completar perfil 100%	50	Una vez
Primera lección del día	5	Diario (bonus)

Bonificaciones:

• Fin de semana: +50% XP sábados y domingos
• Perfectionist: +20% XP si completa curso con todos los quizzes al 100%
• Speed learner: +30% XP si completa curso en <50% del tiempo estimado

RF-EDU-006.2: Sistema de Niveles

Niveles del 1 al 100 con títulos temáticos:

Nivel	XP Acumulado	Título	Descripción
1-10	0 - 5,500	Novice Trader	Iniciando el viaje
11-20	5,500 - 23,100	Apprentice Analyst	Aprendiendo fundamentos
21-30	23,100 - 50,700	Skilled Trader	Dominando estrategias
31-40	50,700 - 88,300	Expert Strategist	Conocimiento avanzado
41-50	88,300 - 136,500	Master Investor	Elite del trading
51-60	136,500 - 196,100	Quant Analyst	Análisis cuantitativo
61-70	196,100 - 267,700	Portfolio Manager	Gestión profesional
71-80	267,700 - 351,300	Market Wizard	Dominio del mercado
81-90	351,300 - 447,900	Trading Legend	Leyenda del trading
91-100	447,900 - 556,500	Quant Master	Maestría absoluta

Recompensas por nivel:

• Nivel 5: Desbloquea tema oscuro premium
• Nivel 10: Badge especial + Avatar frame
• Nivel 15: Acceso a cursos exclusivos
• Nivel 20: Descuento 10% en suscripción
• Nivel 25: Prioridad en soporte
• Nivel 30: Acceso a comunidad premium
• Nivel 50: Certificado de "Elite Trader"
• Nivel 75: Reunión 1-on-1 con instructor
• Nivel 100: Trofeo físico + Lifetime discount 20%

RF-EDU-006.3: Sistema de Badges (Insignias)

Categorías de badges:

Logros de Curso:

• First Steps (completar primer curso)
• Knowledge Seeker (completar 5 cursos)
• Learning Machine (completar 10 cursos)
• Master Scholar (completar 25 cursos)
• Completionist (completar todos los cursos de una categoría)

Logros de Velocidad:

• Fast Learner (completar curso en 1 día)
• Speed Demon (completar 3 cursos en 1 semana)
• Marathon Runner (completar curso de >10h)

Logros de Calidad:

• Perfectionist (aprobar todos los quizzes al 100%)
• Overachiever (superar 95% en todos los quizzes de un curso)
• Note Taker (tomar notas en 50 lecciones)

Logros de Racha:

• Week Warrior (racha de 7 días)
• Month Master (racha de 30 días)
• Unstoppable (racha de 100 días)
• Year Legend (racha de 365 días)

Logros Sociales:

• Influencer (compartir 5 certificados)
• Recruiter (referir 10 usuarios)
• Helper (responder 25 preguntas en foro)

Logros Especiales:

• Early Bird (completar lección antes de las 6am)
• Night Owl (completar lección después de las 11pm)
• Weekend Warrior (completar 5 lecciones en fin de semana)
• Category Master (completar todos los cursos de una categoría)

Cada badge tiene:

• Nombre
• Descripción
• Icono (SVG/PNG)
• Rareza: Común, Raro, Épico, Legendario
• Fecha de obtención
• Progreso hacia obtenerlo (si aplica)

RF-EDU-006.4: Leaderboard (Tabla de Clasificación)

El sistema debe proveer leaderboards:

Global:

• Top 100 usuarios por XP total
• Actualización: Tiempo real

Por Período:

• Esta semana (lunes a domingo)
• Este mes
• Este año
• Histórico

Por Categoría:

• Leaderboard por cada categoría de curso
• Top learners de Análisis Técnico, etc.

Por Métrica:

• Más cursos completados
• Más racha consecutiva
• Más badges obtenidos
• Más rápido en completar curso X

Información mostrada:

• Posición (#1, #2, ...)
• Avatar del usuario
• Nombre/username
• XP total o métrica relevante
• Badge de top 3 (oro, plata, bronce)
• Indicador de subida/bajada de posición

Privacidad:

• Usuario puede optar por salir del leaderboard
• Por default, solo muestra username, no nombre completo
• Top 10 siempre visible, resto opcional

RF-EDU-006.5: Sistema de Logros (Achievements)

Logros son metas específicas que otorgan recompensas:

interface Achievement {
  id: string;
  name: string;
  description: string;
  icon: string;
  category: 'course' | 'speed' | 'quality' | 'streak' | 'social';
  rarity: 'common' | 'rare' | 'epic' | 'legendary';
  xpReward: number;
  badgeReward?: string; // ID del badge que se otorga

  requirements: {
    type: 'courses_completed' | 'quiz_score' | 'streak_days' | 'custom';
    target: number;
    metadata?: any;
  };

  progress?: {
    current: number;
    target: number;
    percentage: number;
  };
}

Ejemplos:

• "Trading Fundamentals Master": Completar todos los cursos de categoría Fundamentos (200 XP + badge)
• "Quiz Perfectionist": Obtener 100% en 20 quizzes (150 XP + badge épico)
• "Dedicated Learner": Mantener racha de 30 días (500 XP + badge raro)

RF-EDU-006.6: Recompensas y Premios

El sistema debe permitir canjear XP o logros por:

• Descuentos en suscripción premium (1000 XP = 5% descuento)
• Acceso early a nuevos cursos (500 XP)
• Merch de Trading Platform (camisetas, stickers) (5000 XP)
• Consulta 1-on-1 con instructor (10,000 XP)
• Features premium temporales (2,000 XP = 1 mes)

Tienda de recompensas:

• Catálogo de items canjeables
• Historial de canjes
• Balance de XP disponible

RF-EDU-006.7: Notificaciones y Celebraciones

El sistema debe mostrar animaciones/notificaciones para:

• Subir de nivel (modal con confeti)
• Obtener nuevo badge (toast notification)
• Completar logro (modal con progreso)
• Entrar al top 100 del leaderboard (email)
• Alcanzar milestone de racha (confeti)
• Obtener XP ("+10 XP" flotante en pantalla)

RF-EDU-006.8: Perfil Gamificado

Página de perfil del usuario debe mostrar:

• Avatar con marco según nivel
• Nivel actual y barra de progreso
• XP actual / XP para próximo nivel
• Total de badges obtenidos
• Galería de badges (destacar raros/épicos)
• Logros recientes
• Estadísticas: cursos, lecciones, quizzes, racha
• Posición en leaderboard global
• Gráfico de XP ganado por mes

---

Datos de Salida

interface UserGamification {
  userId: string;
  totalXP: number;
  currentLevel: number;
  levelTitle: string;
  xpForCurrentLevel: number;
  xpForNextLevel: number;
  progressToNextLevel: number; // 0-100

  badges: {
    id: string;
    name: string;
    description: string;
    icon: string;
    rarity: string;
    earnedAt: string;
  }[];

  achievements: Achievement[];

  leaderboard: {
    globalRank: number;
    weeklyRank: number;
    categoryRanks: {
      category: string;
      rank: number;
    }[];
  };

  stats: {
    coursesCompleted: number;
    quizzesPassed: number;
    currentStreak: number;
    longestStreak: number;
    totalBadges: number;
    rareBadges: number;
    epicBadges: number;
    legendaryBadges: number;
  };
}

interface LeaderboardEntry {
  rank: number;
  userId: string;
  username: string;
  avatar: string;
  totalXP: number;
  level: number;
  badge?: string; // Badge de top 3
  rankChange: number; // +5, -2, 0
}

---

Reglas de Negocio

1. XP no se puede perder: Una vez ganado, permanece
2. Nivel no puede bajar: Solo sube
3. Badges permanentes: No se pueden perder
4. Leaderboard semanal: Reset cada lunes 00:00 UTC
5. Anti-cheat: Validar todas las acciones en backend
6. Rate limiting: Máximo 1000 XP por hora para prevenir exploits
7. Recompensas únicas: Algunos logros se pueden ganar solo una vez
8. Canje de recompensas: Consume XP del balance, pero no baja nivel
9. Privacidad: Usuario puede ocultar su perfil gamificado

---

Criterios de Aceptación

Escenario: Usuario gana XP al completar lección
  DADO que el usuario completa una lección de video
  CUANDO se marca como completada
  ENTONCES se otorgan 10 XP
  Y se muestra animación "+10 XP"
  Y se actualiza barra de progreso de nivel
  Y se guarda en historial de XP

Escenario: Usuario sube de nivel
  DADO que el usuario tiene 990 XP (nivel 9)
  Y necesita 1000 XP para nivel 10
  CUANDO completa un curso y gana 200 XP
  ENTONCES sube a nivel 10
  Y se muestra modal "¡Subiste de nivel!"
  Y se desbloquea badge de nivel 10
  Y se envía notificación por email

Escenario: Usuario obtiene badge
  DADO que el usuario completó 4 cursos
  CUANDO completa el 5to curso
  ENTONCES se otorga badge "Knowledge Seeker"
  Y se muestra toast notification
  Y el badge aparece en galería de perfil
  Y se suman 50 XP adicionales

Escenario: Usuario ve leaderboard
  DADO que el usuario está en posición #42
  CUANDO accede a /education/leaderboard
  ENTONCES se muestra tabla con top 100
  Y su posición está destacada
  Y se muestra su XP y nivel
  Y puede filtrar por: Semanal, Mensual, Histórico

Escenario: Usuario canjea recompensa
  DADO que el usuario tiene 5000 XP disponibles
  CUANDO canjea "Merch Trading Platform" (5000 XP)
  ENTONCES se deduce 5000 XP de balance
  Y se registra el canje
  Y se envía email de confirmación
  Y nivel NO baja (XP acumulado permanece)

Escenario: Progreso hacia logro
  DADO que el usuario completó 7 de 10 cursos para logro
  CUANDO ve página de logros
  ENTONCES se muestra "7/10 cursos"
  Y barra de progreso al 70%
  Y descripción de lo que falta

---

Dependencias

• PostgreSQL para gamification data
• Redis para caché de leaderboards
• Event system para otorgar XP en tiempo real
• Notification service para celebraciones
• Analytics para tracking de engagement

---

Notas Técnicas

• Calcular leaderboard en background job cada 5 minutos
• Usar Redis Sorted Sets para leaderboards rápidos
• Implementar event handlers para cada acción que otorga XP
• Crear índices en tablas de XP y badges para queries rápidas
• Considerar rate limiting para prevenir farming de XP
• Implementar audit log de XP ganado/gastado
• Usar WebSockets para notificaciones en tiempo real

---

Referencias

• Schema: /backend/src/database/schemas/gamification.sql
• API: /backend/src/modules/gamification/
• Frontend: /frontend/src/pages/Leaderboard.tsx

---

Tareas Técnicas

Database:

• Tabla gamification.user_xp: user_id, total_xp, level
• Tabla gamification.badges: definición de badges
• Tabla gamification.user_badges: user_id, badge_id, earned_at
• Tabla gamification.achievements: definición de logros
• Tabla gamification.user_achievements: progreso de usuario
• Tabla gamification.xp_transactions: log de XP ganado/gastado
• Tabla gamification.leaderboard: caché de rankings
• Índices para queries de leaderboard

Backend:

• Endpoint GET /gamification/profile (stats del usuario)
• Endpoint GET /gamification/leaderboard
• Endpoint GET /gamification/badges
• Endpoint GET /gamification/achievements
• Endpoint POST /gamification/rewards/redeem
• Implementar GamificationService.awardXP()
• Implementar GamificationService.checkLevelUp()
• Implementar GamificationService.checkAchievements()
• Event handlers para todas las acciones que otorgan XP
• Cron job para calcular leaderboards

Frontend:

• Crear LeaderboardPage.tsx
• Crear BadgesGalleryPage.tsx
• Crear AchievementsPage.tsx
• Crear RewardsStorePage.tsx
• Crear componente XPAnimation.tsx
• Crear componente LevelUpModal.tsx
• Crear componente BadgeToast.tsx
• Crear componente ProgressBar.tsx para nivel
• Integrar gamificación en perfil de usuario
• Implementar gamificationStore

Tests:

• Test cálculo de nivel según XP
• Test otorgamiento de badges automático
• Test ranking en leaderboard
• Test canje de recompensas

---

Creado por: Requirements-Analyst Fecha: 2025-12-05 Última actualización: 2025-12-05