workspace/projects/gamilit/docs/95-guias-desarrollo/GUIA-REFERENCIAS-SIMCO.md

Guía: Agregar Referencias SIMCO en Código DDL

📋 Objetivo

Esta guía explica cómo agregar referencias bidireccionales entre la documentación (carpeta docs/) y el código de implementación (carpeta apps/) para cumplir con el estándar SIMCO (Sistema Indexado Modular por COntexto).

✅ Estado Actual

Completado:

• ✅ 00-prerequisites.sql: 16 ENUMs con referencias agregadas
• ✅ auth_management.profiles: Tabla de perfiles de usuario
• ✅ gamification_system.comodines_inventory: Tabla de inventario de comodines
• ✅ educational_content.exercises: Tabla de ejercicios

Pendiente:

• ⏳ ~46 tablas SQL restantes
• ⏳ ~100 archivos TypeScript en Backend
• ⏳ ~80 componentes React en Frontend

---

📐 Patrón para Archivos SQL

Formato de Referencias

Agregar un bloque de documentación después del header existente y antes del código SQL:

-- =====================================================
-- Table: nombre_schema.nombre_tabla
-- Description: Descripción de la tabla
-- ...header existente...
--
-- 📚 Documentación:
-- Requerimiento: docs/01-requerimientos/.../RF-XXX-xxx.md
-- Especificación: docs/02-especificaciones-tecnicas/.../ET-XXX-xxx.md
-- Ver también: docs/... (opcional, para referencias adicionales)
-- =====================================================

Ejemplo Real: auth_management.profiles

-- =====================================================
-- Table: auth_management.profiles
-- Description: Perfiles de usuario con información básica, rol y configuraciones
-- Dependencies: auth_management.tenants, auth.users
-- Created: 2025-10-27
--
-- 📚 Documentación:
-- Requerimiento: docs/01-requerimientos/01-autenticacion-autorizacion/RF-AUTH-001-roles.md
-- Requerimiento: docs/01-requerimientos/01-autenticacion-autorizacion/RF-AUTH-002-estados-cuenta.md
-- Especificación: docs/02-especificaciones-tecnicas/01-autenticacion-autorizacion/ET-AUTH-001-rbac.md
-- Especificación: docs/02-especificaciones-tecnicas/01-autenticacion-autorizacion/ET-AUTH-002-estados-cuenta.md
-- =====================================================

SET search_path TO auth_management, public;

CREATE TABLE auth_management.profiles (
    ...
);

Ejemplo Real: educational_content.exercises

-- =====================================================
-- Table: educational_content.exercises
-- Description: Ejercicios con 27 mecánicas diferentes
--
-- 📚 Documentación:
-- Requerimiento: docs/01-requerimientos/03-contenido-educativo/RF-EDU-001-mecanicas-ejercicios.md
-- Especificación: docs/02-especificaciones-tecnicas/03-contenido-educativo/ET-EDU-001-mecanicas-ejercicios.md
-- Ver también: docs/01-requerimientos/modulos/MODULOS-EDUCATIVOS.md
-- =====================================================

---

🗺️ Mapeo de Schemas → Documentación

1. auth_management

Tablas:

• profiles → RF-AUTH-001 (roles), RF-AUTH-002 (estados cuenta)
• linked_providers → RF-AUTH-003 (OAuth)
• sessions, tokens → RF-AUTH-001 (autenticación)

2. gamification_system

Tablas:

• achievements, user_achievements → RF-GAM-001 (achievements)
• comodines_inventory → RF-GAM-002 (comodines)
• leaderboards, user_stats → RF-GAM-003 (rangos Maya)
• ml_coins_transactions → RF-GAM-002 (ML Coins)
• missions, user_missions → RF-GAM-001 (misiones)

3. educational_content

Tablas:

• modules → RF-EDU-001 (módulos educativos)
• exercises → RF-EDU-001 (31 mecánicas)
• media_resources → RF-CNT-001 (gestión media)
• assessment_rubrics → RF-EDU-001 (evaluación)

4. progress_tracking

Tablas:

