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:

```bash
# 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

```sql
-- 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):

```sql
-- 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

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

### Registrar progreso en lección

```sql
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

```sql
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

```sql
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

```sql
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

```sql
-- 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

```sql
-- 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