workspace/projects/gamilit/orchestration/agentes/tech-leader/PLAN-IMPLEMENTACION-FLUJO-USUARIOS-2025-12-15.md

PLAN DE IMPLEMENTACIÓN - FLUJO DE CREACIÓN DE USUARIOS

Tech-Leader: Claude Opus 4.5 Proyecto: GAMILIT Fecha: 2025-12-15 Estado: FASE 3 - Planeación de Implementaciones

---

1. RESUMEN EJECUTIVO

Objetivo

Implementar los siguientes cambios en el sistema GAMILIT:

1. Crear School Default "Sistema - Por Asignar"
2. Asignar admin (admin@gamilit.com) a la School Default
3. Corregir el problema de "Nunca" en último acceso (seeds)

Corrección del Análisis Inicial

Item	Análisis Inicial	Análisis Profundo	Acción
AuthService.register()	NO IMPLEMENTADO	✅ SÍ IMPLEMENTADO	No requiere cambios
AuthService.login()	NO IMPLEMENTADO	✅ SÍ IMPLEMENTADO	No requiere cambios
last_sign_in_at update	No se actualiza	✅ SÍ SE ACTUALIZA	Problema es datos NULL en seeds
School Default	NO EXISTE	NO EXISTE	CREAR
Admin school_id	NULL	NULL	ASIGNAR

---

2. CAMBIOS A IMPLEMENTAR

2.1 CAPA DATABASE - PRIORIDAD P0

Cambio DB-001: Crear Seed de School Default

Archivo a crear: apps/database/seeds/prod/social_features/00-schools-default.sql

Contenido:

-- School Default: "Sistema - Por Asignar"
-- UUID: 99999999-9999-9999-9999-999999999999
-- Código: SYSTEM-UNASSIGNED
-- Propósito: Escuela de sistema para usuarios pendientes de asignación

Campos requeridos (según DDL social_features.schools):

• id: 99999999-9999-9999-9999-999999999999
• tenant_id: (variable, obtener de GAMILIT Platform)
• name: "Sistema - Por Asignar"
• code: "SYSTEM-UNASSIGNED"
• short_name: "Sistema"
• description: "Escuela de sistema para asignación pendiente"
• is_active: true
• metadata: {"is_system": true, "is_default": true}

Cambio DB-002: Actualizar Classroom Default

Archivo: apps/database/seeds/prod/social_features/02-classrooms.sql

Acción: Modificar el classroom default para apuntar a la nueva School Default

• school_id: Cambiar de 50000000-0000-0000-0000-000000000001 (Marie Curie) a 99999999-9999-9999-9999-999999999999 (System)

Cambio DB-003: Asignar School a Admin

Archivo a crear: apps/database/seeds/prod/auth_management/08-assign-admin-schools.sql

Contenido:

-- Asignar escuela default a usuarios admin
UPDATE auth_management.profiles
SET school_id = '99999999-9999-9999-9999-999999999999'
WHERE role IN ('admin_teacher', 'super_admin')
  AND school_id IS NULL;

Cambio DB-004: Actualizar last_sign_in_at en Seeds (OPCIONAL)

Archivos: apps/database/seeds/prod/auth/01-demo-users.sql

Acción: Agregar valor default para last_sign_in_at

-- Para usuarios demo, establecer last_sign_in_at = created_at
-- Esto evita que muestren "Nunca" en el portal admin
last_sign_in_at = gamilit.now_mexico()

Nota: Este cambio es cosmético para demo. En producción real, los usuarios harán login.

---

2.2 CAPA BACKEND - SIN CAMBIOS REQUERIDOS

El análisis profundo confirmó que:

• ✅ AuthService.register() implementado correctamente
• ✅ AuthService.login() implementado correctamente
• ✅ last_sign_in_at se actualiza en ambos métodos
• ✅ AdminUsersService.listUsers() retorna el campo correctamente

NO SE REQUIEREN CAMBIOS EN BACKEND

---

2.3 CAPA FRONTEND - SIN CAMBIOS REQUERIDOS

El análisis profundo confirmó que:

• ✅ transformUser() mapea last_sign_in_at → lastLogin correctamente
• ✅ useUserManagement procesa el campo correctamente
• ✅ AdminUsersPage renderiza "Nunca" solo cuando el valor es NULL (esperado)

NO SE REQUIEREN CAMBIOS EN FRONTEND

---

3. ORDEN DE IMPLEMENTACIÓN

FASE 1: Database Seeds (15 min)
├─ 1.1 Crear 00-schools-default.sql (School Default)
├─ 1.2 Actualizar 02-classrooms.sql (Classroom apunta a School Default)
├─ 1.3 Crear 08-assign-admin-schools.sql (Admin → School Default)
└─ 1.4 (Opcional) Actualizar 01-demo-users.sql (last_sign_in_at)

FASE 2: Validación (10 min)
├─ 2.1 Ejecutar drop-and-recreate-database.sh
├─ 2.2 Verificar escuela default creada
├─ 2.3 Verificar admin tiene school_id asignado
├─ 2.4 Verificar classroom default apunta a school default
└─ 2.5 Verificar último acceso en admin/users

FASE 3: Documentación (5 min)
├─ 3.1 Actualizar DATABASE_INVENTORY.yml
├─ 3.2 Actualizar SEEDS_INVENTORY.yml
└─ 3.3 Agregar entrada a CHANGELOG.md

---

4. ARCHIVOS A CREAR/MODIFICAR

Crear (3 archivos):

Archivo	Prioridad	Descripción
seeds/prod/social_features/00-schools-default.sql	P0	School Default
seeds/dev/social_features/00-schools-default.sql	P0	(copia para dev)
seeds/prod/auth_management/08-assign-admin-schools.sql	P0	Asignar admin

Modificar (2 archivos):

Archivo	Prioridad	Cambio
seeds/prod/social_features/02-classrooms.sql	P0	school_id del classroom default
apps/database/create-database.sh	P1	Agregar nuevo seed en orden

---

5. DEPENDENCIAS IDENTIFICADAS

Orden de Ejecución de Seeds:

1. auth_management/01-tenants.sql        (tenant_id)
2. social_features/00-schools-default.sql (school default) ← NUEVO
3. social_features/01-schools.sql        (escuelas demo)
4. social_features/02-classrooms.sql     (classrooms)
5. auth/01-demo-users.sql                (usuarios)
6. auth_management/04-profiles-complete.sql (profiles)
7. auth_management/08-assign-admin-schools.sql ← NUEVO
8. social_features/03-classroom-members.sql (membresías)

FKs Involucradas:

• profiles.school_id → schools.id (FK diferida, Fase 9.5)
• classrooms.school_id → schools.id
• classrooms.teacher_id → profiles.id

---

6. VALIDACIÓN POST-IMPLEMENTACIÓN

Queries de Verificación:

-- 1. Verificar School Default existe
SELECT * FROM social_features.schools WHERE code = 'SYSTEM-UNASSIGNED';

-- 2. Verificar Classroom Default apunta a School Default
SELECT c.name, c.code, s.name as school_name
FROM social_features.classrooms c
JOIN social_features.schools s ON c.school_id = s.id
WHERE c.code = 'DEFAULT';

-- 3. Verificar Admin tiene school_id
SELECT email, role, school_id
FROM auth_management.profiles
WHERE role IN ('admin_teacher', 'super_admin');

-- 4. Verificar último acceso de usuarios demo
SELECT email, last_sign_in_at
FROM auth.users
WHERE email LIKE '%@gamilit.com';

---

7. RIESGOS Y MITIGACIONES

Riesgo	Impacto	Mitigación
Orden incorrecto de seeds	FK violation	Validar con drop-and-recreate completo
Classroom default sin school	Estudiantes huérfanos	Verificar FK antes de cambio
Scripts no idempotentes	Error en re-ejecución	Usar ON CONFLICT DO UPDATE

---

8. SIGUIENTE PASO

FASE 4: Validación de Planeación

• Verificar que no falten objetos dependientes
• Confirmar orden de seeds en create-database.sh
• Validar estructura de School Default contra DDL

---

Fin del Plan de Implementación - FASE 3 Documento generado por Tech-Leader - 2025-12-15