snatchgame/migration-plan-nuxt.md

Plan de Migración a Nuxt - SnatchGame

Resumen Ejecutivo

Migración de arquitectura multi-aplicación (Colyseus server + Vue client + Vue admin) a una aplicación unificada Nuxt 3 que maneje servidor, cliente y administración en un solo proyecto.

Análisis de la Arquitectura Actual

Componentes Existentes

1. Servidor Colyseus (Puerto 2567)

   • Framework: Colyseus.io v0.16
   • GameRoom con lógica de juego
   • API REST para admin
   • WebSocket para sincronización en tiempo real

2. Cliente Vue (Puerto 3000)

   • Vue 3 con Composition API
   • Colyseus.js SDK para conexión
   • Componentes: Home, Game, Settings, PlayerCard, TradeOfferCard
   • Sin build tools (vanilla)

3. Admin Vue (Puerto 3001)

   • Vue 3 con dashboard de estadísticas
   • SSE (Server-Sent Events) para actualizaciones
   • Control total del juego
   • Sin build tools (vanilla)

Arquitectura Propuesta Nuxt 3

Estructura del Proyecto

nuxt-snatchgame/
├── server/
│   ├── api/                  # API REST endpoints
│   │   ├── admin/            # Admin endpoints
│   │   └── config.ts         # Configuración
│   ├── plugins/              
│   │   └── colyseus.ts       # Integración Colyseus
│   └── rooms/                
│       └── GameRoom.ts       # Lógica del juego
├── pages/
│   ├── index.vue             # Cliente del juego (/)
│   └── admin.vue             # Dashboard admin (/admin)
├── components/
│   ├── game/                 # Componentes del juego
│   │   ├── PlayerCard.vue
│   │   ├── TradeOfferCard.vue
│   │   ├── MakeOfferForm.vue
│   │   └── OfferModal.vue
│   └── admin/                # Componentes admin
│       ├── StatsCard.vue
│       ├── PlayerList.vue
│       └── ControlPanel.vue
├── composables/
│   ├── useGameClient.ts      # Cliente Colyseus
│   └── useAdminService.ts    # Servicio admin
├── types/
│   └── game.ts               # TypeScript types
├── public/
│   └── assets/               # Imágenes y recursos
├── nuxt.config.ts
└── package.json

Fases de Migración

Fase 1: Setup Inicial (2 horas)

1. Crear proyecto Nuxt 3

   npx nuxi@latest init nuxt-snatchgame
   cd nuxt-snatchgame
   

2. Instalar dependencias necesarias

   {
     "dependencies": {
       "nuxt": "^3.x",
       "@colyseus/core": "^0.16.19",
       "@colyseus/schema": "^3.0.42",
       "colyseus": "^0.16.0",
       "colyseus.js": "^0.16.19"
     }
   }
   

3. Configuración base en nuxt.config.ts

   • Nitro server configuration
   • WebSocket support
   • Vue 3 setup

Fase 2: Migración del Servidor Colyseus (3 horas)

1. Integrar Colyseus en Nitro

   // server/plugins/colyseus.ts
   import { Server } from 'colyseus'
   import { WebSocketTransport } from '@colyseus/ws-transport'
   import { GameRoom } from '../rooms/GameRoom'
   
   export default defineNitroPlugin((nitroApp) => {
     const gameServer = new Server({
       transport: new WebSocketTransport({
         server: nitroApp.node.server
       })
     })
   
     gameServer.define('game', GameRoom)
       .filterBy(['gameMode'])
       .sortBy({ clients: 1 })
   })
   

2. Migrar GameRoom y tipos

   • Copiar GameRoom.ts sin cambios
   • Mantener Schema classes
   • Adaptar métodos admin

3. API Endpoints

   // server/api/admin/stats.get.ts
   export default defineEventHandler(async (event) => {
     // Migrar lógica de stats
   })
   

Fase 3: Migración del Cliente (3 horas)

1. Página principal del juego

   <!-- pages/index.vue -->
   <template>
     <div>
       <HomeScreen v-if="!inGame" @join="joinGame" />
       <GameScreen v-else :client="gameClient" />
     </div>
   </template>
   

2. Composable para cliente Colyseus

   // composables/useGameClient.ts
   export const useGameClient = () => {
     const client = ref<Client | null>(null)
     const room = ref<Room | null>(null)
   
     const connect = async (playerName: string) => {
       client.value = new Client('ws://localhost:3000')
       room.value = await client.value.joinOrCreate('game', {
         playerName
       })
     }
   
     return { client, room, connect }
   }
   

3. Migrar componentes Vue

   • Convertir a script setup
   • Usar auto-imports de Nuxt
   • Mantener lógica existente

