feat: add architectural documentation for refactor process, including audit, rules, migration plan, session handoff, and target architecture

docs/refactor/MIGRATION_PLAN.md

@@ -0,0 +1,47 @@
+# Plan de Migración
+
+> [!WARNING]
+> Este plan está diseñado para evitar regresiones y mantener un estado "compilable" en todo momento. Se debe ejecutar estrictamente de backend a frontend, y de lógica pura a UI.
+
+## Paso 1: Estabilización del Shared y Tipos
+- **Acciones**:
+  - Mover utilidades genéricas (como la lista de `countries`, funciones de manipulación de strings) a `src/shared/utils/`.
+  - Refinar y consolidar los tipos en `src/shared/types/` para que representen el dominio real.
+  - Eliminar tipos parciales o duplicados dispersos en el código.
+- **Riesgo**: Bajo. Gran parte es movimiento y ajuste de imports.
+
+## Paso 2: Refactor del Backend (Extension)
+- **Acciones**:
+  - **Reescritura controlada de integraciones**: Dividir `startgg.ts` en:
+    - `services/startgg.ts` (lógica de negocio y transformaciones).
+    - `api/startgg.ts` (GraphQL / HTTP requests).
+    - `oauth/startgg.ts` (flujo OAuth).
+    - `nodecg-bindings/startgg.ts` (vinculación exclusiva de `nodecg.listenFor`).
+  - Repetir la misma división para `challonge.ts`.
+  - Mover cualquier otra utilidad de backend a `extension/utils/`.
+- **Riesgo**: Moderado. Requiere trasladar código con cuidado para no romper las firmas de los métodos.
+
+## Paso 3: Refactor del Estado del Dashboard (Stores)
+- **Acciones**:
+  - Limpiar `store-sync.ts`. Reducir la complejidad y sobre-ingeniería generada por el uso del `localStorage`.
+  - Asegurar que Pinia dependa directa y limpiamente de los Replicantes como fuente de datos real.
+  - Garantizar que los stores exporten acciones limpias, evitando que el estado interno se mute manualmente desde los componentes de la vista.
+- **Riesgo**: Medio. Afecta el flujo de reactividad base de la UI.
+
+## Paso 4: Modularización de los Componentes Grandes (Dashboard)
+- **Acciones**:
+  - **Reescritura/División controlada de `Players.vue`**:
+    - Extraer modales a componentes independientes (ej. `ImportDialog.vue`, `PlayerEditDialog.vue`).
+    - Extraer los selectores de integración a componentes puros (`StartGGPanel.vue`, `ChallongePanel.vue`).
+    - Reemplazar los SVGs "hardcodeados" en el template por un componente dedicado o usar la librería de iconos de Quasar.
+  - Extraer partes de vistas monolíticas (`PlayerSidePanel.vue`) en sub-componentes especializados.
+- **Riesgo**: Medio. Afecta directamente a la UI. Es crítico asegurar que los eventos (`emits`) se propagen y conecten correctamente.
+
+## Paso 5: Refactor de los Gráficos (Scoreboard)
+- **Acciones**:
+  - **Reescritura controlada de `main.vue`**:
+    - Extraer la lógica de ajuste de fuente a un archivo dedicado, ya sea como directiva o función: `graphics/shared/utils/fitText.ts` (o `v-fit-text`).
+    - Extraer la lógica de resolución de banderas (flags) y su caché a un composable dedicado: `useFlag(countryCode)`.
+    - Extraer el control de animaciones y timeouts a `useScoreAnimation(scoreRef)`.
+    - Dividir el DOM en componentes claros: `<BackgroundPanel>`, `<PlayerInfo side="left">`, `<ScoreDisplay>`, orquestados desde `App.vue` (o `main.vue` simplificado).
+- **Riesgo**: Alto. Las animaciones y cálculos visuales de DOM son delicados. El objetivo visual final debe ser idéntico, y el comportamiento ante cambios de Replicants debe mantenerse exacto.