---
id: "US-EDU-007"
title: "Ver Progreso Educativo"
type: "User Story"
status: "Done"
priority: "Alta"
epic: "OQI-002"
story_points: 3
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# US-EDU-007: Ver Progreso Educativo

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-EDU-007 |
| **Épica** | OQI-002 - Módulo Educativo |
| **Módulo** | education |
| **Prioridad** | P0 |
| **Story Points** | 3 |
| **Sprint** | Sprint 4 |
| **Estado** | Pendiente |
| **Asignado a** | Por asignar |

---

## Historia de Usuario

**Como** usuario activo en la plataforma educativa,
**quiero** ver un dashboard con mi progreso de aprendizaje completo,
**para** monitorear mi avance, mantenerme motivado y planificar mi siguiente paso.

## Descripción Detallada

El usuario debe poder acceder a un dashboard educativo centralizado que muestre métricas clave de su aprendizaje: cursos en progreso con porcentajes, cursos completados, total de lecciones vistas, horas de estudio, racha actual, nivel y XP, actividad reciente, calendario de aprendizaje, y sugerencias de qué estudiar a continuación.

## Mockups/Wireframes

```
┌─────────────────────────────────────────────────────────────────┐
│  [LOGO] Trading Platform     Educación    Trading    Cuentas    👤  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  MI APRENDIZAJE                                                 │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  RESUMEN GENERAL                                          │  │
│  │                                                           │  │
│  │  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐         │  │
│  │  │ 🔄 3   │  │ ✅ 12  │  │ 📚 156 │  │ ⏱ 42h │         │  │
│  │  │ En prog│  │ Comple │  │ Lecc.  │  │ Estudio│         │  │
│  │  └────────┘  └────────┘  └────────┘  └────────┘         │  │
│  │                                                           │  │
│  │  ┌───────────────────┐  ┌─────────────────┐             │  │
│  │  │ 🔥 RACHA: 12 DÍAS │  │ ⭐ NIVEL 15     │             │  │
│  │  │ ¡Sigue así!       │  │ 2,450 / 3,000 XP│             │  │
│  │  │ 📅📅📅📅📅📅📅 │  │ ████████░░ 82%  │             │  │
│  │  └───────────────────┘  └─────────────────┘             │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  CURSOS EN PROGRESO (3)                                   │  │
│  │                                                           │  │
│  │  ┌────────────────────────────────────────────────────┐  │  │
│  │  │ [IMG] Fibonacci Retracement Básico                  │  │  │
│  │  │ ████████████████░░░░ 75% completado                 │  │  │
│  │  │ 18 de 23 lecciones | Módulo 4 de 5                  │  │  │
│  │  │ Última vez: Hace 2 horas                            │  │  │
│  │  │ [Continuar →] Lección: Fibonacci en tendencias      │  │  │
│  │  └────────────────────────────────────────────────────┘  │  │
│  │                                                           │  │
│  │  ┌────────────────────────────────────────────────────┐  │  │
│  │  │ [IMG] Day Trading para Principiantes                │  │  │
│  │  │ ██████░░░░░░░░░░░░░░ 30% completado                 │  │  │
│  │  │ 9 de 30 lecciones | Módulo 2 de 6                   │  │  │
│  │  │ Última vez: Hace 1 día                              │  │  │
│  │  │ [Continuar →] Lección: Análisis de volumen          │  │  │
│  │  └────────────────────────────────────────────────────┘  │  │
│  │                                                           │  │
│  │  [Ver todos los cursos en progreso]                      │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌─────────────────────┐  ┌─────────────────────────────────┐  │
│  │ ACTIVIDAD RECIENTE  │  │ CALENDARIO DE APRENDIZAJE       │  │
│  │                     │  │                                 │  │
│  │ Hoy, 15:30         │  │  L  M  X  J  V  S  D            │  │
│  │ ✓ Completaste      │  │ ██ ██ ░░ ██ ██ ██ ░░          │  │
│  │   "Niveles de Fib."│  │ ██ ██ ██ ██ ██ ░░ ░░          │  │
│  │   +10 XP           │  │ ██ ██ ██ ░░ ░░ ░░ ░░          │  │
│  │                     │  │                                 │  │
│  │ Hoy, 14:20         │  │ Días activos este mes: 18       │  │
│  │ ✅ Aprobaste       │  │                                 │  │
│  │   Quiz Módulo 3    │  │                                 │  │
│  │   +30 XP           │  │                                 │  │
│  │                     │  │                                 │  │
│  │ Ayer, 18:45        │  │                                 │  │
│  │ 🎓 Obtuviste       │  │                                 │  │
│  │   badge "Week      │  │                                 │  │
│  │   Warrior"         │  │                                 │  │
│  │                     │  │                                 │  │
│  │ [Ver más]          │  │                                 │  │
│  └─────────────────────┘  └─────────────────────────────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  📊 ESTADÍSTICAS                                          │  │
│  │                                                           │  │
│  │  Tiempo promedio por lección: 15 min                     │  │
│  │  Cursos completados este mes: 3                          │  │
│  │  Tasa de completitud: 80% (12 de 15 cursos iniciados)    │  │
│  │  Categoría favorita: Análisis Técnico (6 cursos)         │  │
│  │  Mejor día de la semana: Miércoles (25 lecciones)        │  │
│  │                                                           │  │
│  │  [📈 Ver estadísticas detalladas]                        │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Ver dashboard de progreso**
```gherkin
DADO que el usuario está autenticado
CUANDO navega a /education/progress o /education/dashboard
ENTONCES se muestra dashboard completo de aprendizaje
Y se muestran métricas: cursos en progreso, completados, lecciones, horas
Y se muestra racha actual con visualización de días
Y se muestra nivel actual y progreso a siguiente nivel
Y se muestran cursos en progreso con porcentajes
Y se muestra actividad reciente
```

**Escenario 2: Ver cursos en progreso**
```gherkin
DADO que el usuario tiene 3 cursos en progreso
CUANDO ve la sección "Cursos en progreso"
ENTONCES se muestran los 3 cursos ordenados por última actividad
Y cada curso muestra: título, imagen, porcentaje, lecciones completadas
Y se muestra "Última vez: hace X tiempo"
Y se muestra botón "Continuar" con próxima lección
Y al hacer click en "Continuar", navega a esa lección
```

**Escenario 3: Ver racha activa**
```gherkin
DADO que el usuario tiene racha de 12 días
CUANDO ve el widget de racha
ENTONCES se muestra "🔥 RACHA: 12 DÍAS"
Y se muestra visualización de últimos 7 días
Y se muestra mensaje motivacional "¡Sigue así!"
Y si no completó lección hoy, muestra "Completa 1 lección hoy para mantener racha"
```

**Escenario 4: Ver nivel y XP**
```gherkin
DADO que el usuario es nivel 15 con 2450 XP
Y necesita 3000 XP para nivel 16
CUANDO ve el widget de nivel
ENTONCES se muestra "⭐ NIVEL 15"
Y se muestra "2,450 / 3,000 XP"
Y se muestra barra de progreso al 82%
Y se muestra cuántos XP faltan: "Faltan 550 XP para nivel 16"
```

**Escenario 5: Ver calendario de actividad**
```gherkin
DADO que el usuario completó lecciones en 18 días este mes
CUANDO ve el calendario
ENTONCES se muestra grid estilo GitHub contributions
Y días con actividad están resaltados (cuadros llenos)
Y días sin actividad están vacíos
Y al hacer hover sobre un día, muestra detalle: "3 lecciones, 45 min"
Y se muestra contador "Días activos este mes: 18"
```

**Escenario 6: Ver actividad reciente**
```gherkin
DADO que el usuario tiene actividad reciente
CUANDO ve la sección "Actividad reciente"
ENTONCES se muestran últimos 10 eventos
Y cada evento muestra: timestamp, tipo, descripción, XP ganado
Y eventos incluyen: lección completada, quiz aprobado, badge obtenido
Y se ordenan de más reciente a más antiguo
Y hay botón "Ver más" para ver historial completo
```

**Escenario 7: Ver estadísticas**
```gherkin
DADO que el usuario tiene suficiente actividad
CUANDO ve la sección "Estadísticas"
ENTONCES se muestra tiempo promedio por lección
Y se muestra cursos completados este mes
Y se muestra tasa de completitud (cursos finalizados / iniciados)
Y se muestra categoría favorita
Y se muestra mejor día de la semana
Y hay botón para ver estadísticas detalladas
```

**Escenario 8: Continuar curso desde dashboard**
```gherkin
DADO que el usuario tiene curso en progreso
Y la última lección accedida fue "Lección 18"
CUANDO hace click en "Continuar" del curso
ENTONCES navega directamente a la Lección 19 (siguiente)
Y el reproductor se carga listo para comenzar
```

**Escenario 9: Usuario sin actividad reciente**
```gherkin
DADO que el usuario no tiene actividad en últimos 7 días
CUANDO accede al dashboard
ENTONCES se muestra mensaje de bienvenida
Y se sugieren cursos populares para comenzar
Y se muestra motivación: "¡Comienza hoy tu racha de aprendizaje!"
Y las métricas muestran valores cero elegantemente
```

**Escenario 10: Racha en riesgo**
```gherkin
DADO que el usuario tiene racha de 15 días
Y NO ha completado lecciones hoy
Y es después de las 6pm hora local
CUANDO accede al dashboard
ENTONCES se muestra alerta "⚠ ¡Racha en riesgo!"
Y se muestra "Completa 1 lección antes de medianoche"
Y se sugiere lección corta: "Lección rápida (5 min): [título]"
```

## Criterios Adicionales

- [ ] Gráfico de XP ganado por semana/mes
- [ ] Comparación con usuarios similares (opcional)
- [ ] Metas personales de aprendizaje
- [ ] Exportar reporte de progreso en PDF
- [ ] Compartir logros en redes sociales
- [ ] Widget de "Próximas recompensas" (badge a desbloquear)

---

## Tareas Técnicas

**Database:**
- [ ] DB-EDU-020: Vista materialized para stats de usuario
- [ ] DB-EDU-021: Índices en user_activity_log por user_id + timestamp

**Backend:**
- [ ] BE-EDU-049: Endpoint GET /education/progress/overview
- [ ] BE-EDU-050: Endpoint GET /education/progress/courses
- [ ] BE-EDU-051: Endpoint GET /education/progress/stats
- [ ] BE-EDU-052: Endpoint GET /education/progress/activity
- [ ] BE-EDU-053: Endpoint GET /education/progress/calendar
- [ ] BE-EDU-054: Implementar ProgressService.getOverview()
- [ ] BE-EDU-055: Job diario para calcular stats agregadas
- [ ] BE-EDU-056: Caché de stats en Redis (15 min)

**Frontend:**
- [ ] FE-EDU-060: Crear EducationDashboardPage.tsx
- [ ] FE-EDU-061: Crear componente ProgressOverview.tsx
- [ ] FE-EDU-062: Crear componente CourseProgressCard.tsx
- [ ] FE-EDU-063: Crear componente StreakWidget.tsx
- [ ] FE-EDU-064: Crear componente LevelWidget.tsx
- [ ] FE-EDU-065: Crear componente ActivityCalendar.tsx (GitHub style)
- [ ] FE-EDU-066: Crear componente RecentActivity.tsx
- [ ] FE-EDU-067: Crear componente StatsPanel.tsx
- [ ] FE-EDU-068: Implementar progressStore (Zustand)
- [ ] FE-EDU-069: Skeleton loaders para cada sección

**Tests:**
- [ ] TEST-EDU-026: Test cálculo de tasa de completitud
- [ ] TEST-EDU-027: Test cálculo de racha
- [ ] TEST-EDU-028: Test stats agregadas
- [ ] TEST-EDU-029: Test E2E visualizar dashboard completo

---

## Dependencias

**Depende de:**
- [ ] US-EDU-005: Completar lección - Estado: Pendiente
- [ ] RF-EDU-003: Sistema de progreso
- [ ] RF-EDU-006: Gamificación (para nivel y XP)

**Bloquea:**
- Ninguna (es página de visualización)

---

## Notas Técnicas

**Endpoint GET /education/progress/overview:**
```typescript
{
  overview: {
    coursesInProgress: 3,
    coursesCompleted: 12,
    coursesSaved: 5,
    lessonsCompleted: 156,
    totalLearningTime: 2520, // minutos (42h)
    currentStreak: 12,
    longestStreak: 18,
    totalXP: 2450,
    currentLevel: 15,
    xpToNextLevel: 550
  },

  coursesInProgress: [
    {
      courseId: "course-1",
      title: "Fibonacci Retracement Básico",
      slug: "fibonacci-retracement-basico",
      thumbnail: "...",
      progressPercent: 75,
      lessonsCompleted: 18,
      totalLessons: 23,
      modulesCompleted: 3,
      totalModules: 5,
      lastAccessedAt: "2025-12-05T13:30:00Z",
      nextLesson: {
        id: "les-19",
        title: "Fibonacci en tendencias bajistas",
        slug: "fibonacci-tendencias-bajistas",
        duration: 12
      }
    }
    // ... más cursos
  ],

  recentActivity: [
    {
      type: "lesson_completed",
      title: "Completaste 'Niveles de Fibonacci'",
      description: "Lección 2.1 del curso Fibonacci Básico",
      timestamp: "2025-12-05T15:30:00Z",
      xpEarned: 10,
      icon: "✓"
    },
    {
      type: "quiz_passed",
      title: "Aprobaste Quiz Módulo 3",
      description: "Puntuación: 85%",
      timestamp: "2025-12-05T14:20:00Z",
      xpEarned: 30,
      icon: "✅"
    }
    // ... más actividad
  ],

  calendar: [
    { date: "2025-12-01", lessonsCompleted: 3, minutesLearned: 45 },
    { date: "2025-12-02", lessonsCompleted: 2, minutesLearned: 30 },
    { date: "2025-12-03", lessonsCompleted: 0, minutesLearned: 0 },
    // ...
  ],

  stats: {
    avgTimePerLesson: 15,
    coursesThisMonth: 3,
    completionRate: 80, // 12 completados de 15 iniciados
    activeDays: 18,
    favoriteCategory: "Análisis Técnico",
    bestDayOfWeek: "Wednesday",
    preferredTimeOfDay: "Evening"
  }
}
```

**Cálculos importantes:**
```javascript
// Racha actual
currentStreak = countConsecutiveDaysWithActivity(today, lookback=365);

