scoreko-dev/docs/refactor/MIGRATION_PLAN.md

Migration Plan

Este plan define el orden de migración. Debe ejecutarse de forma secuencial para reducir riesgo, preservar comportamiento y evitar reescrituras amplias sin baseline.

Principios

• Mantener nombres públicos y comportamiento hasta completar la migración.
• Congelar comportamiento antes de mover responsabilidades.
• Eliminar legacy muerto antes de envolverlo.
• Separar boundaries antes de reescribir módulos complejos.
• Tocar overlays al final y con verificación visual.

Secuencia

Paso	Objetivo	Tipo
1	Congelar comportamiento con screenshots de overlays, fixtures de replicants, build, typecheck y lint baseline.	Baseline
2	Quitar example*, regenerar schema types y eliminar .js redundantes en src/shared si no se usan.	Limpieza
3	Crear nodecg/browser y nodecg/extension sin cambiar comportamiento.	Boundary
4	Añadir schemas para replicants de packs manteniendo nombres y defaults exactos.	Contratos
5	Extraer tipos/config de packs a shared y ajustar tsconfig.extension para no duplicar.	Shared
6	Reescribir controladamente pack-manager.	Reescritura
7	Reescribir controladamente usePackRegistry y fighting-characters.	Reescritura
8	Dividir useIntegration.	Modularización
9	Dividir Players.vue.	Modularización
10	Dividir Settings.vue.	Modularización
11	Refactor suave de dashboard scoreboard para eliminar duplicación left/right.	Modularización
12	Extraer view models y helpers de overlays sin tocar CSS/markup al inicio.	Overlays
13	Añadir tests puros para normalizadores y lógica de dominio.	Tests
14	Añadir verificación visual Playwright para overlays principales.	Visual QA

Detalle por Fase

1. Congelar Comportamiento

Crear una baseline antes de refactorizar:

• Screenshots de scoreboard, scoreboard-2xko y commentary.
• Fixtures representativos de replicants.
• Resultado actual de build y typecheck.
• Resultado actual de lint, incluyendo los 3 errores reales conocidos.

2. Limpiar Dead y Stale Code

Eliminar código que no representa comportamiento productivo:

• exampleReplicant.
• example.ts.
• ExampleType.
• Schema de ejemplo.
• Tipos generados stale.
• .js redundantes en src/shared si se confirma que no se usan.

3. Crear Boundaries NodeCG

Introducir APIs sin cambiar comportamiento:

• src/nodecg/browser/replicants.ts
• src/nodecg/browser/messages.ts
• src/nodecg/extension/replicants.ts
• src/nodecg/extension/messages.ts
• src/nodecg/extension/context.ts

El objetivo es centralizar acceso a replicants, messages, logging y NodeCG globals.

4. Centralizar Contratos Realtime

Añadir schemas para:

• installedPacks
• packRegistry
• downloadStates
• availableUpdates

Los nombres y defaults deben mantenerse exactamente para no romper dashboard, extensión ni overlays.

5. Extraer Shared de Packs

Mover a shared:

• Tipos de manifest.
• Tipos de registry.
• Tipos de estado de descarga.
• Config derivada común.
• Validación ligera en boundaries.

No duplicar tipos entre extension y browser.

6. Reescritura Controlada de Pack Manager

Separar pack-manager.ts en módulos pequeños:

Módulo	Responsabilidad
Registry client	Fetch y normalización del registry remoto.
Downloader	Descargas, progreso y errores.
Disk store	Lectura/escritura en disco.
Static mount	Exposición HTTP de assets instalados.
Handlers	Registro de mensajes NodeCG.
Replicant sync	Actualización centralizada de replicants.

7. Reescritura de Pack Registry Runtime

Rehacer usePackRegistry y fighting-characters para:

• Quitar estado mutable de módulo opaco.
• Evitar ref en shared.
• Modelar packs instalados como estado explícito.
• Cargar manifests mediante boundaries claros.
• Eliminar comentarios que contradicen el estado real de assets.

8. Dividir Integraciones

Extraer useIntegration en piezas:

• nodecgMessageClient
• oauthClient
• temporaryPlayers
• tournamentImport

Cada pieza debe tener cleanup explícito para timers/listeners.

9. Dividir Players

Extraer desde Players.vue:

• PlayersTable
• PlayerEditorDialog
• IntegrationImportCard
• ImportPlayersDialog

La vista debe coordinar el feature, no contener la implementación completa.

10. Dividir Settings

Extraer desde Settings.vue:

• LanguageSettings
• ShortcutSettings
• IntegrationSettings

Mantener UI Quasar y comportamiento actual.

11. Refactor Suave de Scoreboard Dashboard

Eliminar duplicación left/right con subcomponentes pequeños, sin cambiar el comportamiento público ni el layout principal.

12. Overlays al Final

Primero extraer sin modificar presentación:

• View models.
• Helpers de flags.
• Helpers de score animation.
• Helpers de text fitting.

Después de verificar baseline visual, deduplicar internals.

13. Tests Puros

Añadir tests para:

• Normalizadores.
• Pack registry.
• Shortcut parsing.
• Country resolving.
• Bracket round formatting.

14. Verificación Visual

Añadir Playwright para overlays principales:

• scoreboard.
• scoreboard-2xko.
• commentary.

Debe validar screenshots o checks visuales estables antes de tocar CSS sensible.

Clasificación de Trabajo

Categoría	Incluye
Automatizable	Moves/imports, schema generation, lint autofix, snapshots.
Reescritura controlada	Packs y registry runtime.
División	Players.vue, Settings.vue, overlays.
Conservar	Quasar UI, Pinia, schemas, oauth-server, concepto de store-sync, layout visual de overlays.