rckrdmrd 59f1e3badf Initial commit - erp-core

2026-01-04 06:12:07 -06:00

38 KiB

Raw Blame History

Arquitectura de Base de Datos Multi-Schema - GAMILIT

Documento: Analisis de Arquitectura de Base de Datos Proyecto de Referencia: GAMILIT Fecha: 2025-11-23 Analista: Architecture-Analyst Agent

1. VISION GENERAL

GAMILIT implementa una arquitectura multi-schema en PostgreSQL 16+ que organiza objetos de base de datos por dominios de negocio, proporcionando separacion logica, permisos granulares y escalabilidad arquitectonica.

1.1 Principios Arquitectonicos

Domain-Driven Design (DDD): Cada schema representa un contexto delimitado (bounded context)
Separation of Concerns: Objetos agrupados por responsabilidad funcional
Principle of Least Privilege: Permisos granulares por schema
Scalability First: Facil agregar nuevos dominios sin afectar existentes
Documentation as Code: Sistema SIMCO de mapas _MAP.md jerarquicos

2. LOS 9 SCHEMAS DE GAMILIT

2.1 Resumen Comparativo

Schema	Tablas	Indices	Funciones	Triggers	RLS Policies	Vistas	MViews	Total Objetos
auth_management	15	11	6	6	1 archivo	-	-	39
gamification_system	15	23	25	10	8 archivos	4	4	93
educational_content	14	16	3	4	2 archivos	-	-	42
progress_tracking	~8	~15	~5	~3	~2 archivos	-	-	~35
social_features	~10	~12	~4	~2	~2 archivos	-	-	~32
content_management	~6	~8	~2	~2	~1 archivo	-	-	~20
audit_logging	~4	~6	~2	~1	~1 archivo	-	-	~15
system_configuration	~3	~4	~2	~1	~1 archivo	-	-	~12
public	~2	~3	~10	-	-	-	-	~15
TOTAL	~77	~98	~59	~29	~18	4	4	~303

Nota: Numeros exactos solo para auth_management, gamification_system y educational_content (documentados). Resto estimado.

2.2 Detalle por Schema

2.2.1 auth_management - Autenticacion y Autorizacion

Proposito: Gestion completa de autenticacion, usuarios, roles, sesiones y seguridad.

Tablas (15):

01. tenants                       -- Multi-tenancy (organizaciones)
02. auth_attempts                 -- Intentos de autenticacion (tracking)
03. profiles                      -- Perfiles de usuario
04. roles                         -- Roles del sistema (RBAC)
05. auth_providers                -- Proveedores OAuth (Google, GitHub, etc.)
06. email_verification_tokens     -- Tokens de verificacion de email
07. password_reset_tokens         -- Tokens de reset de password
08. security_events               -- Eventos de seguridad (logs)
09. user_preferences              -- Preferencias de usuario (theme, language)
10. memberships                   -- Membresias de usuarios en tenants
11. user_sessions                 -- Sesiones activas (JWT tracking)
12. user_suspensions              -- Suspensiones de usuarios
14. parent_accounts               -- Cuentas de padres (FUTURE - EXT-010)
15. parent_student_links          -- Links padres-estudiantes (FUTURE)
16. parent_notifications          -- Notificaciones a padres (FUTURE)

Funciones (6):

01. assign_role_to_user()         -- Asignar rol a usuario
02. get_user_role()               -- Obtener rol de usuario
03. verify_user_permission()      -- Verificar permiso
04. remove_role_from_user()       -- Remover rol
05. hash_token()                  -- Hash de tokens de seguridad
06. update_user_preferences()     -- Actualizar preferencias

Triggers (6):

02. trg_memberships_updated_at    -- Auto-actualizar updated_at
03. trg_audit_profile_changes     -- Auditar cambios en profiles
04. trg_initialize_user_stats     -- Inicializar stats de gamificacion
05. trg_profiles_updated_at       -- Auto-actualizar updated_at
06. trg_tenants_updated_at        -- Auto-actualizar updated_at
07. trg_user_roles_updated_at     -- Auto-actualizar updated_at

Indices (11):

Indices en user_roles (role, tenant_id, user_id)
Indices en user_sessions (active, expires, tokens)
Indices en user_preferences (theme)
Indices GIN en permissions

RLS Policies: 1 archivo consolidado con politicas de acceso

Patrones observados:

✅ Multi-tenancy con tabla tenants
✅ RBAC (Role-Based Access Control) con roles y user_roles
✅ OAuth providers multiples
✅ Tokens con hash de seguridad
✅ Auditoria de eventos de seguridad
✅ Sesiones con JWT tracking
✅ Triggers para updated_at automatico
✅ RLS policies para multi-tenant isolation

Aplicabilidad a ERP Generico: ⭐⭐⭐⭐⭐ (MAXIMA)

Decision: ✅ ADOPTAR estructura completa de autenticacion y RBAC

2.2.2 gamification_system - Sistema de Gamificacion

Proposito: Sistema completo de gamificacion con logros, rangos mayas, monedas ML, comodines y notificaciones.

Tablas (15):

