trading-platform/docs/02-definicion-modulos/OQI-002-education/historias-usuario/US-EDU-003-iniciar-leccion.md

id	title	type	status	priority	epic	story_points	created_date	updated_date
US-EDU-003	Iniciar Leccion	User Story	Done	Alta	OQI-002	3	2025-12-05	2026-01-04

US-EDU-003: Iniciar Lección

Metadata

Campo	Valor
ID	US-EDU-003
É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 inscrito en un curso, quiero acceder y comenzar una lección específica, para consumir el contenido educativo y avanzar en mi aprendizaje.

Descripción Detallada

El usuario debe poder hacer click en una lección desde el temario del curso y acceder a la página de reproducción/visualización de la lección. El sistema debe validar que el usuario está inscrito, verificar si la lección está desbloqueada (según orden secuencial si aplica), cargar el contenido apropiado según el tipo de lección, y registrar que el usuario inició la lección.

Mockups/Wireframes

┌─────────────────────────────────────────────────────────────────┐
│  ← Volver al curso                              [≡ Temario]  👤 │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Módulo 2: Niveles de Retroceso                                │
│  Lección 1/4: Niveles principales (38.2%, 50%, 61.8%)          │
│  Progreso del curso: ████████░░░░░░░░ 45%                      │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                                                            │ │
│  │               [REPRODUCTOR DE VIDEO]                       │ │
│  │                                                            │ │
│  │                      ▶ PLAY                                │ │
│  │                                                            │ │
│  │  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  12:15              │ │
│  │  ⏮ ⏸ ⏭  🔊────  ⚙ 1x  CC  ⛶                            │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                  │
│  ┌─ PESTAÑAS ────────────────────────────────────────────────┐  │
│  │ [Descripción] [Recursos] [Mis Notas] [Q&A]                │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
│  📝 DESCRIPCIÓN                                                 │
│  En esta lección aprenderás los tres niveles principales de     │
│  Fibonacci: 38.2%, 50% y 61.8%. Veremos cómo identificarlos...  │
│                                                                  │
│  📥 RECURSOS (2)                                                │
│  • Plantilla de Fibonacci.xlsx (45 KB) [Descargar]             │
│  • Cheatsheet de niveles.pdf (120 KB) [Descargar]              │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  [← Anterior: Historia y fundamentos]                      │ │
│  │  [Siguiente: Cómo dibujar Fibonacci →]                     │ │
│  │  [✓ Marcar como completada]                                │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

[SIDEBAR TEMARIO - Desplegable]
┌────────────────────────┐
│ TEMARIO                │
│ ✓ Módulo 1 (4/4) ✓     │
│ ▼ Módulo 2 (1/4)       │
│   ✓ 1. Niveles princ.  │ ← Lección actual
│   ○ 2. Dibujar Fib.    │
│   🔒 3. Práctica        │
│   🔒 4. Quiz            │
│ 🔒 Módulo 3            │
│ 🔒 Módulo 4            │
│ 🔒 Módulo 5            │
└────────────────────────┘

---

Criterios de Aceptación

Escenario 1: Iniciar lección desbloqueada

DADO que el usuario está inscrito en el curso
Y la lección está desbloqueada
CUANDO hace click en la lección desde el temario
ENTONCES se navega a /education/courses/:slug/lessons/:lessonSlug
Y se carga el contenido de la lección
Y se registra en backend que el usuario inició la lección
Y se actualiza "última lección accedida"
Y se muestra sidebar con temario completo

Escenario 2: Intentar acceder a lección bloqueada

DADO que el curso requiere orden secuencial
Y el usuario NO ha completado la lección anterior
CUANDO intenta acceder a una lección bloqueada
ENTONCES se muestra modal "Debes completar lecciones anteriores"
Y se sugiere la última lección disponible
Y NO se carga el contenido

Escenario 3: Lección de video carga posición guardada

DADO que el usuario vio 5:30 de un video de 12:15
Y cerró la lección sin terminar
CUANDO vuelve a abrir la lección
ENTONCES el video se posiciona en 5:30
Y se muestra toast "Continuando desde 5:30"
Y se puede resetear posición si el usuario lo desea

Escenario 4: Usuario no inscrito intenta acceder

DADO que el usuario NO está inscrito en el curso
CUANDO intenta acceder directamente a una lección
ENTONCES se redirige a la página del curso
Y se muestra mensaje "Inscríbete para acceder a este curso"
Y se muestra botón "Inscribirse"

Escenario 5: Ver recursos de la lección

DADO que la lección tiene recursos descargables
CUANDO el usuario accede a la pestaña "Recursos"
ENTONCES se muestran todos los archivos disponibles
Y se muestra: nombre, tipo, tamaño
Y puede descargar cada archivo con un click
Y se registra la descarga en analytics

Escenario 6: Tomar notas durante lección

DADO que el usuario está en una lección
CUANDO accede a la pestaña "Mis Notas"
Y escribe texto en el editor
ENTONCES las notas se guardan automáticamente cada 2s
Y se muestra indicador "Guardado" cuando se persiste
Y para videos se guarda el timestamp actual

Escenario 7: Navegar entre lecciones

DADO que el usuario está en una lección
Y existe una lección siguiente
CUANDO hace click en "Siguiente"
ENTONCES navega a la siguiente lección del módulo
Y se carga el nuevo contenido
Y se actualiza el sidebar

