# Ejemplo de TRACEABILITY.yml # Archivo que vive dentro de cada épica para mantener trazabilidad completa epic_code: EAI-003 epic_name: Gamificación Básica phase: 1 phase_name: Alcance Inicial budget_mxn: 22000 story_points: 40 status: completed sprint: 2-3 period: "Mes 1, Semana 2-3" # ============================================================================ # DOCUMENTACIÓN # ============================================================================ documentation: requirements: - id: RF-GAM-001 file: requerimientos/RF-GAM-001-achievements.md title: Sistema de Logros (Achievements) status: implemented - id: RF-GAM-002 file: requerimientos/RF-GAM-002-comodines.md title: Sistema de Comodines (Ayudas) status: implemented - id: RF-GAM-003 file: requerimientos/RF-GAM-003-rangos-maya.md title: Sistema de Rangos Maya status: implemented specifications: - id: ET-GAM-001 file: especificaciones/ET-GAM-001-achievements.md rf: RF-GAM-001 title: Implementación del Sistema de Achievements status: implemented - id: ET-GAM-002 file: especificaciones/ET-GAM-002-comodines.md rf: RF-GAM-002 title: Implementación del Sistema de Comodines status: implemented version: "1.1" last_updated: "2025-11-11" changes: "Costos sincronizados con DDL: pistas=15, vision_lectora=25, segunda_oportunidad=40" - id: ET-GAM-003 file: especificaciones/ET-GAM-003-rangos-maya.md rf: RF-GAM-003 title: Implementación del Sistema de Rangos Maya status: implemented version: "1.1" last_updated: "2025-11-11" changes: "Umbrales XP sincronizados: Nacom(1K-3K), Ah K'in(3K-6K), Halach Uinic(6K-10K), K'uk'ulkan(10K+)" user_stories: - id: US-GAM-003 file: historias-usuario/US-GAM-003-monedas-lectoras.md title: Monedas lectoras (ML Coins) rf: [RF-GAM-001, RF-GAM-002] story_points: 6 status: completed - id: US-GAM-004 file: historias-usuario/US-GAM-004-sistema-ayudas.md title: Sistema de Ayudas (Comodines) rf: RF-GAM-002 story_points: 5 status: completed - id: US-GAM-005 file: historias-usuario/US-GAM-005-insignias-basicas.md title: Insignias y Achievements rf: RF-GAM-001 story_points: 8 status: completed - id: US-GAM-006 file: historias-usuario/US-GAM-006-narrativa-basica.md title: Narrativa Maya Básica rf: RF-GAM-003 story_points: 4 status: completed - id: US-GAM-008 file: historias-usuario/US-GAM-008-recompensas-modulos.md title: Recompensas por Completar Módulos rf: [RF-GAM-001, RF-GAM-003] story_points: 5 status: completed # ============================================================================ # IMPLEMENTACIÓN - BASE DE DATOS # ============================================================================ implementation: database: schemas: - name: gamification_system path: apps/database/ddl/schemas/gamification_system/ description: Schema principal de gamificación enums: - name: achievement_type schema: gamification_system file: apps/database/ddl/00-prerequisites.sql lines: "51-54" values: [badge, milestone, special, rank_promotion] rf: RF-GAM-001 - name: achievement_category schema: gamification_system file: apps/database/ddl/00-prerequisites.sql lines: "47-50" values: [progress, streak, completion, social, special, mastery, exploration] rf: RF-GAM-001 - name: maya_rank schema: gamification_system file: apps/database/ddl/schemas/gamification_system/enums/maya_rank.sql lines: "8-14" values: [Ajaw, Nacom, "Ah K'in", "Halach Uinic", "K'uk'ulkan"] rf: RF-GAM-003 note: "Rangos mayas con Title Case. 5 niveles de progresión." - name: comodin_type schema: gamification_system file: apps/database/ddl/00-prerequisites.sql lines: "79-80" values: [pistas, vision_lectora, segunda_oportunidad] rf: RF-GAM-002 note: "Comodines (power-ups) del sistema de ayudas" tables: - name: achievements schema: gamification_system file: apps/database/ddl/schemas/gamification_system/tables/01-achievements.sql lines: 125 description: Definiciones de achievements disponibles rf: RF-GAM-001 columns_using_enums: - column: type enum: achievement_type - column: category enum: achievement_category - name: user_achievements schema: gamification_system file: apps/database/ddl/schemas/gamification_system/tables/02-user_achievements.sql lines: 78 description: Achievements desbloqueados por usuario rf: RF-GAM-001 - name: maya_ranks schema: gamification_system file: apps/database/ddl/schemas/gamification_system/tables/13-maya_ranks.sql lines: 131 description: Configuración de rangos maya (5 niveles) con criterios y recompensas rf: RF-GAM-003 columns_using_enums: - column: rank_name enum: maya_rank - column: next_rank enum: maya_rank note: "Tabla de configuración dinámica. Define min_xp, max_xp, ml_coins_bonus, xp_multiplier, perks JSONB" - name: user_ranks schema: gamification_system file: apps/database/ddl/schemas/gamification_system/tables/02-user_ranks.sql lines: 100 description: Rango actual y progreso de usuario rf: RF-GAM-003 columns_using_enums: - column: current_rank enum: maya_rank - column: previous_rank enum: maya_rank - name: coin_transactions schema: gamification_system file: apps/database/ddl/schemas/gamification_system/tables/05-coin_transactions.sql lines: 85 description: Historial de transacciones de ML Coins rf: RF-GAM-001 - name: comodines_inventory schema: gamification_system file: apps/database/ddl/schemas/gamification_system/tables/07-comodines_inventory.sql lines: 156 description: Inventario de comodines por usuario (pistas, vision_lectora, segunda_oportunidad) rf: RF-GAM-002 columns_using_enums: - column: comodin_type enum: comodin_type note: "Tabla con columnas: pistas_count, vision_lectora_count, segunda_oportunidad_count, costos default 15/25/40" - name: comodin_usage_log schema: gamification_system file: apps/database/ddl/schemas/gamification_system/tables/08-comodin_usage_log.sql lines: 98 description: Log de uso de comodines por ejercicio rf: RF-GAM-002 - name: comodin_usage_tracking schema: gamification_system file: apps/database/ddl/schemas/gamification_system/tables/09-comodin_usage_tracking.sql lines: 87 description: Tracking de límites de uso por ejercicio rf: RF-GAM-002 functions: - name: check_and_unlock_achievement schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/01-check_and_unlock_achievement.sql lines: 156 description: Verifica criterios y desbloquea achievements rf: RF-GAM-001 used_by: - AchievementListener (backend) - name: award_achievement_rewards schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/02-award_achievement_rewards.sql lines: 98 description: Otorga recompensas (XP, ML Coins) al desbloquear achievement rf: RF-GAM-001 - name: calculate_rank_progress schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/03-calculate_rank_progress.sql lines: 112 description: Calcula progreso hacia siguiente rango rf: RF-GAM-003 - name: award_coins schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/04-award_coins.sql lines: 73 description: Otorga ML Coins a usuario rf: RF-GAM-001 - name: spend_coins schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/05-spend_coins.sql lines: 89 description: Gasta ML Coins (validando saldo suficiente) rf: RF-GAM-001, RF-GAM-002 # FUNCIONES RANGOS MAYA - NUEVAS (2025-11-11) - name: update_user_rank schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/update_user_rank.sql lines: 92 description: "Actualiza rango basado en XP. LEE DINÁMICAMENTE desde maya_ranks table." rf: RF-GAM-003 version: "2.0" changes: "Migrado a maya_rank ENUM. Usa SELECT dinámico en vez de CASE hardcodeado." used_by: - RankService (backend) - name: get_rank_multiplier schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/get_rank_multiplier.sql lines: 42 description: Obtiene multiplicador XP desde maya_ranks table rf: RF-GAM-003 created: "2025-11-11" returns: "NUMERIC(3,2)" - name: get_rank_benefits schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/get_rank_benefits.sql lines: 42 description: Obtiene perks (beneficios) desde maya_ranks table rf: RF-GAM-003 created: "2025-11-11" returns: "JSONB" - name: check_rank_promotion schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/check_rank_promotion.sql lines: 67 description: Verifica elegibilidad para promoción de rango (lee next_rank de maya_ranks) rf: RF-GAM-003 created: "2025-11-11" returns: "BOOLEAN" security: "SECURITY DEFINER" - name: promote_to_next_rank schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/promote_to_next_rank.sql lines: 128 description: Promociona usuario al siguiente rango (actualiza user_stats, user_ranks, registra transacción) rf: RF-GAM-003 created: "2025-11-11" returns: "VOID" security: "SECURITY DEFINER" parameters: - p_user_id: UUID - p_new_rank: gamification_system.maya_rank # FUNCIONES COMODINES - ACTUALIZADAS (2025-11-11) - name: purchase_comodin schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/purchase_comodin.sql lines: 98 description: "Compra comodines con ML Coins (costos: 15/25/40)" rf: RF-GAM-002 version: "1.1" changes: "Costos sincronizados: pistas=15, vision_lectora=25, segunda_oportunidad=40" - name: use_comodin schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/use_comodin.sql lines: 112 description: Usa comodín en ejercicio (respeta límites por ejercicio) rf: RF-GAM-002 - name: get_comodin_inventory schema: gamification_system file: apps/database/ddl/schemas/gamification_system/functions/get_comodin_inventory.sql lines: 78 description: Obtiene inventario completo de comodines del usuario rf: RF-GAM-002 triggers: - name: trg_achievement_unlocked table: user_achievements file: apps/database/ddl/schemas/gamification_system/triggers/01-trg_achievement_unlocked.sql lines: 45 description: Ejecuta al desbloquear achievement (notificación + recompensas) rf: RF-GAM-001 - name: trg_check_rank_promotion table: user_ranks file: apps/database/ddl/schemas/gamification_system/triggers/02-trg_check_rank_promotion.sql lines: 52 description: Verifica si XP alcanza siguiente rango rf: RF-GAM-003 - name: trg_check_rank_promotion_on_xp_gain table: user_stats file: apps/database/ddl/schemas/gamification_system/triggers/trg_check_rank_promotion_on_xp_gain.sql lines: 45 description: "Trigger automático que verifica promoción cuando total_xp aumenta" rf: RF-GAM-003 created: "2025-11-11" event: "AFTER UPDATE OF total_xp" condition: "NEW.total_xp > OLD.total_xp" views: - name: user_gamification_stats schema: gamification_system file: apps/database/ddl/schemas/gamification_system/views/01-user_gamification_stats.sql lines: 67 description: Vista consolidada de estadísticas de gamificación por usuario rf: RF-GAM-001, RF-GAM-003 materialized_views: - name: achievement_leaderboard schema: gamification_system file: apps/database/ddl/schemas/gamification_system/materialized-views/01-achievement_leaderboard.sql lines: 48 description: Leaderboard de achievements (cacheable) rf: RF-GAM-001 indexes: - name: idx_user_achievements_user_id table: user_achievements file: apps/database/ddl/schemas/gamification_system/indexes/01-idx_user_achievements.sql lines: 15 description: Índice para consultas por usuario rf: RF-GAM-001 rls_policies: - name: user_achievements_select_policy table: user_achievements file: apps/database/ddl/schemas/gamification_system/rls-policies/01-policies.sql lines: 89 description: RLS para ver solo achievements propios rf: RF-GAM-001 seeds: - name: 03-maya_ranks schema: gamification_system file: apps/database/seeds/prod/gamification_system/03-maya_ranks.sql lines: 200 description: "Configuración de 5 rangos maya (Ajaw: 0-999, Nacom: 1K-3K, Ah K'in: 3K-6K, Halach Uinic: 6K-10K, K'uk'ulkan: 10K+)" rf: RF-GAM-003 records: 5 note: "Umbrales XP sincronizados 2025-11-11" # ============================================================================ # IMPLEMENTACIÓN - BACKEND # ============================================================================ backend: module: gamification path: apps/backend/src/modules/gamification/ rf: [RF-GAM-001, RF-GAM-002, RF-GAM-003] services: - name: achievement.service.ts path: apps/backend/src/modules/gamification/services/achievement.service.ts lines: 245 description: Lógica de achievements rf: RF-GAM-001 methods: - checkAndUnlockAchievement() - getUserAchievements() - getAchievementProgress() - name: rank.service.ts path: apps/backend/src/modules/gamification/services/rank.service.ts lines: 198 description: Lógica de rangos maya rf: RF-GAM-003 methods: - getCurrentRank() - calculateRankProgress() - promoteRank() - name: coin.service.ts path: apps/backend/src/modules/gamification/services/coin.service.ts lines: 167 description: Lógica de ML Coins rf: RF-GAM-001 methods: - awardCoins() - spendCoins() - getCoinBalance() - getCoinHistory() - name: help.service.ts path: apps/backend/src/modules/gamification/services/help.service.ts lines: 142 description: Lógica de comodines/ayudas rf: RF-GAM-002 methods: - purchaseHelp() - getAvailableHelps() - useHelp() controllers: - name: gamification.controller.ts path: apps/backend/src/modules/gamification/controllers/gamification.controller.ts lines: 189 description: API endpoints de gamificación rf: [RF-GAM-001, RF-GAM-002, RF-GAM-003] endpoints: - "GET /api/gamification/achievements" - "GET /api/gamification/achievements/:id" - "GET /api/gamification/rank" - "GET /api/gamification/coins" - "POST /api/gamification/coins/spend" - "GET /api/gamification/helps" - "POST /api/gamification/helps/purchase" - name: user-stats.controller.ts path: apps/backend/src/modules/gamification/controllers/user-stats.controller.ts description: Controlador de estadísticas de gamificación por usuario implemented: 2025-11-23 rf: [RF-GAM-001, RF-GAM-003] endpoints: - path: /gamification/users/:userId/summary method: GET description: Returns complete gamification data for a user (XP, rank, coins, achievements) dto_response: UserGamificationSummaryDto service: GamificationService.getUserSummary() implemented: 2025-11-23 frontend_usage: useUserGamification hook (React Query) related_adr: ADR-013 response_fields: - xp (number) - rank (string) - rankProgress (number) - coins (number) - achievements (Achievement[]) - leaderboardPosition (number) dtos: - name: unlock-achievement.dto.ts path: apps/backend/src/modules/gamification/dto/unlock-achievement.dto.ts lines: 23 rf: RF-GAM-001 - name: rank-progress.dto.ts path: apps/backend/src/modules/gamification/dto/rank-progress.dto.ts lines: 28 rf: RF-GAM-003 - name: spend-coins.dto.ts path: apps/backend/src/modules/gamification/dto/spend-coins.dto.ts lines: 19 rf: RF-GAM-001 - name: purchase-help.dto.ts path: apps/backend/src/modules/gamification/dto/purchase-help.dto.ts lines: 21 rf: RF-GAM-002 listeners: - name: achievement.listener.ts path: apps/backend/src/modules/gamification/listeners/achievement.listener.ts lines: 134 description: Escucha eventos para desbloquear achievements rf: RF-GAM-001 events: - exercise.completed - module.completed - streak.achieved enums: - name: achievement-type.enum.ts path: apps/backend/src/modules/gamification/enums/achievement-type.enum.ts lines: 12 rf: RF-GAM-001 sync_with_db: gamification_system.achievement_type - name: achievement-category.enum.ts path: apps/backend/src/modules/gamification/enums/achievement-category.enum.ts lines: 14 rf: RF-GAM-001 sync_with_db: gamification_system.achievement_category - name: rank.enum.ts path: apps/backend/src/modules/gamification/enums/rank.enum.ts lines: 11 rf: RF-GAM-003 sync_with_db: gamification_system.rank - name: help-type.enum.ts path: apps/backend/src/modules/gamification/enums/help-type.enum.ts lines: 10 rf: RF-GAM-002 sync_with_db: gamification_system.help_type # ============================================================================ # IMPLEMENTACIÓN - FRONTEND # ============================================================================ frontend: feature: student/gamification path: apps/frontend/src/features/student/gamification/ rf: [RF-GAM-001, RF-GAM-002, RF-GAM-003] components: - name: AchievementGallery.tsx path: apps/frontend/src/features/student/gamification/components/AchievementGallery.tsx lines: 178 description: Galería de achievements (desbloqueados + bloqueados) rf: RF-GAM-001 - name: AchievementCard.tsx path: apps/frontend/src/features/student/gamification/components/AchievementCard.tsx lines: 92 description: Tarjeta individual de achievement rf: RF-GAM-001 - name: AchievementUnlockedModal.tsx path: apps/frontend/src/features/student/gamification/components/AchievementUnlockedModal.tsx lines: 115 description: Modal de celebración al desbloquear achievement rf: RF-GAM-001 - name: AchievementProgress.tsx path: apps/frontend/src/features/student/gamification/components/AchievementProgress.tsx lines: 87 description: Barra de progreso hacia achievement rf: RF-GAM-001 - name: RankProgressBar.tsx path: apps/frontend/src/features/student/gamification/components/RankProgressBar.tsx lines: 125 description: Barra de progreso de XP hacia siguiente rango rf: RF-GAM-003 - name: RankBadge.tsx path: apps/frontend/src/features/student/gamification/components/RankBadge.tsx lines: 68 description: Badge visual del rango actual rf: RF-GAM-003 - name: CoinsDisplay.tsx path: apps/frontend/src/features/student/gamification/components/CoinsDisplay.tsx lines: 54 description: Display de ML Coins con balance actual rf: RF-GAM-001 - name: CoinHistoryModal.tsx path: apps/frontend/src/features/student/gamification/components/CoinHistoryModal.tsx lines: 98 description: Modal con historial de transacciones de coins rf: RF-GAM-001 - name: HelpShop.tsx path: apps/frontend/src/features/student/gamification/components/HelpShop.tsx lines: 156 description: Tienda de comodines/ayudas rf: RF-GAM-002 - name: HelpButton.tsx path: apps/frontend/src/features/student/gamification/components/HelpButton.tsx lines: 73 description: Botón para usar ayuda durante ejercicio rf: RF-GAM-002 - name: MayaNarrativePanel.tsx path: apps/frontend/src/features/student/gamification/components/MayaNarrativePanel.tsx lines: 142 description: Panel con narrativa maya según rango rf: RF-GAM-003 types: - name: gamification.types.ts path: apps/frontend/src/features/student/gamification/types/gamification.types.ts lines: 89 description: Types TypeScript para gamificación rf: [RF-GAM-001, RF-GAM-002, RF-GAM-003] hooks: - name: useUserGamification.ts file: apps/frontend/src/shared/hooks/useUserGamification.ts description: Custom React Query hook for fetching complete user gamification data technology: React Query v5 (TanStack Query) implemented: 2025-11-23 rf: [RF-GAM-001, RF-GAM-003] query_config: queryKey: ['userGamification', userId] endpoint: GET /gamification/users/:userId/summary staleTime: 5 minutes (300000ms) gcTime: 10 minutes (600000ms) enabled: !!userId returns: data: UserGamificationData | undefined isLoading: boolean error: Error | null refetch: () => void related_adr: ADR-013 (React Query Adoption) used_by: - GamificationWidget (StudentDashboard) - UserProfileCard - AdminUserDetails note: "Primer hook del proyecto en usar React Query. Sirve como patrón para futuros hooks de data fetching." - name: useAchievements.ts path: apps/frontend/src/features/student/gamification/hooks/useAchievements.ts lines: 67 description: Hook para gestionar achievements rf: RF-GAM-001 - name: useRanks.ts path: apps/frontend/src/features/student/gamification/hooks/useRanks.ts lines: 54 description: Hook para gestionar rangos rf: RF-GAM-003 - name: useCoins.ts path: apps/frontend/src/features/student/gamification/hooks/useCoins.ts lines: 49 description: Hook para gestionar ML Coins rf: RF-GAM-001 - name: useHelps.ts path: apps/frontend/src/features/student/gamification/hooks/useHelps.ts lines: 58 description: Hook para gestionar comodines/ayudas rf: RF-GAM-002 stores: - name: gamificationStore.ts path: apps/frontend/src/features/student/gamification/stores/gamificationStore.ts lines: 112 description: Zustand store de gamificación (state global) rf: [RF-GAM-001, RF-GAM-002, RF-GAM-003] # ============================================================================ # TESTING # ============================================================================ testing: backend: unit_tests: - name: achievement.service.spec.ts path: apps/backend/src/modules/gamification/services/achievement.service.spec.ts lines: 234 coverage: 92% rf: RF-GAM-001 - name: rank.service.spec.ts path: apps/backend/src/modules/gamification/services/rank.service.spec.ts lines: 189 coverage: 88% rf: RF-GAM-003 - name: coin.service.spec.ts path: apps/backend/src/modules/gamification/services/coin.service.spec.ts lines: 167 coverage: 94% rf: RF-GAM-001 integration_tests: - name: gamification.e2e.spec.ts path: apps/backend/test/gamification.e2e.spec.ts lines: 312 description: Tests E2E de gamificación rf: [RF-GAM-001, RF-GAM-002, RF-GAM-003] frontend: component_tests: - name: AchievementGallery.test.tsx path: apps/frontend/src/features/student/gamification/components/__tests__/AchievementGallery.test.tsx lines: 156 coverage: 87% rf: RF-GAM-001 - name: RankProgressBar.test.tsx path: apps/frontend/src/features/student/gamification/components/__tests__/RankProgressBar.test.tsx lines: 123 coverage: 91% rf: RF-GAM-003 database: sql_tests: - name: test-achievements.sql path: apps/database/tests/gamification/test-achievements.sql lines: 198 description: Tests de funciones de achievements rf: RF-GAM-001 - name: test-ranks.sql path: apps/database/tests/gamification/test-ranks.sql lines: 145 description: Tests de funciones de rangos rf: RF-GAM-003 coverage: overall: 25% # REAL (actualizado 2025-11-23) backend: 35% # REAL (actualizado 2025-11-23) frontend: 15% # REAL (actualizado 2025-11-23) database: 0% # REAL (actualizado 2025-11-23) meta_original: 89% # Conservado para referencia histórica gap_actual: -64% # 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. Solo módulo ranks tiene tests (ranks.service.spec.ts y ranks.controller.spec.ts). Los demás servicios (achievement, coin, powerup, streak, leaderboard) NO tienen tests. Frontend gamification tiene 74 componentes implementados pero solo 1 test. 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: effort: estimated_sp: 40 actual_sp: 42 variance: +5% budget: estimated: 22000 actual: 23100 variance: +5% time: estimated_days: 10 actual_days: 11 variance: +10% quality: test_coverage: 25% test_coverage_original_estimate: 89% coverage_gap: -64% bugs_found: 12 bugs_fixed: 12 tech_debt: medium note: "Coverage real actualizado 2025-11-08 - Solo ranks.service y ranks.controller tienen tests" deliverables: database_objects: 24 backend_files: 18 frontend_components: 11 tests: 7 documentation: 10 status: phase_status: completed completion_date: "2024-09-15" accepted_by: Product Owner deployed_to: production updated: "2025-11-08" notes: | Épica completada exitosamente con ligero sobrepaso en tiempo y presupuesto (+5%). Sistema de gamificación bien recibido por usuarios. Narrativa maya agrega valor diferencial. ACTUALIZACIÓN 2025-11-08: Test coverage real es 25%, no 89% como se estimó originalmente. Solo ranks.service.spec.ts y ranks.controller.spec.ts tienen tests completos. Los demás servicios (achievement, coin, powerup, streak, leaderboard) NO tienen tests. Frontend gamification tiene 74 componentes implementados pero solo 1 test. Brecha crítica de -64% que necesita ser atendida urgentemente. # ============================================================================ # DEPENDENCIAS # ============================================================================ dependencies: required_by_epics: - EAI-002 # Actividades necesitan sistema de XP - EXT-004 # Perfiles muestran achievements - EXT-005 # Reportes incluyen métricas de gamificación depends_on_epics: - EAI-001 # Requiere auth y perfiles de usuario # ============================================================================ # NOTAS ADICIONALES # ============================================================================ notes: - La narrativa maya fue agregada como valor adicional sin costo extra - Sistema de comodines diseñado para expansión futura (tienda de items) - ENUMs sincronizados entre BD, backend y frontend para evitar inconsistencias - RLS implementado para seguridad de datos de gamificación - Leaderboard implementado como materialized view para performance lessons_learned: - Sincronizar ENUMs entre capas desde el inicio evita bugs - Listeners de eventos facilitan lógica reactiva de achievements - Materialized views mejoran performance en leaderboards - Narrativa maya genera engagement excepcional con estudiantes # ============================================================================ # CHANGELOG # ============================================================================ changelog: - date: "2025-11-23" version: "2.1" author: "Architecture-Analyst" changes: | ACTUALIZACIÓN TEST COVERAGE: Métricas reales vs estimaciones Coverage actualizado con valores REALES (no estimados): - Overall: 89% → 25% (gap: -64%) - Backend: 91% → 35% (gap: -56%) - Frontend: 88% → 15% (gap: -73%) - Database: N/A → 0% Causa raíz: Valores previos eran estimaciones optimistas del inicio del proyecto. Plan de mejora: orchestration/roadmap/ROADMAP-TEST-COVERAGE.md (pendiente crear). Referencias: - REPORTE-COHERENCIA-DOCUMENTACION-CODIGO-2025-11-23.md - GAP-4: Test coverage metrics incorrectos - date: "2024-08-15" version: "1.0" author: "Development Team" changes: "Implementación inicial completa" - date: "2024-09-05" version: "1.1" author: "Backend Team" changes: "Optimización de funciones de achievements" - date: "2024-09-15" version: "1.2" author: "Frontend Team" changes: "Mejoras UI/UX en galería de achievements" - date: "2025-11-11" version: "2.0" author: "Database Team" changes: | GAP-1 CORREGIDO: ET-GAM-002 costos sincronizados con DDL (15/25/40) GAP-2 CORREGIDO: Sistema de rangos refactorizado - update_user_rank() migrado a maya_rank ENUM con lectura dinámica - Umbrales XP corregidos en ET-GAM-003 - 5 funciones nuevas implementadas: get_rank_multiplier, get_rank_benefits, check_rank_promotion, promote_to_next_rank, trigger automático - Sistema ahora 100% dinámico (lee desde maya_ranks table)