workspace/projects/gamilit/orchestration/agentes/architecture-analyst/PLAN-IMPLEMENTACION-PORTAL-ADMIN-2025-11-28.md

PLAN DE IMPLEMENTACIÓN: CORRECCIONES PORTAL ADMIN

Fecha: 2025-11-28 Basado en: REPORTE-ANALISIS-PORTAL-ADMIN-2025-11-28.md Estado: FASE 2 - PLANEACIÓN

---

RESUMEN DEL PLAN

Este plan aborda las correcciones necesarias para completar el portal de administración. Se organiza en 4 grupos de tareas ordenados por prioridad y dependencias.

Alcance Total

• Tareas: 9 principales
• Subtareas: 25
• SP Estimados: 34
• Agentes a orquestar: Database-Agent, Backend-Agent, Frontend-Agent

---

GRUPO 1: CORRECCIONES CRÍTICAS (Prioridad ALTA)

TAREA 1.1: Completar AdminSettingsPage

Objetivo: Habilitar la página de configuración del sistema que actualmente está deshabilitada por feature flag.

Dependencias: Ninguna

Subtareas:

#	Subtarea	Agente	Archivos	Descripción
1.1.1	Completar useSettings hook	Frontend-Agent	hooks/useSettings.ts	Implementar conexión real con endpoints /admin/system/config
1.1.2	Habilitar GeneralSettings	Frontend-Agent	components/settings/GeneralSettings.tsx	Verificar componente funciona correctamente
1.1.3	Habilitar SecuritySettings	Frontend-Agent	components/settings/SecuritySettings.tsx	Verificar componente funciona correctamente
1.1.4	Activar feature flag	Frontend-Agent	pages/AdminSettingsPage.tsx	Cambiar SHOW_CONTENT = true
1.1.5	Validar integración	Frontend-Agent	-	Test manual de funcionalidad completa

Criterios de Aceptación:

• Hook useSettings conecta con backend sin errores
• Tab General muestra y permite modificar configuraciones
• Tab Security muestra y permite modificar políticas
• Cambios se persisten correctamente
• No hay errores en consola

---

TAREA 1.2: Implementar Endpoint restore-defaults (Gamificación)

Objetivo: Crear endpoint faltante para restaurar valores por defecto de gamificación.

Dependencias: Ninguna

Subtareas:

#	Subtarea	Agente	Archivos	Descripción
1.2.1	Crear endpoint en controller	Backend-Agent	admin-gamification-config.controller.ts	POST /admin/gamification/restore-defaults
1.2.2	Implementar lógica en service	Backend-Agent	gamification-config.service.ts	Método para restaurar parámetros a valores default
1.2.3	Crear DTO de respuesta	Backend-Agent	dto/gamification-config/	DTO para respuesta del restore
1.2.4	Actualizar hook frontend	Frontend-Agent	hooks/useGamificationConfig.ts	Conectar con nuevo endpoint
1.2.5	Habilitar RestoreDefaultsDialog	Frontend-Agent	components/gamification/RestoreDefaultsDialog.tsx	Verificar funcionalidad

Criterios de Aceptación:

• Endpoint responde correctamente
• Parámetros se restauran a valores default de BD
• Frontend muestra confirmación de éxito
• No se pierden overrides de tenant/classroom

---

TAREA 1.3: Resolver AdminAdvancedPage

Objetivo: Decidir e implementar solución para página Advanced (actualmente placeholder).

Dependencias: Ninguna

Opciones:

• Opción A: Implementar funcionalidades (Multi-tenant, Feature Flags UI, A/B Testing)
• Opción B: Remover del menú hasta Fase 2

DECISIÓN RECOMENDADA: Opción B - Remover temporalmente

Subtareas (Opción B):

#	Subtarea	Agente	Archivos	Descripción
1.3.1	Ocultar del sidebar	Frontend-Agent	GamilitSidebar.tsx	Comentar o condicionar item 'advanced'
1.3.2	Mantener ruta pero mostrar "Coming Soon"	Frontend-Agent	AdminAdvancedPage.tsx	Mostrar mensaje informativo
1.3.3	Documentar decisión	-	docs/97-adr/	Crear ADR si no existe