Escenario 8: Marcar lección como completada

DADO que el usuario vio la lección completa
CUANDO hace click en "Marcar como completada"
ENTONCES se actualiza el progreso en backend
Y aparece checkmark ✓ en el sidebar
Y se actualiza la barra de progreso del curso
Y si es secuencial, se desbloquea siguiente lección

Criterios Adicionales

• Auto-save de progreso de video cada 10s
• Atajos de teclado: Espacio=play/pause, →=+10s, ←=-10s
• Picture-in-Picture para videos
• Modo cine (ocultar sidebar)
• Velocidad de reproducción: 0.5x, 0.75x, 1x, 1.25x, 1.5x, 2x
• Subtítulos si están disponibles
• Analytics: tiempo en lección, pausas, rewinds

---

Tareas Técnicas

Database:

• DB-EDU-007: Tabla user_lesson_progress (started_at, completed_at, last_position)
• DB-EDU-008: Tabla user_notes (lesson_id, content, timestamp)
• DB-EDU-009: Índice en user_id + lesson_id para queries rápidas

Backend:

• BE-EDU-014: Endpoint GET /education/courses/:id/lessons/:lessonId
• BE-EDU-015: Validar inscripción y acceso a lección
• BE-EDU-016: Endpoint POST /education/lessons/:id/progress (guardar posición)
• BE-EDU-017: Endpoint POST /education/lessons/:id/complete
• BE-EDU-018: Endpoint GET/POST /education/lessons/:id/notes
• BE-EDU-019: Endpoint GET /education/lessons/:id/resources/:resourceId
• BE-EDU-020: Implementar signed URLs para videos privados
• BE-EDU-021: Verificar orden secuencial si aplica

Frontend:

• FE-EDU-017: Crear LessonPlayerPage.tsx
• FE-EDU-018: Crear componente VideoPlayer.tsx
• FE-EDU-019: Crear componente LessonSidebar.tsx
• FE-EDU-020: Crear componente NotesEditor.tsx
• FE-EDU-021: Crear componente ResourcesList.tsx
• FE-EDU-022: Implementar auto-save de posición (cada 10s)
• FE-EDU-023: Implementar lessonStore (Zustand)
• FE-EDU-024: Navegación con teclas de flecha
• FE-EDU-025: Toast notifications para acciones

Tests:

• TEST-EDU-007: Test validación de acceso a lección
• TEST-EDU-008: Test bloqueo de lección secuencial
• TEST-EDU-009: Test guardar y restaurar posición de video
• TEST-EDU-010: Test E2E iniciar lección y marcar completada

---

Dependencias

Depende de:

• US-EDU-002: Ver detalle de curso - Estado: Pendiente
• US-AUTH-001: Autenticación - Estado: ✅ Completado

Bloquea:

• US-EDU-004: Ver video completo
• US-EDU-005: Completar lección
• US-EDU-007: Ver progreso

---

Notas Técnicas

Endpoints involucrados:

Método	Endpoint	Descripción
GET	/education/courses/:courseId/lessons/:lessonId	Obtener lección
POST	/education/lessons/:id/progress	Guardar posición
POST	/education/lessons/:id/complete	Marcar completada
GET	/education/lessons/:id/notes	Obtener notas
POST	/education/lessons/:id/notes	Crear/actualizar notas

Response GET /lessons/🆔

{
  lesson: {
    id: "les-5",
    courseId: "course-1",
    moduleId: "mod-2",
    title: "Niveles principales: 38.2%, 50%, 61.8%",
    slug: "niveles-principales",
    description: "En esta lección aprenderás...",
    type: "video",
    duration: 12.25, // minutos
    order: 1,
    isFree: false,

    // Video específico
    videoUrl: "https://vimeo.com/signed-url-12345",
    videoProvider: "vimeo",
    subtitles: [
      { language: "es", url: "..." },
      { language: "en", url: "..." }
    ],

    resources: [
      {
        id: "res-1",
        name: "Plantilla de Fibonacci.xlsx",
        type: "application/vnd.ms-excel",
        size: 45120,
        url: "https://s3.../signed-url"
      }
    ],

    userProgress: {
      startedAt: "2025-12-04T10:30:00Z",
      completedAt: null,
      lastPosition: 5.5, // minutos
      timeSpent: 320, // segundos
      isCompleted: false
    },

    navigation: {
      previous: {
        id: "les-4",
        title: "Historia y fundamentos",
        slug: "historia-fundamentos"
      },
      next: {
        id: "les-6",
        title: "Cómo dibujar Fibonacci",
        slug: "como-dibujar-fibonacci",
        isLocked: false
      }
    },

    module: {
      id: "mod-2",
      title: "Niveles de Retroceso",
      lessonsCompleted: 1,
      totalLessons: 4
    },

    course: {
      id: "course-1",
      title: "Fibonacci Retracement Básico",
      slug: "fibonacci-retracement-basico",
      progressPercent: 45,
      isSequential: true
    }
  }
}

Validaciones backend:

1. Usuario autenticado
2. Usuario inscrito en el curso
3. Si curso es secuencial, validar lecciones anteriores completadas
4. Si curso es premium, validar suscripción activa

Entidades/Tablas:

• education.lessons
• education.user_lesson_progress
• education.user_notes
• education.lesson_resources

---

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