# 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

    - 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

  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: rank
        schema: gamification_system
        file: apps/database/ddl/00-prerequisites.sql
        lines: "55-58"
        values: [ix_chel_aprendiz, ah_puch_explorador, kukulkan_sabio, itzamna_maestro]
        rf: RF-GAM-003

      - name: help_type
        schema: gamification_system
        file: apps/database/ddl/00-prerequisites.sql
        lines: "59-62"
        values: [show_hint, reveal_answer, skip_question, extra_time]
        rf: RF-GAM-002

    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: ranks
        schema: gamification_system
        file: apps/database/ddl/schemas/gamification_system/tables/03-ranks.sql
        lines: 92
        description: Definiciones de rangos maya
        rf: RF-GAM-003
        columns_using_enums:
          - column: rank
            enum: rank

      - name: user_ranks
        schema: gamification_system
        file: apps/database/ddl/schemas/gamification_system/tables/04-user_ranks.sql
        lines: 68
        description: Rango actual y progreso de usuario
        rf: RF-GAM-003

      - 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: help_purchases
        schema: gamification_system
        file: apps/database/ddl/schemas/gamification_system/tables/06-help_purchases.sql
        lines: 72
        description: Compras de comodines/ayudas
        rf: RF-GAM-002
        columns_using_enums:
          - column: help_type
            enum: help_type

    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

    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

    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

  # ============================================================================
  # 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"

    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: 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: 89%
    backend: 91%
    frontend: 87%
    database: 85%

# ============================================================================
# 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: 89%
    bugs_found: 12
    bugs_fixed: 12
    tech_debt: low

  deliverables:
    database_objects: 19
    backend_files: 18
    frontend_components: 11
    tests: 7
    documentation: 8

status:
  phase_status: completed
  completion_date: "2024-09-15"
  accepted_by: Product Owner
  deployed_to: production
  notes: |
    Épica completada exitosamente con ligero sobrepaso en tiempo y presupuesto (+5%).
    Cobertura de tests excelente (89%). Sistema de gamificación bien recibido por usuarios.
    Narrativa maya agrega valor diferencial.

# ============================================================================
# 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: "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"