trading-platform/docs/02-definicion-modulos/OQI-002-education/especificaciones

id	title	type	project	version	updated_date
README	Especificaciones Técnicas - OQI-002 Módulo Educativo	Documentation	trading-platform	1.0.0	2026-01-04

Especificaciones Técnicas - OQI-002 Módulo Educativo

Este directorio contiene las especificaciones técnicas detalladas para el módulo educativo de Trading Platform.

Índice de Especificaciones

ET-EDU-001: Modelo de Datos - Schema Education

Componente: Database Tamaño: ~30KB

Define el schema completo de PostgreSQL para el módulo educativo:

• 11 tablas principales (categories, courses, modules, lessons, enrollments, progress, quizzes, quiz_questions, quiz_attempts, certificates, user_achievements)
• 6 ENUMs personalizados
• Triggers y funciones automáticas
• Vistas optimizadas
• Índices de performance
• Row Level Security (RLS)

Contenido clave:

• Schema education completo con relaciones
• Triggers para auto-actualización de progreso
• Vistas para queries complejas
• Estrategias de indexación

---

ET-EDU-002: API REST - Endpoints del Módulo

Componente: Backend Tamaño: ~42KB

Especificación completa de la API REST con Express.js + TypeScript:

• 10 grupos de endpoints (Categories, Courses, Modules, Lessons, Enrollments, Progress, Quizzes, Certificates, Achievements, Gamification)
• Request/Response con TypeScript interfaces
• Autenticación JWT y autorización por roles
• Rate limiting y paginación
• Validación con Zod
• Manejo de errores estandarizado

Contenido clave:

• ~60 endpoints documentados
• Middleware stack completo
• Códigos de error estandarizados
• Ejemplos de tests con Supertest

---

ET-EDU-003: Componentes Frontend - React + TypeScript

Componente: Frontend Tamaño: ~46KB

Arquitectura frontend con React 18, TypeScript, Zustand y TailwindCSS:

• 7 páginas principales (CoursesPage, CourseDetailPage, LessonPage, ProgressPage, QuizPage, CertificatesPage, AchievementsPage)
• 20+ componentes reutilizables
• Custom hooks para data fetching
• Stores Zustand para state management
• Integración con React Query

Contenido clave:

• Código completo de componentes principales
• Hooks personalizados (useCourses, useEnrollment, useVideoProgress, etc.)
• Stores con Zustand (courseStore, progressStore, gamificationStore)
• Configuración de TailwindCSS

---

ET-EDU-004: Sistema de Streaming de Video

Componente: Backend/Infraestructura Tamaño: ~30KB

Integración de video streaming con Vimeo y AWS S3+CloudFront:

• Configuración de Vimeo Pro/Business
• Upload y gestión de videos
• AWS S3 + CloudFront con signed URLs
• Transcoding HLS con FFmpeg
• Player configuration (Vimeo Player / Video.js)
• Tracking de progreso de video
• Subtítulos WebVTT

Contenido clave:

• Servicios de upload a Vimeo
• Generación de signed URLs en CloudFront
• Pipeline de transcoding HLS multi-bitrate
• Componentes de video player (VimeoPlayer, HLSPlayer)
• Configuración de CloudFront Distribution

---

ET-EDU-005: Motor de Evaluaciones y Quizzes

Componente: Backend/Frontend Tamaño: ~33KB

Sistema completo de evaluaciones con múltiples tipos de preguntas:

• 5 tipos de preguntas (Multiple Choice, True/False, Multiple Select, Fill in the Blank, Code Challenge)
• Algoritmo de scoring con crédito parcial
• Gestión de intentos con límites
• Timer con auto-submit
• Validación de respuestas (incluyendo fuzzy matching)
• Analytics de quizzes

Contenido clave:

• QuizScoringService con algoritmos completos
• QuizAttemptService para flujo de quiz
• Componentes de UI (QuizQuestion, QuizTimer, QuizResults)
• Cálculo de dificultad de preguntas
• Distribución de puntajes