01. user_stats                    -- Estadisticas de usuario (XP, level, coins, streak)
02. user_ranks                    -- Historial de rangos mayas
03. achievements                  -- Logros disponibles
04. user_achievements             -- Logros desbloqueados por usuarios
05. ml_coins_transactions         -- Transacciones de ML Coins
06. missions                      -- Misiones disponibles
07. comodines_inventory           -- Inventario de comodines (power-ups)
08. notifications                 -- Notificaciones del sistema
09. leaderboard_metadata          -- Metadata de leaderboards
10. achievement_categories        -- Categorias de logros
11. active_boosts                 -- Boosts activos temporales
12. inventory_transactions        -- Transacciones de inventario
13. maya_ranks                    -- Definicion de rangos mayas
14. comodin_usage_log             -- Log de uso de comodines
15. comodin_usage_tracking        -- Tracking de uso de comodines

ENUMs (4):

maya_rank                -- 5 rangos: Ajaw, Nacom, Ah K'in, Halach Uinic, K'uk'ulkan
notification_priority    -- 4 niveles: low, medium, high, critical
notification_type        -- 11 tipos: achievement_unlocked, rank_up, etc.
transaction_type         -- 14 tipos: earned_exercise, spent_powerup, etc.

Funciones (25):

apply_xp_boost()                  -- Aplicar boost de XP
award_ml_coins()                  -- Otorgar ML Coins
calculate_level_from_xp()         -- Calcular nivel desde XP
calculate_user_rank()             -- Calcular rango maya
check_and_award_achievements()    -- Verificar y otorgar logros
check_rank_promotion()            -- Verificar promocion de rango (NUEVO)
claim_achievement_reward()        -- Reclamar recompensa de logro
consume_comodin()                 -- Consumir comodin (power-up)
get_rank_benefits()               -- Obtener beneficios de rango (NUEVO)
get_rank_multiplier()             -- Obtener multiplicador de rango (NUEVO)
get_user_comodines()              -- Obtener comodines de usuario
get_user_inventory_summary()      -- Resumen de inventario
get_user_rank_progress()          -- Progreso de rango
get_user_rank_requirements()      -- Requisitos de siguiente rango
process_exercise_completion()     -- Procesar completacion de ejercicio
promote_to_next_rank()            -- Promocion a siguiente rango (NUEVO)
send_notification()               -- Enviar notificacion
update_leaderboard_coins()        -- Actualizar leaderboard de coins
update_leaderboard_global()       -- Actualizar leaderboard global
update_leaderboard_streaks()      -- Actualizar leaderboard de rachas
update_user_rank()                -- Actualizar rango de usuario (REFACTORIZADO)
recalculate_level_on_xp_change()  -- Recalcular nivel al cambiar XP
update_missions_updated_at()      -- Auto-actualizar updated_at
update_notifications_updated_at() -- Auto-actualizar updated_at

Triggers (10):

01. trg_achievement_unlocked           -- Trigger al desbloquear logro
02. trg_check_rank_promotion           -- Verificar promocion de rango
15. trg_achievements_updated_at        -- Auto-actualizar updated_at
16. trg_comodines_inventory_updated_at -- Auto-actualizar updated_at
17. missions_updated_at                -- Auto-actualizar updated_at
18. notifications_updated_at           -- Auto-actualizar updated_at
19. trg_user_ranks_updated_at          -- Auto-actualizar updated_at
20. trg_user_stats_updated_at          -- Auto-actualizar updated_at
21. trg_recalculate_level_on_xp_change -- Recalcular nivel automaticamente
    trg_check_rank_promotion_on_xp_gain -- Promocion automatica (NUEVO)

Vistas (4):

01. leaderboard_coins    -- Leaderboard por ML Coins
02. leaderboard_global   -- Leaderboard global por XP
03. leaderboard_streaks  -- Leaderboard por rachas
04. leaderboard_xp       -- Leaderboard por XP puro

Vistas Materializadas (4):

01. mv_global_leaderboard    -- Leaderboard global materializado
02. mv_classroom_leaderboard -- Leaderboard por aula
03. mv_weekly_leaderboard    -- Leaderboard semanal
04. mv_mechanic_leaderboard  -- Leaderboard por mecanica educativa

Indices (23): Indices optimizados en user_stats, achievements, transactions, etc.

RLS Policies: 8 archivos (ml-coins, achievements, user-stats, inventory, notifications, leaderboard)

Patrones observados:

✅ Sistema de XP y niveles con calculo automatico
✅ Rangos jerarquicos (mayas) con beneficios
✅ Moneda virtual (ML Coins) con transacciones
✅ Logros con condiciones y recompensas
✅ Comodines/Power-ups con inventario
✅ Notificaciones con prioridades
✅ Leaderboards con vistas materializadas (performance)
✅ Triggers automaticos para recalculo
✅ Funciones PL/pgSQL para logica compleja

Aplicabilidad a ERP Generico: ⭐⭐ (BAJA)

Decision: ❌ NO ADOPTAR (especifico de gamificacion, no aplicable a ERP)

2.2.3 educational_content - Contenido Educativo

Proposito: Modulos educativos, ejercicios, recursos multimedia y assignments.

Tablas (14 activas):

01. modules                       -- Modulos educativos (5 modulos)
02. exercises                     -- Ejercicios (33 tipos diferentes, 85 total)
03. assessment_rubrics            -- Rubricas de evaluacion
04. media_resources               -- Recursos multimedia
05. assignments                   -- Tareas asignadas por profesor
06. assignment_exercises          -- Ejercicios en cada assignment
07. assignment_students           -- Estudiantes asignados
08. assignment_submissions        -- Envios de estudiantes
    content_approvals             -- Aprobaciones de contenido
    content_metadata              -- Metadata de contenido
    content_tags                  -- Tags de contenido
    module_dependencies           -- Dependencias entre modulos
    taxonomies                    -- Taxonomias educativas
