trading-platform/docs/02-definicion-modulos/OQI-002-education/historias-usuario/US-EDU-001-ver-catalogo.md

id	title	type	status	priority	epic	story_points	created_date	updated_date
US-EDU-001	Ver Catalogo de Cursos	User Story	Done	Alta	OQI-002	3	2025-12-05	2026-01-04

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

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

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

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

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

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

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

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

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:

{
  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)

• Historia claramente escrita
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• Sin bloqueadores
• Diseño/mockup disponible
• 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