workspace/projects/gamilit/orchestration/analisis-database-2025-12-26/00-PLAN-ANALISIS-DATABASE.md

PLAN DE ANALISIS DE BASE DE DATOS - GAMILIT

Fecha: 2025-12-26 Autor: Requirements-Analyst (Claude Opus 4.5) Proyecto: GAMILIT - Sistema de Gamificacion Educativa Version: 1.0.0

---

RESUMEN EJECUTIVO

Este documento define el plan de analisis exhaustivo de la base de datos del proyecto GAMILIT, incluyendo validacion de objetos DDL, coherencia de UUIDs, alineacion con backend/frontend, y verificacion de dependencias.

---

FASE 1: PLANEACION Y DEFINICION DE ALCANCE

1.1 Alcance del Analisis

Objetos de Base de Datos a Validar

Categoria	Cantidad Esperada	Fuente
Schemas	15-16	DATABASE_INVENTORY.yml
Tablas	126-132	DDL/tables/
Views	17	DDL/views/
Materialized Views	11	DDL/materialized-views/
Funciones	150-214	DDL/functions/
Triggers	91-111	DDL/triggers/
Enums	42	DDL/enums/
Indexes	21	DDL/indexes/
RLS Policies	185	DDL/rls-policies/
Foreign Keys	208	DDL/tables/ (embedded)

Schemas a Analizar

1. admin_dashboard - Dashboard administrativo
2. audit_logging - Auditoria y logging
3. auth - Autenticacion base
4. auth_management - Gestion de usuarios
5. communication - Mensajeria maestro-estudiante
6. content_management - Gestion de contenido
7. educational_content - Contenido educativo
8. gamification_system - Sistema de gamificacion
9. gamilit - Funciones compartidas
10. lti_integration - LTI 1.3
11. notifications - Sistema de notificaciones
12. progress_tracking - Seguimiento de progreso
13. public - Schema publico
14. social_features - Caracteristicas sociales
15. storage - Almacenamiento
16. system_configuration - Configuracion del sistema

1.2 Criterios de Validacion

A. Integridad Estructural DDL

Criterio	Descripcion	Severidad
CRI-DDL-001	Todas las tablas tienen PRIMARY KEY	CRITICO
CRI-DDL-002	FKs referencian tablas existentes	CRITICO
CRI-DDL-003	Triggers referencian funciones existentes	CRITICO
CRI-DDL-004	Indexes no estan duplicados	ALTO
CRI-DDL-005	ENUMs usados existen y estan definidos	ALTO
CRI-DDL-006	RLS policies referencian columnas validas	MEDIO

B. Integridad de Datos (Seeds)

Criterio	Descripcion	Severidad
CRI-SEED-001	UUIDs son validos (formato UUID v4)	CRITICO
CRI-SEED-002	FKs en seeds referencian registros existentes	CRITICO
CRI-SEED-003	No hay UUIDs duplicados entre tablas relacionadas	ALTO
CRI-SEED-004	Datos requeridos (NOT NULL) estan presentes	ALTO
CRI-SEED-005	Valores ENUM son validos	MEDIO

C. Coherencia DB-Backend

Criterio	Descripcion	Severidad
CRI-BE-001	Cada tabla tiene entity correspondiente	ALTO
CRI-BE-002	Columnas de tabla mapeadas en entity	ALTO
CRI-BE-003	Tipos de datos son compatibles	MEDIO
CRI-BE-004	Relaciones (FK) reflejadas en entities	MEDIO

D. Coherencia Backend-Frontend

Criterio	Descripcion	Severidad
CRI-FE-001	Endpoints backend tienen API services frontend	ALTO
CRI-FE-002	DTOs backend tienen tipos TypeScript frontend	MEDIO
CRI-FE-003	Rutas frontend tienen endpoints backend	MEDIO

1.3 Estructura de Entregables

orchestration/analisis-database-2025-12-26/
├── 00-PLAN-ANALISIS-DATABASE.md          # Este documento
├── 01-FASE-1-PLANEACION/
│   ├── ALCANCE-DETALLADO.md
│   └── CRITERIOS-VALIDACION.md
├── 02-FASE-2-EJECUCION/
│   ├── ANALISIS-DDL-OBJETOS.md
│   ├── ANALISIS-SEEDS-UUIDS.md
│   ├── COHERENCIA-DB-BACKEND.md
│   └── COHERENCIA-BACKEND-FRONTEND.md
├── 03-FASE-3-DISCREPANCIAS/
│   ├── REPORTE-DISCREPANCIAS.md
│   └── PLAN-CORRECCIONES.md
├── 04-FASE-4-VALIDACION/
│   └── VALIDACION-PLAN-CORRECCIONES.md
└── 05-FASE-5-EJECUCION/
    └── LOG-IMPLEMENTACION.md

---