20. difficulty_criteria           -- Criterios de dificultad CEFR (NUEVO)

-- DEPRECATED (eliminadas):
-- exercise_answers.sql
-- exercise_options.sql

ENUMs (3):

bloom_taxonomy       -- Taxonomia de Bloom educativa
difficulty_level     -- 8 niveles CEFR: beginner (A1), elementary (A2), ..., native
exercise_mechanic    -- 33 mecanicas educativas diferentes

Funciones (3):

calculate_learning_path()         -- Calcular ruta de aprendizaje
get_recommended_missions()        -- Recomendar misiones
validate_exercise_structure()     -- Validar estructura de ejercicio

Triggers (4):

11. trg_assessment_rubrics_updated_at  -- Auto-actualizar updated_at
12. trg_exercises_updated_at           -- Auto-actualizar updated_at
13. trg_media_resources_updated_at     -- Auto-actualizar updated_at
14. trg_modules_updated_at             -- Auto-actualizar updated_at

Indices (16): Indices en assignments, submissions, exercises

RLS Policies: 2 archivos (enable-rls, modules-exercises-policies)

Patrones observados:

✅ Modulos con dependencias (prerequisitos)
✅ Ejercicios con config JSONB (modelo dual)
✅ Niveles de dificultad CEFR internacional
✅ Assignments con deadlines
✅ Sistema de submissions y grading
✅ Recursos multimedia con metadata
✅ Taxonomias educativas
❌ Modelo JSONB puro (eliminaron exercise_options y exercise_answers)

Aplicabilidad a ERP Generico: ⭐ (MUY BAJA)

Decision: ❌ NO ADOPTAR (especifico de educacion, no aplicable a ERP)

Aprendizajes trasladables:

✅ Patron de assignments (podria ser ordenes de trabajo)
✅ Sistema de submissions (podria ser entregas/recepciones)
✅ Modelo JSONB para datos flexibles

2.2.4 progress_tracking - Seguimiento de Progreso

Proposito: Tracking de progreso de estudiantes, sesiones de aprendizaje, attempts de ejercicios.

Tablas (~8):

module_progress              -- Progreso en modulos
learning_sessions            -- Sesiones de aprendizaje
exercise_attempts            -- Intentos de ejercicios
exercise_submissions         -- Envios de ejercicios
scheduled_missions           -- Misiones programadas
teacher_notes                -- Notas del profesor
engagement_metrics           -- Metricas de engagement
learning_paths               -- Rutas de aprendizaje
mastery_tracking             -- Tracking de maestria
module_completion_tracking   -- Tracking de completacion
progress_snapshots           -- Snapshots de progreso
skill_assessments            -- Evaluaciones de habilidades
user_learning_paths          -- Rutas por usuario

ENUMs:

progress_status      -- 6 estados: not_started, in_progress, completed, needs_review, mastered, abandoned
attempt_result       -- 4 resultados: correct, incorrect, partial, skipped

Patrones observados:

✅ Tracking de progreso con porcentajes
✅ Sesiones de aprendizaje con tiempo
✅ Multiple attempts por ejercicio
✅ Snapshots para analytics historicos
✅ Notas del profesor (feedback)

Aplicabilidad a ERP Generico: ⭐⭐ (BAJA-MEDIA)

Decision: 🔧 ADAPTAR conceptos de tracking

Aprendizajes trasladables:

✅ Patron de "progreso" (aplicable a avance de obra)
✅ Snapshots para historico (aplicable a presupuestos)
✅ Notas/comentarios (aplicable a observaciones de obra)

2.2.5 social_features - Caracteristicas Sociales

Proposito: Amistades, escuelas, aulas, equipos y desafios.

Tablas (~10):

friendships              -- Amistades entre usuarios
schools                  -- Escuelas
classrooms               -- Aulas/Salones
classroom_members        -- Miembros de aulas
teams                    -- Equipos
team_members             -- Miembros de equipos
team_challenges          -- Desafios entre equipos
assignment_classrooms    -- Assignments por aula
peer_challenges          -- Desafios entre pares
challenge_participants   -- Participantes en desafios
challenge_results        -- Resultados de desafios
discussion_threads       -- Hilos de discusion
social_interactions      -- Interacciones sociales
teacher_classrooms       -- Aulas por profesor
user_follows             -- Seguidores

ENUMs:

friendship_status        -- 4 estados: pending, accepted, rejected, blocked
classroom_member_status  -- 4 estados: active, inactive, withdrawn, completed
enrollment_method        -- 4 metodos: teacher_invite, self_enroll, admin_add, bulk_import
team_member_role         -- 3 roles: owner, admin, member
team_challenge_status    -- 5 estados: active, in_progress, completed, failed, cancelled
social_event_type        -- 5 tipos: competition, collaboration, challenge, tournament, workshop

Patrones observados:

✅ Jerarquia: Escuelas → Aulas → Equipos
✅ Amistades con estados
✅ Enrollment con multiples metodos
✅ Desafios competitivos
✅ Roles en equipos