// Tasa de completitud
completionRate = (coursesCompleted / coursesStarted) * 100;

// Tiempo promedio por lección
avgTimePerLesson = totalLearningTime / lessonsCompleted;

// Categoría favorita
favoriteCategory = categoryWithMostCompletedCourses();
```

**Optimizaciones:**
- Usar materialized views para stats agregadas
- Calcular stats en background job nocturno
- Cachear overview en Redis (15 min)
- Lazy load de secciones con IntersectionObserver
- Implementar skeleton loading para mejor UX

**Entidades/Tablas:**
- `education.user_course_progress`
- `education.user_lesson_progress`
- `education.user_activity_log`
- `gamification.user_stats`

---

## Definition of Ready (DoR)

- [x] Historia claramente escrita
- [x] Criterios de aceptación definidos
- [x] Story points estimados
- [x] Dependencias identificadas
- [x] Sin bloqueadores
- [x] Diseño/mockup disponible
- [x] API spec disponible

## Definition of Done (DoD)

- [ ] Código implementado según criterios
- [ ] Tests unitarios escritos y pasando
- [ ] Tests de integración pasando
- [ ] Code review aprobado
- [ ] Documentación actualizada
- [ ] QA aprobado
- [ ] Desplegado en ambiente de pruebas

---

## Historial de Cambios

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-05 | Creación | Requirements-Analyst |

---

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