workspace-v1/projects/gamilit/docs/90-transversal/inventarios-database/DECISIONES-ARQUITECTURALES-REQUERIDAS.md

DECISIONES ARQUITECTURALES REQUERIDAS

Fecha: 2025-11-07 Estado: Post-validación de integridad Prioridad: CRÍTICA - Requiere decisión antes de continuar desarrollo

---

PROPÓSITO

Este documento lista las decisiones arquitecturales críticas que deben tomarse para resolver los problemas encontrados en la validación de integridad. Cada decisión está bloqueando funcionalidad o impidiendo el progreso de correcciones.

---

DECISIONES CRÍTICAS (Bloquean desarrollo)

D1. Sistema de Misiones - ¿Dónde ubicar la tabla missions?

Problema:

• Función update_mission_progress referencia educational_content.missions
• La tabla NO existe en educational_content
• Existe gamification_system.missions en archivos DDL

Opciones:

Opción	Pros	Contras	Recomendación
A) Crear en educational_content	Misiones son contenido educativo	Duplica con gamification_system.missions	❌ No recomendado
B) Usar gamification_system.missions	Ya existe en DDL	Función está en progress_tracking	✅ RECOMENDADO
C) Mover a progress_tracking	Función está ahí	Misiones no son solo progreso	⚠️ Considerar

Decisión recomendada: OPCIÓN B

• Usar tabla existente gamification_system.missions
• Actualizar función para referenciar schema correcto
• Razón: Ya existe, schema correcto para misiones

Acción requerida:

-- En progress_tracking/functions/06-update_mission_progress.sql
-- Cambiar:
FROM educational_content.missions
-- Por:
FROM gamification_system.missions

---

D2. Sistema de Inventario - ¿Modelo de datos?

Problema:

• 6 funciones referencian user_inventory y store_items
• Estas tablas NO existen
• Existe tabla comodines_inventory

Opciones:

Opción	Pros	Contras	Esfuerzo
A) Crear user_inventory + store_items	Separación de concerns	2 tablas nuevas, más complejo	8 horas
B) Refactorizar a comodines_inventory	Usa tabla existente	Funciones deben reescribirse	6 horas
C) Modelo híbrido	Flexible	Más complejo mantener	10 horas

Análisis de modelo A (Separación):

-- Tabla de catálogo de items
CREATE TABLE gamification_system.store_items (
    id UUID PRIMARY KEY,
    item_type TEXT, -- 'comodin', 'powerup', 'cosmetic'
    name TEXT,
    description TEXT,
    cost_ml_coins INTEGER,
    metadata JSONB
);

-- Tabla de inventario de usuario
CREATE TABLE gamification_system.user_inventory (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES auth_management.profiles(id),
    item_id UUID REFERENCES gamification_system.store_items(id),
    quantity INTEGER,
    acquired_at TIMESTAMPTZ
);

Análisis de modelo B (Simplificado):

-- Usar tabla existente
-- gamification_system.comodines_inventory ya tiene:
-- - user_id
-- - comodin_type (pistas, vision_lectora, segunda_oportunidad)
-- - quantity
-- - last_earned_at

-- Funciones deben adaptarse para:
-- 1. Usar comodin_type en lugar de item_id
-- 2. Trabajar directamente con inventory

Decisión recomendada: OPCIÓN B (corto plazo) → OPCIÓN A (largo plazo)

Razón:

• Corto plazo: Refactorizar funciones para usar comodines_inventory (menor esfuerzo, funciona YA)
• Largo plazo: Migrar a modelo completo cuando se agreguen items no-comodines

Acción inmediata:

1. Refactorizar 6 funciones para usar comodines_inventory
2. Documentar plan de migración a modelo completo en futuro

---

D3. Tabla mechanic_progress - ¿Feature necesaria?

Problema:

• Función check_mechanic_completion referencia progress_tracking.mechanic_progress
• Tabla NO existe
• No hay otra referencia a "mechanics" en el sistema

Opciones:

Opción	Pros	Contras	Recomendación
A) Crear tabla + feature completa	Sistema de progreso granular	Trabajo adicional sin spec clara	❌ No ahora
B) Eliminar función	Simplifica código	Pierde feature potencial	✅ RECOMENDADO
C) Deprecar y documentar	Mantiene para futuro	Código muerto	⚠️ Alternativa