FASE 2: EJECUCION DEL ANALISIS

2.1 Analisis de Objetos DDL

Subagente: Database-Analyst

Tareas:

1. Contar y listar todos los objetos DDL por schema
2. Validar sintaxis SQL de archivos DDL
3. Verificar dependencias entre objetos (FKs, triggers→functions)
4. Identificar objetos duplicados o huerfanos
5. Comparar conteos reales vs inventario documentado

Archivos a Analizar:

• /apps/database/ddl/schemas/*/tables/*.sql
• /apps/database/ddl/schemas/*/functions/*.sql
• /apps/database/ddl/schemas/*/triggers/*.sql
• /apps/database/ddl/schemas/*/indexes/*.sql
• /apps/database/ddl/schemas/*/views/*.sql
• /apps/database/ddl/schemas/*/enums/*.sql
• /apps/database/ddl/schemas/*/rls-policies/*.sql

2.2 Analisis de Seeds y UUIDs

Subagente: Data-Validator

Tareas:

1. Extraer todos los UUIDs de archivos de seeds
2. Validar formato UUID v4 (8-4-4-4-12)
3. Verificar unicidad de UUIDs por tabla
4. Validar integridad referencial entre seeds
5. Identificar UUIDs hardcodeados vs generados

Archivos a Analizar:

• /apps/database/seeds/dev/*.sql
• /apps/database/seeds/prod/*.sql

2.3 Coherencia DB-Backend

Subagente: Integration-Analyst

Tareas:

1. Mapear tablas DDL → entities TypeORM/Prisma
2. Validar columnas de tabla vs propiedades de entity
3. Verificar tipos de datos compatibles
4. Identificar tablas sin entity correspondiente
5. Identificar entities sin tabla correspondiente

Archivos a Analizar:

• /apps/backend/src/modules/*/entities/*.ts
• /apps/database/ddl/schemas/*/tables/*.sql

2.4 Coherencia Backend-Frontend

Subagente: API-Analyst

Tareas:

1. Listar endpoints backend (controllers)
2. Mapear endpoints → API services frontend
3. Verificar DTOs backend vs tipos TypeScript frontend
4. Identificar endpoints sin consumidor frontend
5. Identificar llamadas frontend sin endpoint backend

Archivos a Analizar:

• /apps/backend/src/modules/*/controllers/*.ts
• /apps/frontend/src/services/api/**/*.ts

---

FASE 3: PLANEACION DE CORRECCIONES

3.1 Clasificacion de Discrepancias

Prioridad	Descripcion	SLA Correccion
P0	Errores criticos que impiden operacion	Inmediato
P1	Errores que afectan funcionalidad	1-2 dias
P2	Inconsistencias menores	1 semana
P3	Mejoras de documentacion	Backlog

3.2 Formato de Reporte de Discrepancia

discrepancia:
  id: "DISC-XXX"
  tipo: "DDL|SEED|DB-BE|BE-FE"
  criterio_violado: "CRI-XXX-XXX"
  severidad: "CRITICO|ALTO|MEDIO|BAJO"
  descripcion: "..."
  ubicacion:
    archivo: "..."
    linea: X
  impacto: "..."
  correccion_propuesta: "..."
  dependencias: ["DISC-YYY"]

---

FASE 4: VALIDACION DEL PLAN

4.1 Checklist de Validacion

• Todas las discrepancias tienen correccion propuesta
• Correcciones no introducen nuevas dependencias rotas
• Orden de implementacion respeta dependencias
• Rollback plan definido para cada correccion
• Tests de regresion identificados

4.2 Matriz de Impacto

Correccion	Archivos Impactados	Tests Requeridos
...	...	...

---

FASE 5: EJECUCION DE CORRECCIONES

5.1 Protocolo de Implementacion

1. Crear branch de feature
2. Implementar correccion segun plan
3. Ejecutar tests locales
4. Actualizar documentacion/inventarios
5. Code review
6. Merge a develop

5.2 Registro de Implementacion

Cada correccion implementada se registrara en: 05-FASE-5-EJECUCION/LOG-IMPLEMENTACION.md

---

PROXIMOS PASOS

1. Aprobar este plan - Confirmar alcance y criterios
2. Iniciar FASE 2 - Ejecutar analisis con subagentes
3. Generar reportes - Documentar hallazgos por categoria
4. Priorizar correcciones - Clasificar por severidad
5. Ejecutar correcciones - Implementar segun plan

---

REFERENCIAS

• orchestration/inventarios/DATABASE_INVENTORY.yml
• orchestration/inventarios/BACKEND_INVENTORY.yml
• orchestration/inventarios/FRONTEND_INVENTORY.yml
• orchestration/inventarios/MASTER_INVENTORY.yml
• apps/database/README.md

---

Estado: PENDIENTE APROBACION Siguiente Accion: Confirmar plan e iniciar FASE 2