Criterios de Aceptación:

• Item no aparece en menú sidebar
• Ruta directa muestra mensaje "Coming Soon"
• No hay enlaces rotos en el portal

---

GRUPO 2: CORRECCIONES DE ESTABILIDAD (Prioridad MEDIA)

TAREA 2.1: Validaciones AdminInstitutionsPage

Objetivo: Agregar validaciones defensivas para BUG-ADMIN-006 y BUG-ADMIN-007.

Dependencias: Ninguna

Subtareas:

#	Subtarea	Agente	Archivos	Descripción
2.1.1	Validar estructura de respuesta	Frontend-Agent	hooks/useOrganizations.ts	Agregar checks de null/undefined
2.1.2	Validar datos antes de render	Frontend-Agent	pages/AdminInstitutionsPage.tsx	Defensive rendering
2.1.3	Agregar error boundaries	Frontend-Agent	pages/AdminInstitutionsPage.tsx	Manejo de errores graceful

Criterios de Aceptación:

• Página no crashea con datos incompletos
• Mensajes de error informativos al usuario
• Logs de errores para debugging

---

TAREA 2.2: Validaciones AdminGamificationPage

Objetivo: Agregar validaciones defensivas para BUG-ADMIN-008 y BUG-ADMIN-009.

Dependencias: Tarea 1.2 (restore-defaults)

Subtareas:

#	Subtarea	Agente	Archivos	Descripción
2.2.1	Validar ranks data	Frontend-Agent	hooks/useGamificationConfig.ts	Checks de Array.isArray, null
2.2.2	Validar parameters data	Frontend-Agent	hooks/useGamificationConfig.ts	Checks de estructura
2.2.3	Fallbacks en componentes	Frontend-Agent	pages/AdminGamificationPage.tsx	Valores por defecto seguros

Criterios de Aceptación:

• Página no crashea con datos incompletos
• Fallbacks razonables para datos faltantes
• Console warnings para datos inesperados

---

TAREA 2.3: Corrección AdminContentPage (Menor)

Objetivo: Reemplazar datos mock de gamificación con hook real.

Dependencias: Ninguna

Subtareas:

#	Subtarea	Agente	Archivos	Descripción
2.3.1	Usar useUserGamification	Frontend-Agent	pages/AdminContentPage.tsx	Reemplazar gamificationData mock con hook real

Criterios de Aceptación:

• Datos de gamificación provienen del hook real
• No hay datos mock hardcodeados
• Página funciona igual que antes

---

TAREA 2.4: Persistencia de Reportes

Objetivo: Cambiar almacenamiento de reportes de memoria a persistencia.

Dependencias: Ninguna

Subtareas:

#	Subtarea	Agente	Archivos	Descripción
2.4.1	Crear tabla admin_reports	Database-Agent	DDL nuevo	Tabla para persistir reportes
2.4.2	Crear entity TypeORM	Backend-Agent	entities/admin-report.entity.ts	Entity para nueva tabla
2.4.3	Refactorizar service	Backend-Agent	admin-reports.service.ts	Usar BD en lugar de Map
2.4.4	Actualizar DTOs si necesario	Backend-Agent	dto/reports/	Ajustar estructuras

Criterios de Aceptación:

• Reportes persisten después de reinicio
• CRUD completo funciona
• Cleanup automático de reportes antiguos (>30 días)

---

GRUPO 3: LIMPIEZA DE CÓDIGO (Prioridad BAJA)

TAREA 3.1: Eliminar Duplicado AdminDashboard

Objetivo: Investigar y resolver duplicidad entre AdminDashboard.tsx y AdminDashboardPage.tsx.

Dependencias: Ninguna

Subtareas:

#	Subtarea	Agente	Archivos	Descripción
3.1.1	Investigar uso actual	Frontend-Agent	-	Buscar imports de AdminDashboard.tsx
3.1.2	Determinar cuál es activo	Frontend-Agent	App.tsx, rutas	Verificar cuál se usa en routing
3.1.3	Eliminar duplicado	Frontend-Agent	-	Remover archivo no usado
3.1.4	Actualizar imports	Frontend-Agent	-	Si hay referencias, actualizar

