rckrdmrd/workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d0d5699cd5
workspace/projects/gamilit/docs/90-transversal/templates/EJEMPLO-TRACEABILITY.yml
rckrdmrd ea1879f4ad feat: Initial workspace structure with multi-level Git configuration 
- 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>
2025-12-08 10:44:23 -06:00

665 lines
22 KiB
YAML
Raw Blame History

# 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"
Reference in New Issue View Git Blame Copy Permalink