Fase 4: Migración del Admin (2 horas)

1. Página admin

   <!-- pages/admin.vue -->
   <template>
     <AdminDashboard />
   </template>
   

2. Servicio SSE con Nitro

   // server/api/admin/stream.get.ts
   export default defineEventHandler(async (event) => {
     const stream = createEventStream(event)
   
     // Enviar stats cada 250ms
     const interval = setInterval(async () => {
       const stats = await getGameStats()
       await stream.push(stats)
     }, 250)
   
     stream.onClosed(() => {
       clearInterval(interval)
     })
   
     return stream.send()
   })
   

3. Composable admin

   // composables/useAdminService.ts
   export const useAdminService = () => {
     const stats = ref({})
   
     const connect = () => {
       const eventSource = new EventSource('/api/admin/stream')
       eventSource.onmessage = (e) => {
         stats.value = JSON.parse(e.data)
       }
     }
   
     return { stats, connect }
   }
   

Fase 5: Integración y Testing (2 horas)

1. Configuración de desarrollo

   {
     "scripts": {
       "dev": "nuxt dev",
       "build": "nuxt build",
       "preview": "nuxt preview"
     }
   }
   

2. Variables de entorno

   NUXT_PUBLIC_GAME_NAME=SnatchGame
   NUXT_SERVER_PORT=3000
   

3. Testing funcional

   • Verificar conexión WebSocket
   • Probar sincronización de estado
   • Validar panel admin
   • Test de múltiples jugadores

Consideraciones Técnicas

WebSocket en Nuxt/Nitro

• Nitro soporta WebSocket nativamente
• Colyseus se integra mediante plugin
• Un solo puerto para todo (3000)

Estado Compartido

• Usar Pinia para estado local
• Colyseus para estado sincronizado
• SSE para actualizaciones admin

TypeScript

• Schema-codegen sigue funcionando
• Types compartidos en /types
• Auto-imports de Nuxt

Rutas

• / - Cliente del juego
• /admin - Panel de administración
• /api/* - API endpoints
• WebSocket en el mismo puerto

Simplificaciones MVP

1. Sin autenticación - Solo nombres de usuario
2. Sin base de datos - Todo en memoria
3. Sin Docker - Deploy directo con Node
4. Sin HTTPS - Solo HTTP/WS local
5. Sin optimizaciones - Código simple y directo

Ventajas de la Migración

1. Un solo proyecto - Más fácil de mantener
2. Un solo puerto - Simplifica deployment
3. Hot reload completo - Mejor DX
4. Auto-imports - Menos boilerplate
5. TypeScript integrado - Mejor tooling
6. SSR opcional - Mejor SEO si necesario

Riesgos y Mitigaciones

Riesgo	Mitigación
WebSocket en Nitro no probado	Usar h3-ws o plugin dedicado
Colyseus incompatible	Mantener servidor separado si falla
Performance SSE	Usar WebSocket para admin también
Complejidad aumenta	Mantener arquitectura simple

Cronograma Estimado

• Día 1: Setup + Servidor (5 horas)
• Día 2: Cliente + Admin (5 horas)
• Día 3: Testing + Ajustes (2 horas)

Total: ~12 horas de desarrollo

Comando para Iniciar

# Desarrollo
npm run dev

# Producción
npm run build
npm run preview

Estructura de Datos del Juego

Juegos (5 rondas totales)

1. Sin reglas - Ofrecer/Aceptar/Rechazar/Robar sin castigo
2. Reglas contraproducentes - Jugador 2 puede forzar oferta
3. Fichas de vergüenza - Visible para siguiente contrincante
4. Derechos mínimos - Sistema castiga robos denunciados
5. Comunicación abierta - Jugadores pueden hablar

Mecánicas Core

• 3 rondas por juego (solo la 3ra cuenta)
• Roles: Jugador 1 / Jugador 2
• Contrincantes aleatorios
• Sin comunicación (excepto juego 5)
• Auto-increment para nombres duplicados

Decisiones de Diseño

1. Nuxt sobre Next.js - Mejor integración Vue
2. Nitro server - WebSocket nativo
3. Sin build tools en components - Usar SFC de Nuxt
4. Colyseus integrado - No servidor separado
5. SSE para admin - Mantener patrón actual

Próximos Pasos

1. ✅ Aprobar plan de migración
2. ⏳ Crear proyecto Nuxt base
3. ⏳ Migrar servidor Colyseus
4. ⏳ Migrar cliente Vue
5. ⏳ Migrar admin Vue
6. ⏳ Testing integral
7. ⏳ Deploy local