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
```typescript
// 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
```typescript
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
```bash
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
```bash
# 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:
```bash
# 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.