Criterios de Aceptación:

• Solo existe un componente de Dashboard
• No hay imports rotos
• Funcionalidad preservada

---

GRUPO 4: DOCUMENTACIÓN

TAREA 4.1: Actualizar Documentación

Objetivo: Reflejar cambios realizados en la documentación del proyecto.

Dependencias: Todas las tareas anteriores

Subtareas:

#	Subtarea	Agente	Archivos	Descripción
4.1.1	Actualizar inventario frontend	-	FRONTEND_INVENTORY.yml	Reflejar cambios
4.1.2	Actualizar inventario backend	-	BACKEND_INVENTORY.yml	Reflejar cambios
4.1.3	Actualizar status portal admin	-	docs/90-transversal/	Actualizar estado
4.1.4	Crear ADR si necesario	-	docs/97-adr/	Documentar decisiones

---

ORDEN DE EJECUCIÓN

PARALELO GRUPO 1 (pueden ejecutarse simultáneamente):
├── TAREA 1.1: AdminSettingsPage (Frontend-Agent)
├── TAREA 1.2: Endpoint restore-defaults (Backend-Agent)
└── TAREA 1.3: AdminAdvancedPage (Frontend-Agent)

SECUENCIAL GRUPO 2 (después de Grupo 1):
├── TAREA 2.1: Validaciones Institutions (Frontend-Agent)
├── TAREA 2.2: Validaciones Gamification (Frontend-Agent) [depende de 1.2]
├── TAREA 2.3: Corrección ContentPage (Frontend-Agent)
└── TAREA 2.4: Persistencia Reportes (Database-Agent → Backend-Agent)

PARALELO GRUPO 3:
└── TAREA 3.1: Eliminar duplicado Dashboard (Frontend-Agent)

FINAL GRUPO 4:
└── TAREA 4.1: Documentación (Architecture-Analyst)

---

MATRIZ DE AGENTES POR TAREA

Tarea	Database-Agent	Backend-Agent	Frontend-Agent
1.1 AdminSettingsPage	-	-	✅ Principal
1.2 restore-defaults	-	✅ Principal	✅ Secundario
1.3 AdminAdvancedPage	-	-	✅ Principal
2.1 Valid. Institutions	-	-	✅ Principal
2.2 Valid. Gamification	-	-	✅ Principal
2.3 ContentPage mock	-	-	✅ Principal
2.4 Persist. Reportes	✅ Principal	✅ Secundario	-
3.1 Eliminar duplicado	-	-	✅ Principal
4.1 Documentación	-	-	-

---

ESTIMACIÓN DE ESFUERZO

Grupo	Tareas	SP	Tiempo Est.	Agentes
Grupo 1 (Críticas)	3	16	2-3 días	3 paralelo
Grupo 2 (Estabilidad)	4	14	1-2 días	4 secuencial
Grupo 3 (Limpieza)	1	2	0.5 días	1
Grupo 4 (Docs)	1	2	0.5 días	0 (manual)
TOTAL	9	34	4-6 días	Máx 5 paralelo

---

CRITERIOS DE ÉXITO GLOBAL

Al finalizar todas las tareas:

1. Funcionalidad:

   • Todas las 14 páginas del admin funcionan correctamente
   • No hay páginas con feature flags deshabilitados
   • Todos los endpoints tienen su correspondiente UI

2. Estabilidad:

   • No hay crasheos por datos incompletos
   • Validaciones defensivas en todos los hooks críticos
   • Error handling graceful en todas las páginas

3. Persistencia:

   • Reportes persisten después de reiniciar servidor
   • Configuraciones se guardan correctamente

4. Código:

   • No hay componentes duplicados
   • No hay imports rotos
   • Código limpio y mantenible

5. Documentación:

   • Inventarios actualizados
   • ADRs documentan decisiones importantes
   • Status del portal refleja realidad

---

Plan creado por: Architecture-Analyst Fecha: 2025-11-28 Próximo paso: FASE 3 - Validación de planeación vs análisis