erp-core/docs/01-analisis-referencias/gamilit/database-architecture.md

# 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

1. **Domain-Driven Design (DDD):** Cada schema representa un contexto delimitado (bounded context)
2. **Separation of Concerns:** Objetos agrupados por responsabilidad funcional
3. **Principle of Least Privilege:** Permisos granulares por schema
4. **Scalability First:** Facil agregar nuevos dominios sin afectar existentes
5. **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):**
```sql
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):**
```sql
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):**
```sql
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):**
```sql
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):**
```sql
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):**
```sql
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):**
```sql
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):**
```sql
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):**
```sql
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):**
```sql
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):**
```sql
bloom_taxonomy       -- Taxonomia de Bloom educativa
difficulty_level     -- 8 niveles CEFR: beginner (A1), elementary (A2), ..., native
exercise_mechanic    -- 33 mecanicas educativas diferentes
```

**Funciones (3):**
```sql
calculate_learning_path()         -- Calcular ruta de aprendizaje
get_recommended_missions()        -- Recomendar misiones
validate_exercise_structure()     -- Validar estructura de ejercicio
```

**Triggers (4):**
```sql
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):**
```sql
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:**
```sql
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):**
```sql
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:**
```sql
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):**
```sql
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:**
```sql
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):**
```sql
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:**
```sql
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):**
```sql
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

1. **Navegacion facil:** Estructura predecible
2. **Documentacion integrada:** Archivos _MAP.md en cada nivel
3. **Orden de ejecucion:** Prefijos numericos (01-, 02-, etc.)
4. **Separacion de responsabilidades:** Un archivo por objeto
5. **Git-friendly:** Merges mas faciles
6. **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:**
```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):**
```sql
-- 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

```sql
-- 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`

```markdown
# 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

1. **Navegacion rapida para AI agents**
2. **Documentacion estructurada y actualizable**
3. **Visibilidad de cambios en Git**
4. **Jerarquia clara de objetos**
5. **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:**
```sql
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:**
```sql
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:**
```sql
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:**
```sql
CREATE INDEX idx_user_stats_tenant_level
  ON gamification_system.user_stats(tenant_id, level);
```

**5. Indices de Ordenamiento (Leaderboards):**
```sql
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:**
```sql
-- 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:**
```sql
-- 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:**
```sql
-- 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:**
```sql
-- 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:**
```sql
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:**
```sql
CREATE TRIGGER trg_audit_profile_changes
  AFTER UPDATE ON auth_management.profiles
  FOR EACH ROW
  EXECUTE FUNCTION log_profile_changes();
```

**3. Inicializacion Automatica:**
```sql
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:**
```sql
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:**
```sql
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:

```sql
-- 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

1. **Arquitectura Multi-Schema es excelente:** ⭐⭐⭐⭐⭐
   - Separacion logica clara
   - Escalabilidad comprobada
   - Permisos granulares
   - Documentacion estructurada

2. **Row Level Security es critico:** ⭐⭐⭐⭐⭐
   - Multi-tenant isolation
   - Seguridad a nivel de fila
   - Implementacion con funciones de contexto

3. **Sistema SIMCO (_MAP.md) es invaluable:** ⭐⭐⭐⭐⭐
   - 85+ archivos de documentacion jerarquica
   - Navegacion rapida para AI agents
   - Mantenimiento incremental

4. **Triggers y Funciones PL/pgSQL son potentes:** ⭐⭐⭐⭐⭐
   - Automatizaciones
   - Validaciones de negocio
   - Recalculos automaticos

### 11.2 Recomendaciones Finales

#### ADOPTAR COMPLETAMENTE ✅ (Prioridad P0)

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

#### ADAPTAR A CONTEXTO ERP 🔧 (Prioridad P1)

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

#### EVITAR ❌

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

---

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