workspace/projects/gamilit/docs/01-fase-alcance-inicial/EAI-002-actividades/implementacion/TRACEABILITY.yml

# TRACEABILITY.yml - EAI-002: Actividades

epic_code: EAI-002
epic_name: Actividades y Contenido Educativo
phase: 1
budget_mxn: 22000
story_points: 45
status: completed

documentation:
  requirements:
    - {id: RF-EDU-001, file: requerimientos/RF-EDU-001-mecanicas-ejercicios.md}
    - {id: RF-EDU-002, file: requerimientos/RF-EDU-002-niveles-dificultad.md}
    - {id: RF-EDU-003, file: requerimientos/RF-EDU-003-taxonomia-bloom.md}

  specifications:
    - id: ET-EDU-001
      file: especificaciones/ET-EDU-001-mecanicas-ejercicios.md
      rf: RF-EDU-001
      title: Implementación de Mecánicas de Ejercicios
      status: implemented
      version: "2.0"
      last_updated: "2025-11-11"
      changes: "Reconciliación exercise_mechanic ↔ exercise_type. Sistema dual implementado con tabla de mapeo pedagógico. Sincronizado con DDL real (35 exercise_types). Ver ADR-008."

    - id: ET-EDU-002
      file: especificaciones/ET-EDU-002-niveles-dificultad.md
      rf: RF-EDU-002
      title: Sistema de Niveles de Dificultad CEFR
      status: implemented
      version: "2.0"
      last_updated: "2025-11-11"
      changes: "Migración completa a estándar CEFR (A1-C2+). 8 niveles con criterios específicos y sistema de progresión."

    - id: ET-EDU-003
      file: especificaciones/ET-EDU-003-taxonomia-bloom.md
      rf: RF-EDU-003
      title: Implementación Taxonomía de Bloom
      status: implemented