Aplicabilidad a ERP Generico: ⭐⭐⭐ (MEDIA)

Decision: 🔧 ADAPTAR jerarquias organizacionales

Aprendizajes trasladables:

✅ Jerarquia Empresa → Proyecto → Equipo
✅ Miembros con roles
✅ Estados de membresia
✅ Metodos de enrollment (aplicable a asignacion de personal)

2.2.6 content_management - Gestion de Contenido

Proposito: Plantillas de contenido, contenido Marie Curie, archivos multimedia.

Tablas (~6):

content_templates        -- Plantillas reutilizables
marie_curie_content      -- Contenido especifico
media_files              -- Archivos multimedia
content_authors          -- Autores de contenido
content_categories       -- Categorias
content_versions         -- Versionado de contenido
flagged_content          -- Contenido reportado
media_metadata           -- Metadata de archivos

ENUMs:

content_status       -- 4 estados: draft, published, archived, under_review
content_type         -- 6 tipos: video, text, interactive, quiz, game, simulation
media_type           -- 6 tipos: image, video, audio, document, interactive, animation
processing_status    -- 5 estados: uploading, processing, ready, error, optimizing

Patrones observados:

✅ Plantillas reutilizables
✅ Versionado de contenido
✅ Estados de publicacion
✅ Processing status para multimedia

Aplicabilidad a ERP Generico: ⭐⭐⭐ (MEDIA)

Decision: 🔧 ADAPTAR gestion documental

Aprendizajes trasladables:

✅ Plantillas (aplicable a formatos de contratos)
✅ Versionado (aplicable a documentos de obra)
✅ Estados de publicacion (aplicable a aprobaciones)
✅ Metadata de archivos (aplicable a planos, documentos)

2.2.7 audit_logging - Auditoria y Logs

Proposito: Logs de auditoria, actividad de usuarios, metricas de performance.

Tablas (~4):

audit_logs              -- Logs de auditoria
system_logs             -- Logs del sistema
user_activity_logs      -- Actividad de usuarios
performance_metrics     -- Metricas de performance
system_alerts           -- Alertas del sistema
user_activity           -- Actividad agregada

ENUMs:

aggregation_period   -- 5 periodos: daily, weekly, monthly, quarterly, yearly
metric_type          -- 7 tipos: engagement, performance, completion, time_spent, accuracy, streak, social_interaction

Patrones observados:

✅ Auditoria completa de cambios
✅ Logs de actividad de usuarios
✅ Metricas de performance
✅ Agregacion por periodos

Aplicabilidad a ERP Generico: ⭐⭐⭐⭐⭐ (MAXIMA)

Decision: ✅ ADOPTAR COMPLETAMENTE

Critico para ERP:

Auditoria de cambios en presupuestos
Logs de compras y gastos
Tracking de modificaciones
Metricas de performance del sistema

2.2.8 system_configuration - Configuracion del Sistema

Proposito: Configuracion dinamica del sistema, feature flags.

Tablas (~3):

system_settings          -- Settings del sistema
feature_flags            -- Feature flags (A/B testing)
notification_settings    -- Configuracion de notificaciones
api_configuration        -- Configuracion de APIs
environment_config       -- Configuracion por ambiente
tenant_configurations    -- Configuraciones por tenant

Patrones observados:

✅ Settings dinamicos sin redeploy
✅ Feature flags para A/B testing
✅ Configuracion multi-tenant
✅ Configuracion por ambiente

Aplicabilidad a ERP Generico: ⭐⭐⭐⭐⭐ (MAXIMA)

Decision: ✅ ADOPTAR COMPLETAMENTE

Critico para ERP:

Configuracion dinamica sin redeploy
Feature flags para releases graduales
Configuracion por empresa (multi-tenant)

2.2.9 public - Schema Publico

Proposito: Funciones compartidas y utilidades generales.

Objetos (~15):

Funciones de utilidad compartidas
Extensiones PostgreSQL (uuid-ossp, pgcrypto, etc.)
Tipos compartidos

Patrones observados:

✅ Funciones reutilizables
✅ Extensiones centralizadas
✅ Tipos compartidos

Aplicabilidad a ERP Generico: ⭐⭐⭐⭐ (ALTA)

Decision: ✅ ADOPTAR

3. PATRON DE ORGANIZACION INTERNA DE SCHEMAS

Cada schema en GAMILIT sigue una estructura de carpetas estandarizada:

schema_name/
├── _MAP.md                  # Mapa completo del schema (SIMCO)
├── tables/                  # Tablas principales
│   ├── _MAP.md
│   ├── 01-tabla1.sql        # Prefijo numerico para orden
│   ├── 02-tabla2.sql
│   └── ...
├── indexes/                 # Indices optimizados
│   ├── _MAP.md
│   ├── idx_tabla1_campo1.sql
│   └── ...
├── functions/               # Funciones PL/pgSQL
│   ├── _MAP.md
│   ├── 01-funcion1.sql
│   └── ...
├── triggers/                # Triggers
│   ├── _MAP.md
│   ├── 01-trg_tabla1_updated_at.sql
│   └── ...
├── views/                   # Vistas (opcional)
│   ├── _MAP.md
│   └── ...
├── materialized-views/      # Vistas materializadas (opcional)
│   ├── _MAP.md
│   └── ...
├── enums/                   # ENUMs PostgreSQL (opcional)
│   ├── _MAP.md
│   └── ...
├── rls-policies/            # Row Level Security (opcional)
│   ├── _MAP.md
│   ├── 01-enable-rls.sql
│   └── 02-policies.sql
└── seeds/                   # Datos iniciales (opcional)
    ├── _MAP.md
    └── ...