Decisión recomendada: OPCIÓN B

Razón:

• No hay especificación de "mechanics" como concepto separado
• No hay tabla educational_content.mechanics
• Función no es llamada por ningún otro código
• Simplifica sistema sin perder funcionalidad documentada

Acción requerida:

# Mover a deprecated
mv apps/database/ddl/schemas/progress_tracking/functions/02-check_mechanic_completion.sql \
   apps/database/ddl/schemas/progress_tracking/functions/_deprecated/

# Documentar en _deprecated/README.md por qué se eliminó

---

D4. User Feature Flags - ¿Nivel de usuario o global?

Problema:

• Función is_feature_enabled referencia system_configuration.user_feature_flags
• Tabla NO existe
• Existe system_configuration.feature_flags (tabla global)

Opciones:

Opción	Pros	Contras	Esfuerzo
A) Crear user_feature_flags	Feature flags por usuario	Complejidad adicional	4 horas
B) Usar feature_flags global	Usa tabla existente	No hay control por usuario	1 hora
C) Modelo híbrido (override)	Flexible	Más complejo	6 horas

Análisis:

-- OPCIÓN A: Tabla nueva
CREATE TABLE system_configuration.user_feature_flags (
    user_id UUID REFERENCES auth_management.profiles(id),
    flag_key TEXT,
    enabled BOOLEAN,
    overrides_global BOOLEAN,
    PRIMARY KEY (user_id, flag_key)
);

-- OPCIÓN B: Usar tabla existente
-- system_configuration.feature_flags tiene:
-- - key, enabled, target_roles, ...
-- Función verifica: flag_enabled AND user_role IN target_roles

-- OPCIÓN C: Híbrido
-- 1. Primero busca en user_feature_flags
-- 2. Si no existe, usa feature_flags global
-- 3. Permite overrides por usuario

Decisión recomendada: OPCIÓN B (inmediato) → OPCIÓN C (futuro)

Razón:

• Corto plazo: Tabla global es suficiente para MVP
• target_roles permite filtrado básico
• Largo plazo: Agregar overrides cuando se necesite A/B testing

Acción inmediata:

-- Actualizar función is_feature_enabled
CREATE OR REPLACE FUNCTION public.is_feature_enabled(flag_key TEXT)
RETURNS BOOLEAN AS $$
BEGIN
    RETURN EXISTS (
        SELECT 1 FROM system_configuration.feature_flags
        WHERE key = flag_key
          AND enabled = true
          AND (target_roles IS NULL
               OR gamilit.get_current_user_role() = ANY(target_roles))
    );
END;
$$ LANGUAGE plpgsql STABLE;

---

D5. Tabla maya_ranks (configuración) - ¿Estructura?

Problema:

• 3 funciones referencian gamification_system.maya_ranks
• Tabla NO existe (existe el ENUM maya_rank)
• Se necesita tabla de configuración con XP, perks, etc.

Opciones:

Opción	Pros	Contras	Recomendación
A) Tabla con configuración completa	Flexible, extensible	Requiere seed data	✅ RECOMENDADO
B) Hardcodear en función	Más simple	Difícil cambiar valores	❌ No escalable
C) JSONB en settings	No requiere tabla	Menos estructurado	⚠️ Alternativa

Decisión recomendada: OPCIÓN A

Estructura propuesta:

CREATE TABLE gamification_system.maya_ranks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    rank_name gamification_system.maya_rank NOT NULL UNIQUE,
    rank_order INTEGER NOT NULL UNIQUE, -- 1-5
    min_xp INTEGER NOT NULL,
    max_xp INTEGER, -- NULL para último rango
    description TEXT,
    icon TEXT,
    color TEXT, -- Para UI
    perks JSONB, -- Beneficios del rango
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Seed data
INSERT INTO gamification_system.maya_ranks (rank_name, rank_order, min_xp, max_xp, description, icon, color, perks) VALUES
('Ajaw', 1, 0, 999, 'Nivel inicial del viaje maya', 'star', '#bronze', '{"xp_multiplier": 1.0}'::jsonb),
('Nacom', 2, 1000, 2999, 'Guerrero en entrenamiento', 'shield', '#silver', '{"xp_multiplier": 1.1, "ml_coins_bonus": 10}'::jsonb),
('Ah K''in', 3, 3000, 6999, 'Sacerdote del conocimiento', 'book', '#gold', '{"xp_multiplier": 1.2, "ml_coins_bonus": 20}'::jsonb),
('Halach Uinic', 4, 7000, 14999, 'Líder de la comunidad', 'crown', '#platinum', '{"xp_multiplier": 1.3, "ml_coins_bonus": 30, "unlock_exclusive_content": true}'::jsonb),
('K''uk''ulkan', 5, 15000, NULL, 'Máximo rango maya', 'dragon', '#diamond', '{"xp_multiplier": 1.5, "ml_coins_bonus": 50, "all_perks": true}'::jsonb);