implementation:
  database:
    schemas: [educational_content, progress_tracking]

    enums:
      - name: difficulty_level
        schema: educational_content
        file: apps/database/ddl/schemas/educational_content/enums/difficulty_level.sql
        lines: "14-23"
        migrated_from: apps/database/ddl/00-prerequisites.sql
        migration_date: "2025-11-11"
        migration_reason: "Política de Carga Limpia - Evitar duplicación de ENUMs en prerequisites"
        values: [beginner, elementary, pre_intermediate, intermediate, upper_intermediate, advanced, proficient, native]
        rf: RF-EDU-002
        version: "2.0"
        last_updated: "2025-11-11"
        note: "Migrado a estándar CEFR internacional (A1-C2+). Breaking change desde valores genéricos."

    tables:
      # Tablas existentes
      - name: exercises
        schema: educational_content
        description: Ejercicios del sistema
        rf: RF-EDU-001
        columns_using_enums:
          - column: difficulty_level
            enum: difficulty_level

      - name: exercise_attempts
        schema: progress_tracking
        description: Intentos de ejercicios por usuario
        rf: RF-EDU-001

      - name: modules
        schema: educational_content
        description: Módulos educativos
        rf: RF-EDU-001

      - name: module_progress
        schema: progress_tracking
        description: Progreso de módulos por usuario
        rf: RF-EDU-001

      # Tablas nuevas GAP-3 (2025-11-11)
      - name: difficulty_criteria
        schema: educational_content
        file: apps/database/ddl/schemas/educational_content/tables/20-difficulty_criteria.sql
        lines: 156
        description: Criterios y configuración para cada nivel CEFR (vocab, tiempo, recompensas, promoción)
        rf: RF-EDU-002
        created: "2025-11-11"
        columns_using_enums:
          - column: level
            enum: difficulty_level
        note: "Define criterios específicos: vocab_range, time_multiplier, base_xp, promotion criteria"

      # Tabla nueva Sistema Dual (2025-11-11) - DB-112
      - name: exercise_mechanic_mapping
        schema: educational_content
        file: apps/database/ddl/schemas/educational_content/tables/21-exercise_mechanic_mapping.sql
        lines: "~120"
        description: "Mapeo N:M entre categorías pedagógicas universales (31 subcategorías) e implementaciones GAMILIT (35 exercise_types)"
        rf: RF-EDU-001
        created: "2025-11-11"
        columns_using_enums:
          - column: exercise_type
            enum: exercise_type
          - column: cefr_level
            enum: difficulty_level
        note: "Sistema Dual: Reconcilia clasificación pedagógica con implementación GAMILIT. Ver ADR-008. 13 GAPs pedagógicos identificados como roadmap."
        indexes:
          - idx_mechanic_mapping_category
          - idx_mechanic_mapping_subcategory
          - idx_mechanic_mapping_exercise_type
          - idx_mechanic_mapping_bloom
          - idx_mechanic_mapping_tags_gin (GIN)

      - name: user_difficulty_progress
        schema: progress_tracking
        file: apps/database/ddl/schemas/progress_tracking/tables/15-user_difficulty_progress.sql
        lines: 178
        description: Progreso del usuario por nivel CEFR con métricas calculadas (success_rate, avg_time)
        rf: RF-EDU-002
        created: "2025-11-11"
        columns_using_enums:
          - column: difficulty_level
            enum: difficulty_level
        note: "GENERATED COLUMNS para success_rate y avg_time_per_exercise. Flag is_ready_for_promotion"

      - name: user_current_level
        schema: progress_tracking
        file: apps/database/ddl/schemas/progress_tracking/tables/16-user_current_level.sql
        lines: 123
        description: Nivel actual del usuario y zona de desarrollo próximo (ZDP)
        rf: RF-EDU-002
        created: "2025-11-11"
        columns_using_enums:
          - column: current_level
            enum: difficulty_level
          - column: previous_level
            enum: difficulty_level
          - column: max_allowed_level
            enum: difficulty_level
        note: "Denormalizado para performance. Incluye placement_test_completed tracking"

    functions:
      - name: check_difficulty_promotion_eligibility
        schema: progress_tracking
        file: apps/database/ddl/schemas/progress_tracking/functions/check_difficulty_promotion_eligibility.sql
        lines: 81
        description: Verifica si usuario cumple criterios para promoción de nivel CEFR
        rf: RF-EDU-002
        created: "2025-11-11"
        returns: "BOOLEAN"
        security: "SECURITY DEFINER"
        note: "Evalúa: min_exercises, success_rate, avg_time vs otros usuarios"

      - name: promote_user_difficulty_level
        schema: progress_tracking
        file: apps/database/ddl/schemas/progress_tracking/functions/promote_user_difficulty_level.sql
        lines: 72
        description: Promociona usuario al siguiente nivel CEFR y actualiza ZDP
        rf: RF-EDU-002
        created: "2025-11-11"
        returns: "VOID"
        security: "SECURITY DEFINER"
        parameters:
          - p_user_id: UUID
          - p_from_level: educational_content.difficulty_level
          - p_to_level: educational_content.difficulty_level

      - name: update_difficulty_progress
        schema: progress_tracking
        file: apps/database/ddl/schemas/progress_tracking/functions/update_difficulty_progress.sql
        lines: 85
        description: Actualiza progreso tras completar ejercicio y verifica elegibilidad automáticamente
        rf: RF-EDU-002
        created: "2025-11-11"
        returns: "VOID"
        security: "SECURITY DEFINER"
        parameters:
          - p_user_id: UUID
          - p_difficulty_level: educational_content.difficulty_level
          - p_is_completed: BOOLEAN
          - p_is_correct_first_attempt: BOOLEAN
          - p_time_spent_seconds: INT

    seeds:
      # Seeds PROD - Módulos y Ejercicios (DB-095, DB-096)
      - name: 01-modules
        schema: educational_content
        file: apps/database/seeds/prod/educational_content/01-modules.sql
        lines: 205
        description: "5 módulos educativos (Historiador Detective, Detective Textual, Científico, Creador Digital, Video Carta)"
        rf: RF-EDU-001
        created: "2024-09-15"
        updated: "2025-11-11"
        records: 5
        note: "Módulos principales del sistema educativo GAMILIT"

      - name: 02-exercises-module1
        schema: educational_content
        file: apps/database/seeds/prod/educational_content/02-exercises-module1.sql
        lines: 687
        description: "5 ejercicios Module 1 - Historiador Detective (mecánicas: crucigrama, emparejamiento, sopa de letras, etc.)"
        rf: RF-EDU-001
        created: "2025-11-11"
        records: 5
        note: "Validado 2025-11-23 post-ADR-010. Siempre fueron 5 ejercicios correctos según DocumentoDeDiseño v6.4"

      - name: 03-exercises-module2
        schema: educational_content
        file: apps/database/seeds/prod/educational_content/03-exercises-module2.sql
        lines: 571
        description: "5 ejercicios Module 2 - Detective Textual (análisis y comprensión de textos)"
        rf: RF-EDU-001
        created: "2025-11-11"
        records: 5
        note: "JSONB completo. Migrado DEV → PROD"

      - name: 04-exercises-module3
        schema: educational_content
        file: apps/database/seeds/prod/educational_content/04-exercises-module3.sql
        lines: 683
        description: "5 ejercicios Module 3 - Científico Pensamiento Crítico (evaluación y análisis)"
        rf: RF-EDU-001
        created: "2025-11-11"
        updated: "2025-11-23"
        records: 5
        note: "COMPLETADO 2025-11-23: Ejercicio 3.5 'Matriz de Perspectivas' agregado según ADR-010"

      - name: 05-exercises-module4
        schema: educational_content
        file: apps/database/seeds/prod/educational_content/05-exercises-module4.sql
        lines: 570
        description: "5 ejercicios Module 4 - Creador Digital (producción multimedia)"
        rf: RF-EDU-001
        created: "2025-11-11"
        records: 5
        note: "JSONB completo. Migrado DEV → PROD"

      - name: 06-exercises-module5
        schema: educational_content
        file: apps/database/seeds/prod/educational_content/06-exercises-module5.sql
        lines: 835
        description: "3 ejercicios Module 5 - Video Carta (producción creativa con templates, prompts, rúbricas)"
        rf: RF-EDU-001
        created: "2025-11-11"
        updated: "2025-11-23"
        records: 3
        note: "CORREGIDO 2025-11-23: Son 3 opciones (5A, 5B, 5C) según DocumentoDeDiseño v6.4. JSONB expandido +861% (97→835 líneas). 3 templates, 5 prompts por ejercicio, rúbricas completas"

      - name: 08-difficulty_criteria
        schema: educational_content
        file: apps/database/seeds/prod/educational_content/08-difficulty_criteria.sql
        lines: 245
        description: "Configuración de 8 niveles CEFR con criterios completos (A1-Nativo)"
        rf: RF-EDU-002
        created: "2025-11-11"
        records: 8
        note: "Define vocab_range, time_multiplier, base_xp/coins, promotion_criteria por nivel"

  backend:
    module: educational
    path: apps/backend/src/modules/educational/
    key_services:
      - exercise.service.ts
      - module.service.ts
      - progress.service.ts

    enums:
      - name: DifficultyLevelEnum
        path: apps/backend/src/shared/constants/enums.constants.ts
        lines: "200-210"
        rf: RF-EDU-002
        version: "2.0"
        last_updated: "2025-11-11"
        sync_with_db: educational_content.difficulty_level
        note: "Migrado completamente a CEFR. Breaking change desde valores genéricos."
        values:
          - BEGINNER: 'beginner'        # A1
          - ELEMENTARY: 'elementary'    # A2
          - PRE_INTERMEDIATE: 'pre_intermediate'  # B1
          - INTERMEDIATE: 'intermediate'          # B2
          - UPPER_INTERMEDIATE: 'upper_intermediate'  # C1
          - ADVANCED: 'advanced'        # C2
          - PROFICIENT: 'proficient'    # C2+
          - NATIVE: 'native'            # Nativo

  frontend:
    feature: student/learning
    path: apps/frontend/src/features/student/learning/
    key_components:
      - ExerciseRenderer.tsx
      - MultipleChoice.tsx
      - TrueFalse.tsx
      - DragAndDrop.tsx

