rckrdmrd
a7cca885f0
Changes include: - Updated architecture documentation - Enhanced module definitions (OQI-001 to OQI-008) - ML integration documentation updates - Trading strategies documentation - Orchestration and inventory updates - Docker configuration updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
445 lines
13 KiB
Markdown
445 lines
13 KiB
Markdown
---
|
|
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 OrbiQuant (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 OrbiQuant" (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
|