---
id: "RF-EDU-006"
title: "Sistema de Gamificacion"
type: "Requirement"
status: "Done"
priority: "Media"
module: "education"
epic: "OQI-002"
version: "1.0"
created_date: "2025-12-05"
updated_date: "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:

```typescript
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

```typescript
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

```gherkin
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