# ============================================================================
# TESTING
# ============================================================================

testing:
  coverage:
    overall: 20%  # REAL (actualizado 2025-11-23)
    backend: 30%  # REAL (actualizado 2025-11-23)
    frontend: 10%  # REAL (actualizado 2025-11-23)
    database: 0%  # REAL (actualizado 2025-11-23)
    meta_original: 88%  # Estimación inicial del proyecto
    gap_actual: -68%  # Diferencia entre meta y realidad
    ultima_medicion: "2025-11-23"
    nota: |
      Coverage REAL actualizado por Architecture-Analyst (2025-11-23).
      Valores previos eran ESTIMACIONES optimistas del inicio del proyecto.
      Módulo actividades tiene tests parciales en exercise.service y module.service.
      Gap actual requiere plan de mejora (ver orchestration/roadmap/ROADMAP-TEST-COVERAGE.md).
      Próxima medición: Mensual (Q1 2026).      

# ============================================================================
# MÉTRICAS Y RESULTADO
# ============================================================================

metrics:
  deliverables:
    database_objects: 12
    database_objects_note: "4 tablas existentes + 4 tablas nuevas (3 CEFR + 1 Sistema Dual) + 3 funciones CEFR + 1 seed CEFR"
    seeds_production: 7
    seeds_production_note: "1 módulos + 5 exercises (modules 1-5) + 1 difficulty_criteria. Total: 23 ejercicios educativos"
    exercises_total: 23
    exercises_by_module:
      - module: "Module 1 - Historiador Detective"
        exercises: 5
        mechanics: "Crucigrama, Línea Tiempo, Completar Espacios, Verdadero/Falso, Sopa Letras"
      - module: "Module 2 - Detective Textual"
        exercises: 5
        mechanics: "Análisis de textos y comprensión"
      - module: "Module 3 - Científico Pensamiento Crítico"
        exercises: 5
        mechanics: "Tribunal, Debate, Análisis Fuentes, Podcast, Matriz Perspectivas"
      - module: "Module 4 - Creador Digital"
        exercises: 5
        mechanics: "Placeholders con is_active=false"
      - module: "Module 5 - Video Carta"
        exercises: 3
        mechanics: "Placeholders con is_active=false (3 opciones: Diario, Cómic, Cápsula)"
    backend_files: 15
    frontend_components: 12
    documentation: 7
    documentation_note: "3 RF (RF-EDU-001 v2.0) + 3 ET (ET-EDU-001 v2.0, ET-EDU-002 v2.0) + 1 ADR (ADR-008)"

