# 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.