• module_progress → RF-PRG-001 (estados progreso)
• learning_sessions → RF-PRG-001 (sesiones)
• exercise_attempts → RF-PRG-001 (intentos)
• exercise_submissions → RF-PRG-001 (envíos)

5. social_features

Tablas:

• classrooms → RF-SOC-001 (aulas virtuales)
• classroom_members → RF-SOC-001
• teams, team_members → RF-SOC-001 (equipos)
• friendships → RF-SOC-001 (amistades)

6. audit_logging

Tablas:

• audit_logs → RF-AUD-001 (sistema auditoría)
• admin_audit_log → RF-AUD-001
• security_alerts → RF-AUD-001 (alertas)

7. content_management

Tablas:

• media_files → RF-CNT-001 (gestión media)
• content_versions → RF-CNT-001 (versionado)

---

📂 Archivos Pendientes por Schema

Prioridad Alta (Core Functionality)

# auth_management (5 tablas)
apps/database/ddl/schemas/auth_management/tables/01-tenants.sql
apps/database/ddl/schemas/auth_management/tables/02-tenant_metadata.sql
apps/database/ddl/schemas/auth_management/tables/04-linked_providers.sql
apps/database/ddl/schemas/auth_management/tables/05-sessions.sql
apps/database/ddl/schemas/auth_management/tables/06-auth_tokens.sql

# gamification_system (8 tablas)
apps/database/ddl/schemas/gamification_system/tables/01-user_stats.sql
apps/database/ddl/schemas/gamification_system/tables/02-achievements.sql
apps/database/ddl/schemas/gamification_system/tables/03-user_achievements.sql
apps/database/ddl/schemas/gamification_system/tables/04-leaderboards.sql
apps/database/ddl/schemas/gamification_system/tables/05-ml_coins_transactions.sql
apps/database/ddl/schemas/gamification_system/tables/06-missions.sql
apps/database/ddl/schemas/gamification_system/tables/08-user_missions.sql
apps/database/ddl/schemas/gamification_system/tables/09-notifications.sql

# educational_content (3 tablas)
apps/database/ddl/schemas/educational_content/tables/01-modules.sql
apps/database/ddl/schemas/educational_content/tables/03-assessment_rubrics.sql
apps/database/ddl/schemas/educational_content/tables/04-media_resources.sql

# progress_tracking (5 tablas)
apps/database/ddl/schemas/progress_tracking/tables/01-module_progress.sql
apps/database/ddl/schemas/progress_tracking/tables/02-learning_sessions.sql
apps/database/ddl/schemas/progress_tracking/tables/03-exercise_attempts.sql
apps/database/ddl/schemas/progress_tracking/tables/04-exercise_submissions.sql
apps/database/ddl/schemas/progress_tracking/tables/05-scheduled_missions.sql

# social_features (6 tablas)
apps/database/ddl/schemas/social_features/tables/01-classrooms.sql
apps/database/ddl/schemas/social_features/tables/02-classroom_members.sql
apps/database/ddl/schemas/social_features/tables/03-teams.sql
apps/database/ddl/schemas/social_features/tables/04-team_members.sql
apps/database/ddl/schemas/social_features/tables/05-friendships.sql
apps/database/ddl/schemas/social_features/tables/06-user_activity.sql

# audit_logging (3 tablas)
apps/database/ddl/schemas/audit_logging/tables/01-audit_logs.sql
apps/database/ddl/schemas/audit_logging/tables/02-admin_audit_log.sql
apps/database/ddl/schemas/audit_logging/tables/03-security_alerts.sql

# content_management (2 tablas)
apps/database/ddl/schemas/content_management/tables/01-media_files.sql
apps/database/ddl/schemas/content_management/tables/02-content_versions.sql

---

🔄 Proceso para Agregar Referencias

1. Identificar la tabla

# Ejemplo
vim apps/database/ddl/schemas/gamification_system/tables/01-user_stats.sql

2. Leer el header existente

-- =====================================================
-- Table: gamification_system.user_stats
-- Description: Estadísticas de gamificación por usuario
-- Created: 2025-10-27
-- =====================================================

