trading-platform-database-v2/ddl/schemas/education/README.md

Schema: education

Proyecto: Trading Platform (Trading Platform) Módulo: OQI-002 - Education Especificación: ET-EDU-001-database.md PostgreSQL: 15+

---

Descripción

Schema completo para el módulo educativo de Trading Platform, implementando:

• Gestión de cursos, módulos y lecciones
• Sistema de enrollments y progreso de estudiantes
• Quizzes y evaluaciones
• Certificados de finalización
• Sistema de gamificación (XP, niveles, streaks, achievements)
• Reviews de cursos
• Activity logging

---

Estructura de Archivos

education/
├── 00-enums.sql                                    # Tipos ENUM
├── tables/
│   ├── 01-categories.sql                           # Categorías de cursos
│   ├── 02-courses.sql                              # Cursos
│   ├── 03-modules.sql                              # Módulos del curso
│   ├── 04-lessons.sql                              # Lecciones
│   ├── 05-enrollments.sql                          # Inscripciones de usuarios
│   ├── 06-progress.sql                             # Progreso en lecciones
│   ├── 07-quizzes.sql                              # Quizzes/evaluaciones
│   ├── 08-quiz_questions.sql                       # Preguntas de quiz
│   ├── 09-quiz_attempts.sql                        # Intentos de quiz
│   ├── 10-certificates.sql                         # Certificados
│   ├── 11-user_achievements.sql                    # Logros/badges
│   ├── 12-user_gamification_profile.sql            # Perfil de gamificación
│   ├── 13-user_activity_log.sql                    # Log de actividades
│   └── 14-course_reviews.sql                       # Reviews de cursos
└── functions/
    ├── 01-update_updated_at.sql                    # Trigger updated_at
    ├── 02-update_enrollment_progress.sql           # Actualizar progreso
    ├── 03-auto_complete_enrollment.sql             # Auto-completar enrollment
    ├── 04-generate_certificate.sql                 # Generar certificados
    ├── 05-update_course_stats.sql                  # Actualizar estadísticas
    ├── 06-update_enrollment_count.sql              # Contador de enrollments
    ├── 07-update_gamification_profile.sql          # Sistema de gamificación
    └── 08-views.sql                                # Vistas útiles

---

Orden de Ejecución

Para crear el schema completo, ejecutar en este orden:

# 1. ENUMs
psql -f 00-enums.sql

# 2. Tablas (en orden de dependencias)
psql -f tables/01-categories.sql
psql -f tables/02-courses.sql
psql -f tables/03-modules.sql
psql -f tables/04-lessons.sql
psql -f tables/05-enrollments.sql
psql -f tables/06-progress.sql
psql -f tables/07-quizzes.sql
psql -f tables/08-quiz_questions.sql
psql -f tables/09-quiz_attempts.sql
psql -f tables/10-certificates.sql
psql -f tables/11-user_achievements.sql
psql -f tables/12-user_gamification_profile.sql
psql -f tables/13-user_activity_log.sql
psql -f tables/14-course_reviews.sql

# 3. Funciones y Triggers
psql -f functions/01-update_updated_at.sql
psql -f functions/02-update_enrollment_progress.sql
psql -f functions/03-auto_complete_enrollment.sql
psql -f functions/04-generate_certificate.sql
psql -f functions/05-update_course_stats.sql
psql -f functions/06-update_enrollment_count.sql
psql -f functions/07-update_gamification_profile.sql
psql -f functions/08-views.sql

---

Tablas

Principales

Tabla	Descripción
categories	Categorías de cursos con soporte para jerarquía
courses	Cursos del módulo educativo
modules	Módulos que agrupan lecciones
lessons	Lecciones individuales (video, artículo, interactivo)
enrollments	Inscripciones de usuarios a cursos
progress	Progreso del usuario en cada lección

Evaluación

Tabla	Descripción
quizzes	Quizzes/evaluaciones
quiz_questions	Preguntas de los quizzes
quiz_attempts	Intentos de usuarios en quizzes

Logros

Tabla	Descripción
certificates	Certificados de finalización
user_achievements	Logros/badges obtenidos

Gamificación

Tabla	Descripción
user_gamification_profile	XP, niveles, streaks, estadísticas
user_activity_log	Log de todas las actividades
course_reviews	Reviews y calificaciones de cursos

---

ENUMs

• difficulty_level: beginner, intermediate, advanced, expert
• course_status: draft, published, archived
• enrollment_status: active, completed, expired, cancelled
• lesson_content_type: video, article, interactive, quiz
• question_type: multiple_choice, true_false, multiple_select, fill_blank, code_challenge
• achievement_type: course_completion, quiz_perfect_score, streak_milestone, level_up, special_event

---

Funciones Principales

Gamificación

-- Actualizar XP del usuario
SELECT education.update_user_xp(
  'user-uuid',  -- user_id
  100           -- xp_to_add
);