3.1 Ventajas de esta Organizacion

Navegacion facil: Estructura predecible
Documentacion integrada: Archivos _MAP.md en cada nivel
Orden de ejecucion: Prefijos numericos (01-, 02-, etc.)
Separacion de responsabilidades: Un archivo por objeto
Git-friendly: Merges mas faciles
CI/CD-ready: Facil automatizar ejecucion

4. ROW LEVEL SECURITY (RLS)

4.1 Implementacion en GAMILIT

Politicas RLS totales: 159 planeadas, 41 activas

Schemas con RLS:

auth_management - 1 archivo de policies
gamification_system - 8 archivos de policies
educational_content - 2 archivos de policies
progress_tracking - ~2 archivos de policies
social_features - ~2 archivos de policies
Otros schemas - ~3 archivos de policies

4.2 Patron de Implementacion

Archivo 01-enable-rls.sql:

-- Habilitar RLS en todas las tablas del schema
ALTER TABLE schema_name.tabla1 ENABLE ROW LEVEL SECURITY;
ALTER TABLE schema_name.tabla2 ENABLE ROW LEVEL SECURITY;
-- ...

Archivo 02-policies.sql (ejemplo):

-- Policy: Los usuarios solo ven sus propios datos
CREATE POLICY user_own_data ON schema_name.tabla1
  FOR SELECT
  USING (user_id = current_user_id());

-- Policy: Multi-tenant isolation
CREATE POLICY tenant_isolation ON schema_name.tabla1
  FOR ALL
  USING (tenant_id = current_tenant_id());

4.3 Funciones de Contexto

-- Obtener user_id del contexto actual (JWT)
CREATE FUNCTION current_user_id() RETURNS UUID AS $$
  SELECT current_setting('app.current_user_id')::UUID;
$$ LANGUAGE SQL STABLE;

-- Obtener tenant_id del contexto actual
CREATE FUNCTION current_tenant_id() RETURNS UUID AS $$
  SELECT current_setting('app.current_tenant_id')::UUID;
$$ LANGUAGE SQL STABLE;

4.4 Aplicabilidad a ERP Generico

⭐⭐⭐⭐⭐ (MAXIMA)

Decision: ✅ ADOPTAR COMPLETAMENTE

Usos en ERP:

Multi-tenant isolation (empresa por empresa)
Permisos por rol (solo ver presupuestos asignados)
Seguridad a nivel de fila (solo ver propias compras)

5. SISTEMA DE DOCUMENTACION _MAP.md (SIMCO)

5.1 Total de Archivos _MAP.md en GAMILIT

85+ archivos _MAP.md distribuidos jerarquicamente:

gamilit/
├── _MAP.md                                   # Mapa raiz del proyecto
└── database/
    └── ddl/
        └── schemas/
            ├── auth_management/
            │   ├── _MAP.md                   # Mapa del schema
            │   ├── tables/_MAP.md            # Lista de tablas
            │   ├── indexes/_MAP.md           # Lista de indices
            │   ├── functions/_MAP.md         # Lista de funciones
            │   ├── triggers/_MAP.md          # Lista de triggers
            │   └── rls-policies/_MAP.md      # Lista de policies
            ├── gamification_system/
            │   ├── _MAP.md
            │   ├── tables/_MAP.md
            │   └── ... (7 _MAP.md por schema)
            └── ... (9 schemas × ~9 _MAP.md = ~81 archivos)

5.2 Estructura de un _MAP.md

Ejemplo: database/ddl/schemas/auth_management/_MAP.md

# Schema: auth_management

Gestion de autenticacion y autorizacion: usuarios, roles, perfiles, sesiones

## Estructura