Acción requerida:

1. Crear archivo DDL: gamification_system/tables/10-maya_ranks.sql
2. Crear seed: gamification_system/seeds/maya_ranks.sql
3. Actualizar 3 funciones que la referencian

---

D6. Tabla user_activity_log vs user_activity_logs

Problema:

• Función cleanup_old_user_activity referencia audit_logging.user_activity_log (singular)
• Existe audit_logging.user_activity_logs (plural)
• ¿Es typo o tabla diferente?

Opciones:

Opción	Pros	Contras	Recomendación
A) Es typo, usar _logs	Usa tabla existente	-	✅ RECOMENDADO
B) Son tablas diferentes	-	¿Por qué 2 tablas?	❌ Poco probable

Decisión recomendada: OPCIÓN A (es un typo)

Acción requerida:

-- Actualizar función
-- Cambiar: audit_logging.user_activity_log
-- Por: audit_logging.user_activity_logs

---

D7. Notificaciones - ¿Dónde está la tabla?

Problema:

• Función send_notification referencia social_features.notifications
• Tabla NO existe en social_features
• Existe gamification_system.notifications

Opciones:

Opción	Pros	Contras	Recomendación
A) Mover a social_features	Función lo espera ahí	Notificaciones no son solo sociales	❌
B) Usar gamification_system	Ubicación correcta actual	Función debe actualizarse	✅ RECOMENDADO
C) Duplicar tabla	-	Horrible idea	❌ Nunca

Decisión recomendada: OPCIÓN B

Razón:

• Notificaciones son parte de gamificación (achievements, coins, etc.)
• Schema correcto: gamification_system
• Función debe actualizarse

Acción requerida:

-- Actualizar función send_notification
-- Cambiar: social_features.notifications
-- Por: gamification_system.notifications

---

DECISIONES SECUNDARIAS (No bloquean)

D8. ENUMs en prerequisites vs archivos individuales

Problema: ENUMs definidos en 2 lugares

Decisión: Eliminar de prerequisites, usar solo archivos individuales

Razón: Fuente de verdad única por schema

---

D9. notification_type en public vs gamification_system

Problema: ENUM en schema incorrecto

Decisión: Migrar a gamification_system en fase P1 de ENUMs

Razón: Consistencia arquitectural

---

RESUMEN DE DECISIONES

ID	Decisión	Recomendación	Prioridad	Esfuerzo
D1	Ubicación missions	Usar gamification_system.missions	🔴 CRÍTICA	30 min
D2	Modelo inventario	Refactorizar a comodines_inventory	🔴 CRÍTICA	6 horas
D3	mechanic_progress	Eliminar feature	🔴 CRÍTICA	30 min
D4	User feature flags	Usar tabla global feature_flags	🔴 CRÍTICA	1 hora
D5	maya_ranks config	Crear tabla con seed data	🟠 ALTA	2 horas
D6	user_activity_log	Corregir typo a _logs	🔴 CRÍTICA	10 min
D7	Ubicación notifications	Usar gamification_system	🔴 CRÍTICA	10 min
D8	ENUMs duplicados	Eliminar de prerequisites	🟡 MEDIA	30 min
D9	notification_type schema	Migrar en fase P1	🟡 MEDIA	1 hora

Total esfuerzo estimado (decisiones críticas): ~11 horas

---

PRÓXIMOS PASOS

1. Revisar y aprobar decisiones (30 min - Equipo)
2. Implementar decisiones críticas (1 día)
3. Testing de funciones actualizadas (2 horas)
4. Actualizar documentación (1 hora)
5. Continuar con plan P1 de migración ENUMs

---

Documento preparado por: Sistema de Validación Requiere aprobación de: Arquitecto de BD / Tech Lead Fecha límite decisión: ASAP (bloquea desarrollo)