-- Actualizar streak del usuario
SELECT education.update_user_streak('user-uuid');

Triggers Automáticos

• updated_at: Se actualiza automáticamente en todas las tablas
• update_enrollment_progress(): Calcula progreso al completar lecciones
• auto_complete_enrollment(): Completa enrollment al alcanzar 100%
• generate_certificate_number(): Genera número único de certificado
• update_course_rating_stats(): Actualiza rating promedio del curso
• update_enrollment_count(): Actualiza contador de enrollments
• update_streak_on_activity(): Actualiza streak en cada actividad

---

Vistas

Vista	Descripción
v_courses_with_stats	Cursos con estadísticas agregadas
v_user_course_progress	Progreso del usuario por curso
v_leaderboard_weekly	Top 100 usuarios por XP semanal
v_leaderboard_monthly	Top 100 usuarios por XP mensual
v_leaderboard_alltime	Top 100 usuarios por XP total
v_user_statistics	Estadísticas completas del usuario
v_popular_courses	Top 50 cursos más populares

---

Dependencias

Schemas externos

• auth.users - Tabla de usuarios (requerida)

Extensions

• gen_random_uuid() - Built-in en PostgreSQL 13+

---

Políticas de Seguridad (RLS)

Para habilitar Row Level Security (implementar según necesidad):

-- Habilitar RLS
ALTER TABLE education.enrollments ENABLE ROW LEVEL SECURITY;
ALTER TABLE education.progress ENABLE ROW LEVEL SECURITY;
ALTER TABLE education.quiz_attempts ENABLE ROW LEVEL SECURITY;
ALTER TABLE education.certificates ENABLE ROW LEVEL SECURITY;

-- Política: usuarios solo ven sus propios datos
CREATE POLICY user_own_data ON education.enrollments
  FOR ALL
  USING (user_id = current_setting('app.user_id')::UUID);

---

Ejemplos de Uso

Enrollar usuario a un curso

INSERT INTO education.enrollments (user_id, course_id)
VALUES ('user-uuid', 'course-uuid')
RETURNING *;

Registrar progreso en lección

INSERT INTO education.progress (
  user_id,
  lesson_id,
  enrollment_id,
  is_completed,
  watch_percentage
) VALUES (
  'user-uuid',
  'lesson-uuid',
  'enrollment-uuid',
  true,
  100.00
);
-- Esto automáticamente actualizará el enrollment progress

Completar quiz

INSERT INTO education.quiz_attempts (
  user_id,
  quiz_id,
  enrollment_id,
  is_completed,
  is_passed,
  user_answers,
  score_percentage,
  xp_earned
) VALUES (
  'user-uuid',
  'quiz-uuid',
  'enrollment-uuid',
  true,
  true,
  '[{"questionId": "q1", "answer": "A", "isCorrect": true}]'::jsonb,
  85.00,
  50
);

Emitir certificado

INSERT INTO education.certificates (
  user_id,
  course_id,
  enrollment_id,
  user_name,
  course_title,
  completion_date,
  final_score
) VALUES (
  'user-uuid',
  'course-uuid',
  'enrollment-uuid',
  'John Doe',
  'Introducción al Trading',
  CURRENT_DATE,
  92.50
);
-- El número de certificado y código de verificación se generan automáticamente

Agregar review a curso

INSERT INTO education.course_reviews (
  user_id,
  course_id,
  enrollment_id,
  rating,
  title,
  content
) VALUES (
  'user-uuid',
  'course-uuid',
  'enrollment-uuid',
  5,
  'Excelente curso',
  'Muy bien explicado y con ejemplos prácticos'
);

---

Notas Importantes

1. Referencias: Todas las FKs a usuarios usan auth.users(id)
2. Cascadas: Las eliminaciones en CASCADE están definidas donde corresponde
3. Índices: Creados para optimizar queries frecuentes
4. Constraints: Validaciones de lógica de negocio implementadas
5. JSONB: Usado para metadata flexible (attachments, user_answers, etc.)
6. Denormalización: Algunas estadísticas están denormalizadas para performance

---

Mantenimiento

Resetear XP semanal/mensual

-- Resetear XP semanal (ejecutar cada lunes)
UPDATE education.user_gamification_profile SET weekly_xp = 0;

-- Resetear XP mensual (ejecutar el 1ro de cada mes)
UPDATE education.user_gamification_profile SET monthly_xp = 0;

Recalcular estadísticas de curso

-- Recalcular total de módulos y lecciones
UPDATE education.courses c
SET
  total_modules = (SELECT COUNT(*) FROM education.modules WHERE course_id = c.id),
  total_lessons = (
    SELECT COUNT(*)
    FROM education.lessons l
    JOIN education.modules m ON l.module_id = m.id
    WHERE m.course_id = c.id
  );

---

Versión

Versión: 1.0.0 Última actualización: 2025-12-06