3. Agregar bloque de documentación

-- =====================================================
-- Table: gamification_system.user_stats
-- Description: Estadísticas de gamificación por usuario
-- Created: 2025-10-27
--
-- 📚 Documentación:
-- Requerimiento: docs/01-requerimientos/02-gamificacion/RF-GAM-001-achievements.md
-- Requerimiento: docs/01-requerimientos/02-gamificacion/RF-GAM-003-rangos-maya.md
-- Especificación: docs/02-especificaciones-tecnicas/02-gamificacion/ET-GAM-001-achievements.md
-- Especificación: docs/02-especificaciones-tecnicas/02-gamificacion/ET-GAM-003-rangos-maya.md
-- =====================================================

4. Verificar que las rutas existan

ls -la ../../docs/01-requerimientos/02-gamificacion/RF-GAM-001-achievements.md
ls -la ../../docs/02-especificaciones-tecnicas/02-gamificacion/ET-GAM-001-achievements.md

5. Commit con mensaje descriptivo

git add apps/database/ddl/schemas/gamification_system/tables/01-user_stats.sql
git commit -m "docs(ddl): Agregar referencias SIMCO en user_stats

- RF-GAM-001: Sistema de Achievements
- RF-GAM-003: Sistema de Rangos Maya
- ET-GAM-001: Implementación Achievements
- ET-GAM-003: Implementación Rangos Maya

Parte de Fase 3.2: Referencias en código DDL"

---

🎯 Próximos Pasos

Fase 3.2: DDL (restante)

• Completar 32 tablas restantes (~4-6 horas)
• Agregar referencias en funciones SQL (~2 horas)
• Agregar referencias en vistas (~1 hora)

Fase 3.3: Backend TypeScript

Agregar JSDoc con referencias:

/**
 * Service para gestionar achievements de gamificación
 *
 * @see {@link RF-GAM-001} docs/01-requerimientos/02-gamificacion/RF-GAM-001-achievements.md
 * @see {@link ET-GAM-001} docs/02-especificaciones-tecnicas/02-gamificacion/ET-GAM-001-achievements.md
 */
export class AchievementService {
  // ...
}

Fase 3.4: Frontend React

Agregar JSDoc con referencias:

/**
 * Componente para mostrar galería de achievements desbloqueados
 *
 * @see {@link RF-GAM-001} docs/01-requerimientos/02-gamificacion/RF-GAM-001-achievements.md
 * @see {@link TEACHER-PORTAL-API} docs/02-especificaciones-tecnicas/apis/TEACHER-PORTAL-API.md#achievements
 */
export const AchievementGallery: React.FC<Props> = () => {
  // ...
}

---

📊 Progreso Estimado

Fase	Estado	Archivos	Tiempo Estimado
3.1: ENUMs	✅ Completado	1 archivo (16 ENUMs)	1 hora
3.2: Tablas DDL	⏳ 10% (4/46)	42 archivos restantes	5-7 horas
3.3: Backend	⏳ Pendiente	~100 archivos	8-10 horas
3.4: Frontend	⏳ Pendiente	~80 archivos	6-8 horas

Total Fase 3: 20-26 horas de trabajo

---

✅ Validación

Para verificar que las referencias están correctas:

# Validar que todos los archivos referenciados existen
cd apps/database/ddl
grep -r "Requerimiento: docs/" . | while read line; do
  file=$(echo "$line" | sed 's/.*Requerimiento: docs/docs/g' | sed 's/\.md.*/\.md/g')
  if [ ! -f "../../$file" ]; then
    echo "❌ FALTA: $file"
  else
    echo "✅ OK: $file"
  fi
done

---

📚 Referencias

• Plan SIMCO Original: docs/PROGRESO-PLAN-SIMCO-2025-11-07.md
• Ejemplo completo: apps/database/ddl/00-prerequisites.sql
• Documentación SIMCO: docs/_MAP.md

---

Última actualización: 2025-11-07 Autor: Database Team Estado: 🟡 En progreso (Fase 3.2)