workspace/PLAN-ACTUALIZACIONES-MAYORES.md

Plan de Actualizaciones Mayores - Gamilit & Trading-Platform

Resumen Ejecutivo

Este plan detalla la migración de dependencias con breaking changes significativos para los proyectos gamilit y trading-platform.

---

1. ZOD 3.x → 4.x (GAMILIT Frontend)

Estado Actual

• Versión actual: 4.1.12 (ya está en v4 en package.json)
• Archivos afectados: ~30+ archivos con schemas de validación
• Uso principal: @hookform/resolvers/zod para validación de formularios

Breaking Changes Relevantes

Cambio	Impacto	Acción Requerida
message → error param	Alto	Buscar y reemplazar
.default() behavior change	Medio	Verificar schemas con defaults
ZodError.errors → ZodError.issues	Bajo	Verificar manejo de errores
Import paths (zod/v4)	Bajo	Mantener zod (es v4 default)

Análisis del Código

// Patrones encontrados que necesitan revisión:
z.string().min(1, 'El correo electrónico es requerido')  // OK - sin cambios
z.enum(['student', 'admin_teacher'], { message: '...' }) // CAMBIO: message → error
.refine((val) => val === true, { message: '...' })       // OK - refine sigue igual

Tareas

1. Ejecutar codemod npx zod-v3-to-v4
2. Buscar { message: en schemas y cambiar a { error:
3. Verificar schemas con .default() o .catch()
4. Ejecutar tests y build

Riesgo: BAJO (ya está en v4, solo ajustes menores)

---

2. STRIPE 14.x → 20.x (Trading-Platform Backend)

Estado Actual

• Versión actual: ^14.7.0
• Archivos afectados: 3 archivos en /modules/payments/
• API Version usada: 2023-10-16

Breaking Changes Relevantes

Cambio	Impacto	Acción Requerida
API Version update	Alto	Actualizar apiVersion
Checkout Session behavior	Medio	Verificar subscription flow
total_count deprecated on lists	Bajo	No usado en código

Análisis del Código

const stripe = new Stripe(config.stripe?.secretKey, {
  apiVersion: '2023-10-16',  // CAMBIO: Actualizar a '2024-12-18.acacia' o latest
});

// Patrones usados:
stripe.customers.create()           // OK
stripe.checkout.sessions.create()   // REVISAR: subscription behavior
stripe.subscriptions.update()       // OK
stripe.billingPortal.sessions.create() // OK

Tareas

1. Actualizar stripe a ^20.0.0
2. Actualizar apiVersion a versión compatible
3. Verificar webhook signature handling
4. Testear flujo de checkout completo
5. Verificar stripe.promotionCodes.list() sigue funcionando

Riesgo: MEDIO (requiere testing de flujo de pagos)

---

3. REDIS 4.x → 5.x (Trading-Platform Backend)

Estado Actual

• Versión actual: ^4.6.10
• Archivos afectados: 0 (no se encontró uso activo)
• Nota: La dependencia está declarada pero no hay imports de redis

Análisis

grep -rn "from ['\"']redis['\"']" src/  # Sin resultados
grep -rn "createClient" src/             # Sin resultados

Breaking Changes Relevantes (si se usara)

Cambio	Impacto
client.QUIT() → client.close()	N/A
client.disconnect() → client.destroy()	N/A
Iterator changes (SCAN, etc.)	N/A

Recomendación

OPCIÓN A: Remover la dependencia (no está en uso) OPCIÓN B: Actualizar a v5 para cuando se necesite

Riesgo: NINGUNO (no hay código que usar redis)

---

4. JEST 29.x → 30.x (Ambos Proyectos)

Estado Actual

• Versión actual: ^29.7.0 (gamilit backend, trading-platform backend)
• Archivos afectados: Archivos de configuración jest y todos los tests

Breaking Changes Relevantes

Cambio	Impacto	Acción Requerida
Node 14/16 dropped	Ninguno	Ya usamos Node 18+
jsdom 21→26	Medio	Revisar mocks de window.location
--testPathPattern → --testPathPatterns	Bajo	Actualizar scripts
genMockFromModule removed	Bajo	Buscar y reemplazar
Snapshot changes (Error.cause)	Bajo	Actualizar snapshots

Análisis del Código

# Buscar uso de APIs deprecadas
grep -rn "genMockFromModule" __tests__/  # Verificar
grep -rn "toBeCalled()" __tests__/        # Cambiar a toHaveBeenCalled()

Tareas

1. Actualizar jest a ^30.0.0
2. Actualizar ts-jest a versión compatible
3. Actualizar @types/jest a ^30.0.0
4. Buscar y reemplazar genMockFromModule → createMockFromModule
5. Actualizar snapshots: npm test -- -u
6. Verificar mocks de window.location en frontend tests

Riesgo: BAJO-MEDIO (principalmente snapshots)

---

5. VITEST 3.x → 4.x (Gamilit Frontend)

Estado Actual

• Versión actual: ^3.2.4
• Archivos afectados: Configuración vitest y tests de frontend

Análisis

Vitest 4 tiene cambios menores. La mayoría son mejoras de performance.

Riesgo: BAJO

---

Plan de Ejecución por Fases

FASE 1: Bajo Riesgo (Ejecutar Primero)

1. Redis: Remover dependencia no usada
2. Zod: Ajustes menores de sintaxis (message → error)

FASE 2: Riesgo Medio

3. Jest/Vitest: Actualizar testing frameworks
4. Stripe: Actualizar con testing exhaustivo

FASE 3: Opcional

5. Otras dependencias menores identificadas

---

Prompts para Subagentes

Subagente 1: Migración Zod

TAREA: Migrar schemas de Zod en gamilit/apps/frontend

1. Ejecutar: npx zod-v3-to-v4 --dry-run primero
2. Buscar patrones: { message: en archivos *Schema*.ts
3. Reemplazar { message: por { error: en z.enum() y similares
4. NO cambiar .refine() - esos siguen usando message
5. Verificar: npm run build && npm test

Archivos clave:
- src/shared/schemas/auth.schemas.ts
- src/features/mechanics/**/\*Schemas.ts
- src/services/api/schemas/*.ts

Subagente 2: Limpieza Redis

TAREA: Remover dependencia redis no usada en trading-platform/apps/backend

1. Verificar que no hay imports de 'redis' en src/
2. Remover "redis": "^4.6.10" de package.json
3. Ejecutar npm install
4. Verificar build: npm run build

Subagente 3: Migración Jest

TAREA: Migrar Jest 29→30 en trading-platform/apps/backend

1. Actualizar package.json:
   - "jest": "^30.0.0"
   - "ts-jest": "^29.3.0" (compatible con jest 30)
   - "@types/jest": "^30.0.0"

2. Buscar y reemplazar en __tests__/:
   - genMockFromModule → createMockFromModule
   - toBeCalled() → toHaveBeenCalled()

3. Actualizar jest.config.js si necesario

4. Ejecutar: npm test -- -u (actualizar snapshots)
5. Verificar todos los tests pasan

Subagente 4: Migración Stripe

TAREA: Migrar Stripe 14→20 en trading-platform/apps/backend

1. Actualizar package.json: "stripe": "^20.0.0"
2. npm install

3. Actualizar src/modules/payments/services/stripe.service.ts:
   - Cambiar apiVersion: '2023-10-16' → '2024-12-18.acacia'

4. Verificar que estos métodos siguen funcionando:
   - stripe.customers.create()
   - stripe.checkout.sessions.create()
   - stripe.subscriptions.update()
   - stripe.billingPortal.sessions.create()
   - stripe.webhooks.constructEvent()

5. npm run build
6. Documentar cualquier cambio de API necesario

---

Validación Post-Migración

Para cada proyecto:

# 1. Limpiar node_modules
rm -rf node_modules package-lock.json
npm install

# 2. Verificar vulnerabilidades
npm audit

# 3. Build
npm run build

# 4. Lint
npm run lint

# 5. Tests
npm test

# 6. Dev server (verificación manual)
npm run dev

---

Decisión Final

Dependencia	Acción	Prioridad	Subagente
redis	REMOVER	Alta	#2
zod	AJUSTAR	Media	#1
jest	ACTUALIZAR	Media	#3
stripe	ACTUALIZAR	Baja	#4
vitest	POSTERGAR	Baja	-

Nota: Stripe se posterga porque el riesgo de romper pagos en producción es alto y requiere testing exhaustivo con sandbox.