rckrdmrd
ea1879f4ad
- Configure workspace Git repository with comprehensive .gitignore - Add Odoo as submodule for ERP reference code - Include documentation: SETUP.md, GIT-STRUCTURE.md - Add gitignore templates for projects (backend, frontend, database) - Structure supports independent repos per project/subproject level Workspace includes: - core/ - Reusable patterns, modules, orchestration system - projects/ - Active projects (erp-suite, gamilit, trading-platform, etc.) - knowledge-base/ - Reference code and patterns (includes Odoo submodule) - devtools/ - Development tools and templates - customers/ - Client implementations template 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
890 lines
32 KiB
YAML
890 lines
32 KiB
YAML
# 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)
|