---

ET-EDU-006: Sistema de Gamificación

Componente: Backend/Frontend Tamaño: ~35KB

Sistema de gamificación para aumentar engagement:

• Sistema de XP con múltiples fuentes
• Fórmula de niveles: Level = floor(sqrt(totalXP / 100))
• 15+ achievements predefinidos (common, uncommon, rare, epic, legendary)
• Sistema de rachas diarias con rewards
• Leaderboard global y por períodos
• Notificaciones de logros

Contenido clave:

• XPManagerService con cálculo de niveles
• AchievementManagerService con verificación automática
• StreakManagerService para rachas diarias
• LeaderboardManagerService con caching
• Configuración de achievements y recompensas
• Componentes de UI (XPBar, LevelBadge, AchievementCard)

---

Stack Tecnológico

Backend

• Runtime: Node.js 18+
• Framework: Express.js
• Language: TypeScript 5.3+
• Database: PostgreSQL 15+
• ORM: Prisma / TypeORM (opcional)
• Validation: Zod
• Auth: JWT (jsonwebtoken)
• Caching: Redis 4+
• Video Processing: FFmpeg

Frontend

• Framework: React 18
• Language: TypeScript 5.3+
• State Management: Zustand 4+
• Data Fetching: TanStack React Query 5+
• Styling: TailwindCSS 3+
• Routing: React Router 6+
• Video Player: Vimeo Player / Video.js
• Forms: React Hook Form + Zod

Infraestructura

• Video CDN: Vimeo Pro/Business o AWS S3 + CloudFront
• Object Storage: AWS S3
• Cache: Redis
• Monitoring: (TBD)

---

Convenciones de Nomenclatura

Archivos de Especificación

ET-EDU-XXX-{nombre}.md

• ET: Especificación Técnica
• EDU: Módulo Education
• XXX: Número secuencial (001-999)
• {nombre}: Identificador descriptivo

Versiones

Todas las especificaciones están en versión 1.0.0 (2025-12-05)

---

Cómo Usar Este Documento

1. Para Desarrolladores Backend:

   • Leer ET-EDU-001 (Database) y ET-EDU-002 (API)
   • Referencias: ET-EDU-004 (Video), ET-EDU-005 (Quizzes), ET-EDU-006 (Gamification)

2. Para Desarrolladores Frontend:

   • Leer ET-EDU-002 (API) y ET-EDU-003 (Frontend)
   • Referencias: ET-EDU-004 (Video Player), ET-EDU-005 (Quiz UI), ET-EDU-006 (Gamification UI)

3. Para DevOps:

   • Leer ET-EDU-001 (Database setup)
   • Leer ET-EDU-004 (Video Infrastructure)
   • Variables de entorno en cada especificación

4. Para Product Managers:

   • Todas las especificaciones contienen descripción y arquitectura
   • Ver sección de "Interfaces/Tipos" para data models

---

Estado de Implementación

Especificación	Estado	Prioridad	Notas
ET-EDU-001	Pendiente	Alta	Base de datos requerida primero
ET-EDU-002	Pendiente	Alta	Depende de ET-EDU-001
ET-EDU-003	Pendiente	Alta	Depende de ET-EDU-002
ET-EDU-004	Pendiente	Media	Puede iniciar en paralelo
ET-EDU-005	Pendiente	Media	Depende de ET-EDU-001, ET-EDU-002
ET-EDU-006	Pendiente	Baja	Feature post-MVP

---

Próximos Pasos

1. Revisión Técnica: Validar especificaciones con el equipo de desarrollo
2. Priorización: Definir orden de implementación
3. Estimación: Calcular esfuerzo de desarrollo por especificación
4. Asignación: Distribuir tareas entre el equipo
5. Implementación: Comenzar desarrollo siguiendo las especificaciones

---

Contacto

Para preguntas o aclaraciones sobre estas especificaciones, contactar al Requirements Analyst del proyecto.

---

Última actualización: 2025-12-05 Versión del documento: 1.0.0