# US-EDU-001: Ver Catálogo de Cursos

## Metadata

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

---

## Historia de Usuario

**Como** usuario interesado en aprender trading,
**quiero** ver un catálogo completo de cursos disponibles con filtros y búsqueda,
**para** descubrir contenido educativo relevante a mi nivel y áreas de interés.

## Descripción Detallada

El usuario debe poder acceder a una página que muestre todos los cursos educativos disponibles en la plataforma. Debe poder filtrar por categoría (Fundamentos, Análisis Técnico, etc.), nivel de dificultad (Principiante, Intermedio, Avanzado), y buscar por palabras clave. Cada curso debe mostrar información clave como título, instructor, duración, número de estudiantes, rating, y el progreso del usuario si ya está inscrito.

## Mockups/Wireframes

```
┌─────────────────────────────────────────────────────────────────┐
│  [LOGO] OrbiQuant IA     Educación    Trading    Cuentas    👤  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  CATÁLOGO DE CURSOS                         [🔍 Buscar cursos...] │
│                                                                  │
│  ┌────────────────┐  ┌──────────────────────────────────────┐  │
│  │ FILTROS        │  │  Mostrando 24 de 47 cursos           │  │
│  │                │  │  Ordenar: [Más recientes ▼]          │  │
│  │ Categorías     │  │                                       │  │
│  │ □ Fundamentos  │  │  ┌─────────┐  ┌─────────┐  ┌─────────┐│
│  │ ✓ Análisis T.  │  │  │[IMG]    │  │[IMG]    │  │[IMG]    ││
│  │ □ Gestión Riesgo│ │  │Fibonacci│  │Candlestk│  │Day Trad.││
│  │                │  │  │básico   │  │Avanzado │  │Pro      ││
│  │ Nivel          │  │  │⭐ 4.8   │  │⭐ 4.9   │  │⭐ 4.7   ││
│  │ ✓ Principiante │  │  │2h 30m   │  │4h 15m   │  │6h 45m   ││
│  │ ✓ Intermedio   │  │  │1,234 👥 │  │892 👥   │  │567 👥   ││
│  │ □ Avanzado     │  │  │[Ver curso]│ │[60% ✓] │  │[Iniciar]││
│  │                │  │  └─────────┘  └─────────┘  └─────────┘│
│  │ Duración       │  │                                       │  │
│  │ □ < 2 horas    │  │  ┌─────────┐  ┌─────────┐  ┌─────────┐│
│  │ ✓ 2-5 horas    │  │  │ ...más cursos...                  ││
│  │ □ > 5 horas    │  │  └─────────┘  └─────────┘  └─────────┘│
│  │                │  │                                       │  │
│  │ [Limpiar]      │  │  [1] 2 3 4 ... 8                     │  │
│  └────────────────┘  └──────────────────────────────────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  📚 Recomendado para ti                                   │  │
│  │  [Curso A]  [Curso B]  [Curso C]                          │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Ver catálogo completo**
```gherkin
DADO que el usuario está autenticado
CUANDO navega a /education/courses
ENTONCES se muestra el catálogo de cursos
Y se muestran 12 cursos por página
Y cada curso muestra: imagen, título, instructor, duración, rating, estudiantes
Y se muestran filtros en sidebar izquierdo
Y se muestra barra de búsqueda
Y se muestra contador "Mostrando X de Y cursos"
```

**Escenario 2: Filtrar por categoría**
```gherkin
DADO que el usuario está en el catálogo
CUANDO selecciona filtro "Análisis Técnico"
ENTONCES solo se muestran cursos de esa categoría
Y el filtro se marca como activo (checkbox marcado)
Y la URL se actualiza a ?category=technical-analysis
Y el contador se actualiza "Mostrando X de Y cursos"
```

**Escenario 3: Filtrar por nivel**
```gherkin
DADO que el usuario está en el catálogo
CUANDO selecciona "Principiante" e "Intermedio"
ENTONCES solo se muestran cursos de esos niveles
Y se pueden combinar con otros filtros activos
Y se muestra badge de nivel en cada curso
```

**Escenario 4: Buscar curso**
```gherkin
DADO que el usuario está en el catálogo
CUANDO escribe "fibonacci" en el buscador
ENTONCES se filtran cursos en tiempo real
Y se muestran solo cursos que contengan "fibonacci" en título o descripción
Y se resalta el término buscado en resultados
Y se muestra "X resultados para 'fibonacci'"
```

**Escenario 5: Sin resultados**
```gherkin
DADO que el usuario aplicó filtros
Y no hay cursos que cumplan los criterios
ENTONCES se muestra mensaje "No se encontraron cursos"
Y se sugiere "Intenta ajustar los filtros"
Y se muestra botón "Limpiar filtros"
```

**Escenario 6: Ver progreso en curso inscrito**
```gherkin
DADO que el usuario ya está inscrito en un curso
CUANDO ve la tarjeta del curso en el catálogo
ENTONCES se muestra barra de progreso (ej: "60% completado")
Y el botón dice "Continuar" en lugar de "Ver curso"
Y al hacer click, navega a la última lección vista
```

**Escenario 7: Ver recomendaciones**
```gherkin
DADO que el usuario tiene cursos en progreso
CUANDO accede al catálogo
ENTONCES se muestra sección "Recomendado para ti"
Y aparecen máximo 6 cursos relacionados
Y se basa en: cursos en progreso, nivel del usuario, categorías de interés
```

**Escenario 8: Ordenar resultados**
```gherkin
DADO que el usuario está viendo el catálogo
CUANDO selecciona ordenar por "Mejor valorados"
ENTONCES los cursos se reordenan de mayor a menor rating
Y la paginación se mantiene
Y los filtros activos se mantienen
```

## Criterios Adicionales

- [ ] Responsive design para móvil y tablet
- [ ] Loading skeleton mientras cargan cursos
- [ ] Infinite scroll opcional (además de paginación)
- [ ] Animaciones suaves al filtrar
- [ ] Badge "Nuevo" para cursos publicados hace < 30 días
- [ ] Badge "Popular" para cursos con > 1000 estudiantes
- [ ] Guardar filtros en localStorage para próxima visita

---

## Tareas Técnicas

**Database:**
- [ ] DB-EDU-001: Verificar schema education.courses
- [ ] DB-EDU-002: Verificar índices en category_id, level, published_at
- [ ] DB-EDU-003: Vista courses_catalog con joins optimizados

**Backend:**
- [ ] BE-EDU-001: Endpoint GET /education/courses (con paginación)
- [ ] BE-EDU-002: Implementar filtros: category, level, duration, search
- [ ] BE-EDU-003: Implementar ordenamiento: recent, popular, rating
- [ ] BE-EDU-004: Endpoint GET /education/categories
- [ ] BE-EDU-005: Implementar CourseService.getCatalog()
- [ ] BE-EDU-006: Implementar lógica de recomendaciones
- [ ] BE-EDU-007: Caché de catálogo en Redis (5 min)

**Frontend:**
- [ ] FE-EDU-001: Crear página CoursesPage.tsx
- [ ] FE-EDU-002: Crear componente CourseCard.tsx
- [ ] FE-EDU-003: Crear componente CourseFilters.tsx
- [ ] FE-EDU-004: Crear componente SearchBar.tsx
- [ ] FE-EDU-005: Crear componente Pagination.tsx
- [ ] FE-EDU-006: Implementar coursesStore (Zustand)
- [ ] FE-EDU-007: Integrar con React Query para caché
- [ ] FE-EDU-008: Skeleton loader para carga

**Tests:**
- [ ] TEST-EDU-001: Test unitario CourseService.getCatalog()
- [ ] TEST-EDU-002: Test integración GET /courses con filtros
- [ ] TEST-EDU-003: Test E2E búsqueda y filtrado

---

## Dependencias

**Depende de:**
- [ ] US-AUTH-001: Sistema de autenticación - Estado: ✅ Completado

**Bloquea:**
- [ ] US-EDU-002: Ver detalle de curso
- [ ] US-EDU-003: Iniciar lección

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | /education/courses | Catálogo con filtros y paginación |
| GET | /education/categories | Listado de categorías |

**Query params para GET /courses:**
```
?page=1
&limit=12
&category=technical-analysis,fundamentals
&level=beginner,intermediate
&search=fibonacci
&sortBy=recent
&sortOrder=desc
```

**Response GET /courses:**
```typescript
{
  courses: [
    {
      id: "uuid-1",
      title: "Fibonacci Retracement Básico",
      slug: "fibonacci-retracement-basico",
      shortDescription: "Aprende a usar Fibonacci...",
      thumbnail: "https://cdn.orbiquant.com/courses/fib.jpg",
      category: {
        id: "cat-1",
        name: "Análisis Técnico",
        slug: "technical-analysis",
        icon: "📊"
      },
      level: "beginner",
      duration: 150, // minutos
      moduleCount: 5,
      lessonCount: 23,
      studentCount: 1234,
      rating: 4.8,
      reviewCount: 89,
      instructor: {
        id: "inst-1",
        name: "Carlos Mendoza",
        avatar: "https://...",
        title: "Senior Trader"
      },
      isPremium: false,
      publishedAt: "2025-11-15T10:00:00Z",
      userProgress: {
        enrolledAt: "2025-12-01T14:30:00Z",
        progressPercent: 60,
        lastAccessedAt: "2025-12-04T18:20:00Z"
      }
    }
    // ... más cursos
  ],
  pagination: {
    page: 1,
    limit: 12,
    total: 47,
    totalPages: 4
  },
  filters: {
    categories: [...],
    levels: ["beginner", "intermediate", "advanced", "expert"]
  }
}
```

**Entidades/Tablas:**
- `education.courses`: Catálogo de cursos
- `education.categories`: Categorías
- `education.course_enrollments`: Inscripciones y progreso
- `education.instructors`: Información de instructores

---

## 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