- **tables/**: 15 archivos
- **functions/**: 6 archivos
- **triggers/**: 6 archivos
- **indexes/**: 11 archivos
- **rls-policies/**: 1 archivos

**Total:** 39 objetos

## Contenido Detallado

### tables/ (15 archivos)

01-tenants.sql 02-auth_attempts.sql 03-profiles.sql ...


### functions/ (6 archivos)

01-assign_role_to_user.sql 02-get_user_role.sql ...


---

**Ultima actualizacion:** 2025-11-09
**Reorganizacion:** 2025-11-09

5.3 Beneficios del Sistema SIMCO

Navegacion rapida para AI agents
Documentacion estructurada y actualizable
Visibilidad de cambios en Git
Jerarquia clara de objetos
Mantenimiento incremental

5.4 Aplicabilidad a ERP Generico

⭐⭐⭐⭐⭐ (MAXIMA)

Decision: ✅ ADOPTAR COMPLETAMENTE (ya en uso)

6. INDICES Y OPTIMIZACION

6.1 Metricas de Indices en GAMILIT

Total de indices: 279+

Distribucion:

gamification_system: 23 indices
educational_content: 16 indices
auth_management: 11 indices
Otros schemas: ~229 indices

6.2 Patrones de Indexacion Observados

1. Indices en Foreign Keys:

CREATE INDEX idx_user_roles_user_id ON auth_management.user_roles(user_id);
CREATE INDEX idx_user_roles_tenant_id ON auth_management.user_roles(tenant_id);

2. Indices en Campos de Busqueda Frecuente:

CREATE INDEX idx_user_sessions_active ON auth_management.user_sessions(is_active);
CREATE INDEX idx_user_sessions_expires ON auth_management.user_sessions(expires_at);

3. Indices GIN para JSONB y Arrays:

CREATE INDEX idx_user_roles_permissions_gin
  ON auth_management.user_roles
  USING GIN (permissions);

CREATE INDEX idx_achievements_conditions_gin
  ON gamification_system.achievements
  USING GIN (unlock_conditions);

4. Indices Compuestos:

CREATE INDEX idx_user_stats_tenant_level
  ON gamification_system.user_stats(tenant_id, level);

5. Indices de Ordenamiento (Leaderboards):

CREATE INDEX idx_user_stats_global_rank
  ON gamification_system.user_stats(total_xp DESC);

6.3 Aplicabilidad a ERP Generico

⭐⭐⭐⭐⭐ (MAXIMA)

Decision: ✅ ADOPTAR patrones de indexacion

Indices criticos para ERP:

Foreign keys (empresa_id, proyecto_id, etc.)
Campos de busqueda (fechas, estados, montos)
Indices GIN para campos JSONB (metadata, configuraciones)
Indices compuestos para consultas frecuentes

7. FUNCIONES PL/pgSQL

7.1 Metricas de Funciones en GAMILIT

Total de funciones: 50+

Distribucion:

gamification_system: 25 funciones
auth_management: 6 funciones
educational_content: 3 funciones
public: ~10 funciones
Otros schemas: ~6 funciones

7.2 Categorias de Funciones

1. Funciones de Calculo:

-- Calcular nivel desde XP
CREATE FUNCTION gamification_system.calculate_level_from_xp(xp INTEGER)
RETURNS INTEGER AS $$
  -- Logica de calculo
$$ LANGUAGE plpgsql IMMUTABLE;

2. Funciones de Negocio:

-- Procesar completacion de ejercicio
CREATE FUNCTION gamification_system.process_exercise_completion(
  p_user_id UUID,
  p_exercise_id UUID,
  p_score INTEGER
) RETURNS VOID AS $$
  -- Logica compleja: otorgar XP, coins, verificar logros, etc.
$$ LANGUAGE plpgsql;

3. Funciones de Utilidad:

-- Hash de tokens
CREATE FUNCTION auth_management.hash_token(token TEXT)
RETURNS TEXT AS $$
  SELECT encode(digest(token, 'sha256'), 'hex');
$$ LANGUAGE SQL IMMUTABLE;

4. Funciones de Contexto:

-- Obtener user_id actual
CREATE FUNCTION current_user_id() RETURNS UUID AS $$
  SELECT current_setting('app.current_user_id')::UUID;
$$ LANGUAGE SQL STABLE;

7.3 Aplicabilidad a ERP Generico

⭐⭐⭐⭐⭐ (MAXIMA)

Decision: ✅ ADOPTAR uso de funciones PL/pgSQL

Funciones criticas para ERP:

Calculos de presupuesto (aplicar porcentajes, descuentos)
Validaciones de negocio (verificar disponibilidad de presupuesto)
Agregaciones (totales por proyecto, empresa, periodo)
Automatizaciones (generar asientos contables, actualizar inventario)

8. TRIGGERS

8.1 Metricas de Triggers en GAMILIT

Total de triggers: 35+

Distribucion:

gamification_system: 10 triggers
auth_management: 6 triggers
educational_content: 4 triggers
Otros schemas: ~15 triggers

8.2 Patrones de Triggers Observados

1. Auto-actualizar updated_at:

CREATE TRIGGER trg_users_updated_at
  BEFORE UPDATE ON auth_management.users
  FOR EACH ROW
  EXECUTE FUNCTION update_updated_at_column();

2. Auditoria de Cambios:

CREATE TRIGGER trg_audit_profile_changes
  AFTER UPDATE ON auth_management.profiles
  FOR EACH ROW
  EXECUTE FUNCTION log_profile_changes();

3. Inicializacion Automatica:

CREATE TRIGGER trg_initialize_user_stats
  AFTER INSERT ON auth_management.profiles
  FOR EACH ROW
  EXECUTE FUNCTION gamification_system.initialize_user_stats();

4. Validaciones de Negocio:

CREATE TRIGGER trg_check_rank_promotion
  AFTER UPDATE OF total_xp ON gamification_system.user_stats
  FOR EACH ROW
  WHEN (NEW.total_xp > OLD.total_xp)
  EXECUTE FUNCTION gamification_system.check_rank_promotion();

5. Recalculos Automaticos:

CREATE TRIGGER trg_recalculate_level_on_xp_change
  AFTER UPDATE OF total_xp ON gamification_system.user_stats
  FOR EACH ROW
  EXECUTE FUNCTION gamification_system.recalculate_level_on_xp_change();

8.3 Aplicabilidad a ERP Generico

⭐⭐⭐⭐⭐ (MAXIMA)

Decision: ✅ ADOPTAR uso de triggers

Triggers criticos para ERP:

Auto-actualizar updated_at en todas las tablas
Auditoria de cambios en presupuestos y compras
Validaciones de negocio (no exceder presupuesto)
Recalculos automaticos (totales, saldos, inventario)
Notificaciones automaticas (aprobaciones, vencimientos)

9. MATRIZ DE DECISION: ADOPTAR / ADAPTAR / EVITAR

9.1 ADOPTAR COMPLETAMENTE ✅

Patron	Schema(s)	Justificacion	Prioridad
Arquitectura Multi-Schema	Todos	Separacion logica por dominio	P0
Organizacion interna de schemas	Todos	Estructura estandarizada	P0
Sistema SIMCO (_MAP.md)	Todos	Documentacion jerarquica	P0
Row Level Security (RLS)	auth, gamification, etc.	Multi-tenant isolation	P0
Triggers de updated_at	Todos	Auditoria de cambios	P0
Funciones de contexto	auth_management	current_user_id(), current_tenant_id()	P0
Indices en Foreign Keys	Todos	Performance de JOINs	P0
Indices GIN en JSONB	Varios	Busqueda en campos JSONB	P1
Auditoria completa	audit_logging	Logs de cambios	P0
Configuracion dinamica	system_configuration	Settings sin redeploy	P0

9.2 ADAPTAR A CONTEXTO ERP 🔧

Patron	Schema Original	Adaptacion para ERP	Justificacion
Jerarquia organizacional	social_features	Empresa → Proyecto → Equipo	Estructura similar pero diferente contexto
Sistema de assignments	educational_content	Ordenes de trabajo	Concepto trasladable
Sistema de submissions	educational_content	Entregas/Recepciones	Concepto trasladable
Tracking de progreso	progress_tracking	Avance de obra	Concepto trasladable
Snapshots	progress_tracking	Snapshots de presupuestos	Historial de cambios
Notas/Comentarios	progress_tracking	Observaciones de obra	Feedback y seguimiento
Plantillas	content_management	Plantillas de contratos	Reutilizacion de documentos
Versionado	content_management	Versionado de documentos	Control de cambios

9.3 EVITAR / NO APLICABLE ❌

Patron	Schema Original	Razon
Sistema de gamificacion completo	gamification_system	No aplicable a ERP (XP, logros, rangos mayas)
Contenido educativo	educational_content	Especifico de educacion (modulos, ejercicios)
Caracteristicas sociales	social_features	No aplicable (amistades, equipos gaming)
Leaderboards	gamification_system	No aplicable a ERP
Comodines/Power-ups	gamification_system	Especifico de juegos

10. PROPUESTA DE SCHEMAS PARA ERP GENERICO

Basado en el analisis de GAMILIT, se propone la siguiente arquitectura multi-schema para el ERP Generico:

-- 9 Schemas propuestos para ERP Generico

core_system              -- Usuarios, empresas, monedas, configuracion base
  ├── companies          -- Empresas (multi-tenant)
  ├── users              -- Usuarios del sistema
  ├── roles              -- Roles RBAC
  ├── permissions        -- Permisos granulares
  ├── user_sessions      -- Sesiones activas
  ├── currencies         -- Monedas soportadas
  ├── exchange_rates     -- Tasas de cambio
  └── system_settings    -- Configuracion dinamica

accounting               -- Contabilidad completa
  ├── chart_of_accounts  -- Catalogo de cuentas
  ├── journal_entries    -- Asientos contables
  ├── account_balances   -- Saldos de cuentas
  ├── fiscal_periods     -- Periodos fiscales
  ├── tax_rates          -- Impuestos
  └── financial_reports  -- Reportes financieros

budgets                  -- Presupuestos y control
  ├── budgets            -- Presupuestos maestros
  ├── budget_items       -- Partidas presupuestarias
  ├── budget_categories  -- Categorias
  ├── budget_tracking    -- Seguimiento de ejecucion
  ├── budget_snapshots   -- Snapshots historicos
  └── budget_approvals   -- Flujo de aprobaciones

purchasing               -- Compras y proveedores
  ├── suppliers          -- Proveedores
  ├── purchase_orders    -- Ordenes de compra
  ├── purchase_items     -- Items de compra
  ├── receipts           -- Recepciones
  ├── invoices           -- Facturas de proveedores
  └── payments           -- Pagos a proveedores

inventory                -- Inventario y almacenes
  ├── warehouses         -- Almacenes
  ├── products           -- Productos/Materiales
  ├── product_categories -- Categorias de productos
  ├── stock_movements    -- Movimientos de inventario
  ├── stock_balances     -- Saldos de inventario
  └── inventory_snapshots -- Snapshots de inventario

projects                 -- Proyectos y obras
  ├── projects           -- Proyectos/Obras
  ├── project_phases     -- Fases de proyecto
  ├── work_orders        -- Ordenes de trabajo
  ├── project_team       -- Equipo del proyecto
  ├── project_progress   -- Avance de obra
  └── project_documents  -- Documentos del proyecto

human_resources          -- RRHH y nominas
  ├── employees          -- Empleados
  ├── departments        -- Departamentos
  ├── payrolls           -- Nominas
  ├── payroll_items      -- Conceptos de nomina
  ├── attendance         -- Asistencia
  └── employee_benefits  -- Beneficios

audit_logging            -- Auditoria completa
  ├── audit_logs         -- Logs de auditoria
  ├── user_activity      -- Actividad de usuarios
  ├── change_history     -- Historial de cambios
  ├── system_logs        -- Logs del sistema
  └── performance_metrics -- Metricas de performance

system_notifications     -- Notificaciones multi-canal
  ├── notifications      -- Notificaciones
  ├── notification_preferences -- Preferencias
  ├── notification_templates -- Plantillas
  ├── notification_queue -- Cola de envios
  └── user_devices       -- Dispositivos para push

Total schemas: 9 (igual que GAMILIT)

Beneficios:

Separacion logica clara por dominio
Multi-tenancy (isolation por empresa)
Permisos granulares por schema
Escalabilidad (facil agregar nuevos schemas)
Mantenibilidad (cambios aislados)

11. CONCLUSION Y RECOMENDACIONES

11.1 Hallazgos Clave

Arquitectura Multi-Schema es excelente: ⭐⭐⭐⭐⭐
- Separacion logica clara
- Escalabilidad comprobada
- Permisos granulares
- Documentacion estructurada
Row Level Security es critico: ⭐⭐⭐⭐⭐
- Multi-tenant isolation
- Seguridad a nivel de fila
- Implementacion con funciones de contexto
Sistema SIMCO (_MAP.md) es invaluable: ⭐⭐⭐⭐⭐
- 85+ archivos de documentacion jerarquica
- Navegacion rapida para AI agents
- Mantenimiento incremental
Triggers y Funciones PL/pgSQL son potentes: ⭐⭐⭐⭐⭐
- Automatizaciones
- Validaciones de negocio
- Recalculos automaticos

11.2 Recomendaciones Finales

ADOPTAR COMPLETAMENTE ✅ (Prioridad P0)

Arquitectura multi-schema (9 schemas para ERP)
Organizacion interna estandarizada de schemas
Sistema SIMCO de mapas _MAP.md
Row Level Security con funciones de contexto
Triggers de updated_at en todas las tablas
Indices en foreign keys y campos frecuentes
Auditoria completa (audit_logging schema)
Configuracion dinamica (system_configuration schema)

ADAPTAR A CONTEXTO ERP 🔧 (Prioridad P1)

Jerarquia organizacional (Empresa → Proyecto → Equipo)
Sistema de ordenes de trabajo (adaptado de assignments)
Tracking de progreso (adaptado a avance de obra)
Sistema de plantillas (contratos, documentos)
Versionado de documentos

EVITAR ❌

Sistema de gamificacion (no aplicable a ERP)
Contenido educativo (especifico de educacion)
Caracteristicas sociales de gaming

Documento creado: 2025-11-23 Ultima actualizacion: 2025-11-23 Version: 1.0 Estado: Completado Proximo documento: backend-patterns.md

38 KiB Raw Blame History Unescape Escape

Arquitectura de Base de Datos Multi-Schema - GAMILIT

1. VISION GENERAL

1.1 Principios Arquitectonicos

2. LOS 9 SCHEMAS DE GAMILIT

2.1 Resumen Comparativo

2.2 Detalle por Schema

2.2.1 auth_management - Autenticacion y Autorizacion

2.2.2 gamification_system - Sistema de Gamificacion

2.2.3 educational_content - Contenido Educativo

2.2.4 progress_tracking - Seguimiento de Progreso

2.2.5 social_features - Caracteristicas Sociales

2.2.6 content_management - Gestion de Contenido

2.2.7 audit_logging - Auditoria y Logs

2.2.8 system_configuration - Configuracion del Sistema

2.2.9 public - Schema Publico

3. PATRON DE ORGANIZACION INTERNA DE SCHEMAS

3.1 Ventajas de esta Organizacion

4. ROW LEVEL SECURITY (RLS)

4.1 Implementacion en GAMILIT

4.2 Patron de Implementacion

4.3 Funciones de Contexto

4.4 Aplicabilidad a ERP Generico

5. SISTEMA DE DOCUMENTACION _MAP.md (SIMCO)

5.1 Total de Archivos _MAP.md en GAMILIT

5.2 Estructura de un _MAP.md

5.3 Beneficios del Sistema SIMCO

5.4 Aplicabilidad a ERP Generico

6. INDICES Y OPTIMIZACION

6.1 Metricas de Indices en GAMILIT

6.2 Patrones de Indexacion Observados

6.3 Aplicabilidad a ERP Generico

7. FUNCIONES PL/pgSQL

7.1 Metricas de Funciones en GAMILIT

7.2 Categorias de Funciones

7.3 Aplicabilidad a ERP Generico

8. TRIGGERS

8.1 Metricas de Triggers en GAMILIT

8.2 Patrones de Triggers Observados

8.3 Aplicabilidad a ERP Generico

9. MATRIZ DE DECISION: ADOPTAR / ADAPTAR / EVITAR

9.1 ADOPTAR COMPLETAMENTE ✅

9.2 ADAPTAR A CONTEXTO ERP 🔧

9.3 EVITAR / NO APLICABLE ❌

10. PROPUESTA DE SCHEMAS PARA ERP GENERICO

11. CONCLUSION Y RECOMENDACIONES

11.1 Hallazgos Clave

11.2 Recomendaciones Finales

ADOPTAR COMPLETAMENTE ✅ (Prioridad P0)

ADAPTAR A CONTEXTO ERP 🔧 (Prioridad P1)

EVITAR ❌

38 KiB

Raw Blame History