status:
  phase_status: completed
  completion_date: "2024-09-15"
  updated: "2025-11-11"
  notes: |
    Épica completada exitosamente.

    ACTUALIZACIÓN 2025-11-11 (v2.1): Seeds Production-Ready (DB-095, DB-096)
    - Seeds PROD completados: 10 ejercicios → 27 ejercicios (+170%)
    - Module 5 expandido: 97 líneas → 835 líneas (+861%)
    - Migración completa DEV → PROD para 5 módulos
    - JSONB estructura completa: templates, prompts, rúbricas, validaciones
    - Modelo dual eliminado: Consolidación en JSONB puro
    - Completitud PROD: 36% → 100% (+64 puntos)

    ACTUALIZACIÓN 2025-11-11 (v2.0): GAP-3 - Migración completa a CEFR
    - Sistema de dificultad migrado de valores genéricos a estándar internacional CEFR
    - 8 niveles implementados (A1-Nativo) con criterios específicos
    - Sistema completo de progresión y promoción entre niveles
    - Zona de desarrollo próximo (ZDP) implementada
    - Breaking change: ENUM difficulty_level completamente reescrito    

# ============================================================================
# CHANGELOG
# ============================================================================

changelog:
  - date: "2025-11-23"
    version: "2.3"
    author: "Architecture-Analyst"
    changes: |
      CORRECCIÓN POST-ADR-010: Alineación con DocumentoDeDiseño v6.4

      Ejercicios corregidos:
      - Module 1: 6 → 5 (validado: siempre fueron 5 correctos)
      - Module 3: 6 → 5 (ejercicio 3.5 "Matriz de Perspectivas" agregado)
      - Module 4: 5 (placeholders, is_active=false)
      - Module 5: 5 → 3 (corrección según diseño, placeholders)
      - Total: 27 → 23 ejercicios

      Causa raíz: TRACEABILITY no actualizado tras validación ADR-010.
      Referencias:
        - ADR-010: DocumentoDeDiseño como Fuente de Verdad
        - DocumentoDeDiseño v6.4 (2025-11-23)
        - REPORTE-COHERENCIA-DOCUMENTACION-CODIGO-2025-11-23.md      

  - date: "2025-11-11"
    version: "2.2"
    author: "Database Agent"
    changes: |
      RECONCILIACIÓN EXERCISE_MECHANIC ↔ EXERCISE_TYPE (DB-110, DB-111, DB-112)

      Validación y Reconciliación:
      - DB-110: Validación profunda docs/ ↔ DDL → Incoherencia crítica detectada (0/100)
      - DB-111: Propuesta de reconciliación mediante sistema dual
      - DB-112: Validación contra DEFINICIONES → Opción C aprobada por usuario

      Documentación actualizada:
      - ET-EDU-001 v2.0: Sistema dual implementado (exercise_type + clasificación pedagógica)
      - RF-EDU-001 v2.0: Actualizado ENUM canónico a exercise_type (35 valores)
      - ADR-008: Decisión arquitectónica documentada (Sistema Dual)

      DDL:
      - Tabla exercise_mechanic_mapping: Mapeo N:M categorías pedagógicas ↔ implementaciones GAMILIT
      - 7 categorías pedagógicas + 31 subcategorías mapeadas a 35 exercise_types
      - 13 GAPs pedagógicos identificados como roadmap

      Implementación:
      - ENUM exercise_type: 35 valores (Módulos 1-5 + Auxiliares)
      - Índices: category, exercise_type, bloom, tags(GIN)
      - Vista helper: exercises_with_mechanics (opcional)

      Filosofía aplicada: "Adaptar y reconciliar, NO eliminar"
      Coherencia final: 95/100 (Sistema dual reconcilia ambos conceptos)      

  - date: "2024-09-15"
    version: "1.0"
    author: "Development Team"
    changes: "Implementación inicial completa"

  - date: "2025-11-11"
    version: "2.1"
    author: "Database Agent"
    changes: |
      SEEDS PRODUCTION-READY (DB-095, DB-096): Migración DEV → PROD completada

      Seeds PROD creados/actualizados:
      - 01-modules.sql: 5 módulos (existente, actualizado)
      - 02-exercises-module1.sql: 6 ejercicios (NUEVO, 687 líneas)
      - 03-exercises-module2.sql: 5 ejercicios (NUEVO, 571 líneas)
      - 04-exercises-module3.sql: 6 ejercicios (NUEVO, 683 líneas)
      - 05-exercises-module4.sql: 5 ejercicios (NUEVO, 570 líneas)
      - 06-exercises-module5.sql: 5 ejercicios (EXPANDIDO 97 → 835 líneas, +861%)

      Detalles Module 5 (Video Carta):
      - 3 templates completos (Diario Clásico, Científico, Carta Personal)
      - 5 prompts detallados por ejercicio
      - 4 rúbricas de evaluación con criterios y pesos
      - Estructura JSONB completa para producción creativa

      Arquitectura:
      - Eliminadas tablas legacy: assignment_answers, assignment_resources
      - Consolidado a modelo JSONB puro (decisión arquitectónica)
      - educational_content.tables: 16 → 14 tablas

      Inventarios actualizados:
      - DATABASE_INVENTORY_2025-11-11.yml: Actualizado métricas
      - SEEDS_INVENTORY.yml: NUEVO (650+ líneas, 67 seeds documentados)

      Impacto:
      - Seeds PROD: 10 ejercicios → 27 ejercicios (+170%)
      - Completitud PROD: 36% → 100% (+64 puntos)
      - Sistema listo para producción con contenido educativo completo      

  - date: "2025-11-11"
    version: "2.0"
    author: "Database & Backend Team"
    changes: |
      GAP-3 COMPLETADO: Migración CEFR (Breaking Change)

      DDL:
      - ENUM difficulty_level: Migrado a 8 valores CEFR (beginner, elementary, pre_intermediate,
        intermediate, upper_intermediate, advanced, proficient, native)
      - Tabla difficulty_criteria: Define criterios por nivel (vocab, tiempo, recompensas)
      - Tabla user_difficulty_progress: Tracking con GENERATED COLUMNS
      - Tabla user_current_level: Nivel actual + ZDP
      - 3 funciones: check_eligibility, promote_level, update_progress
      - Seed: 8 niveles CEFR configurados

      Backend:
      - DifficultyLevelEnum: Reescrito completamente con valores CEFR

      Seeds actualizados:
      - achievements.sql: 21 occurrences (mapeo aplicado)
      - exercises-module4.sql: 1 occurrence

      Impacto: Breaking change en valores ENUM. No backward compatible.