---
id: "README"
title: "Especificaciones Técnicas - OQI-002 Módulo Educativo"
type: "Documentation"
project: "trading-platform"
version: "1.0.0"
updated_date: "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](./ET-EDU-001-database.md)
**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](./ET-EDU-002-api.md)
**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](./ET-EDU-003-frontend.md)
**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](./ET-EDU-004-video.md)
**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](./ET-EDU-005-quizzes.md)
**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](./ET-EDU-006-gamification.md)
**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