scoreko-dev/docs/refactor-audit.md

# Refactor / Cleanup / Rework Audit

Este documento lista mejoras propuestas para `scoreko-dev`, priorizadas por impacto y esfuerzo.

## 1) Arquitectura y organización

### Alta prioridad
1. **Definir capas explícitas (`domain`, `application`, `infra`, `ui`)** para separar reglas de negocio (scoreboard, players, commentary) de NodeCG/Pinia/Vue y reducir acoplamiento.
2. **Extraer lógica de negocio fuera de componentes Vue** (sobre todo de `ScoreboardPanel.vue`) a composables/servicios dedicados.
3. **Unificar contratos compartidos en un módulo `src/domain`** para evitar que cada store redeclare defaults/normalizadores manuales.
4. **Introducir un patrón de “casos de uso”** (`swapPlayers`, `resetScores`, `savePlayer`, etc.) para dejar de mezclar orquestación y estado reactivo.
5. **Crear un sistema de módulos por feature** (`features/scoreboard`, `features/players`, `features/commentary`) para facilitar testeo y mantenimiento.

### Media prioridad
6. Consolidar helpers transversales (`filterOptions`, normalizadores, parseo de storage) en utilidades versionadas.
7. Estandarizar convención de nombres (`left/right`, `player/commentator`, `override`) y documentarla.
8. Introducir “barrels” (`index.ts`) por feature para reducir imports relativos largos.
9. Separar claramente código “runtime NodeCG” (extension) de código “browser/dashboard”.

## 2) Stores y sincronización con Replicants

### Alta prioridad
10. **Eliminar duplicación de normalización** en `scoreboard.ts`, `players.ts` y `commentary.ts` usando un validador común (zod/valibot o validadores propios centralizados).
11. **Modelar una política única de snapshots en localStorage**: actualmente algunos stores persisten y otros no; unificar criterio por feature.
12. **Tipar mejor `ReplicantLike<T>`** para contemplar estados de carga, errores y ausencia de datos, no solo `data | undefined`.
13. **Agregar control anti-loop más robusto en `syncStateWithReplicant`** (versionado/cambios por hash) para evitar escrituras redundantes.
14. **Introducir acciones atómicas** para operaciones compuestas (ej. swap + persistencia) y facilitar test unitario.

### Media prioridad
15. Añadir métricas de latencia/frecuencia de `save()` para detectar exceso de persistencia.
16. Exponer `dirty state`/`isSynced` por store para feedback de UI y depuración.
17. Implementar estrategia de migración de snapshots al cambiar schema/version.
18. Crear utilidades de actualización parcial (`patchScoreboard`) en vez de reasignar objetos completos repetidamente.

## 3) Componentes Vue y UI (dashboard)

### Alta prioridad
19. **Partir `ScoreboardPanel.vue` en subcomponentes** (jugador izquierdo/derecho, juego/personajes, score controls, overrides).
20. **Mover filtros y autocompletado a composables** (`usePlayerSearch`, `useCountrySearch`, `useCharacterSearch`).
21. **Reducir watchers y `watchEffect` ad-hoc** sustituyéndolos por derivaciones computadas puras y acciones explícitas.
22. **Crear componentes reutilizables** para pares simétricos izquierda/derecha y eliminar lógica duplicada.
23. **Formalizar estados vacíos/errores/carga** en paneles (players, bracket, commentary) para UX consistente.

### Media prioridad
24. Consolidar strings hardcodeados de juegos en una fuente única + i18n.
25. Definir diseño de formularios con reglas de validación declarativas (Quasar rules reutilizables).
26. Introducir navegación por teclado consistente en selects/inputs críticos para operación en vivo.
27. Añadir micro-feedback visual de acciones críticas (swap/reset/save).
28. Desacoplar assets de personajes de la lógica de presentación para soportar themes/skins.

## 4) Extensión NodeCG e integraciones externas

### Alta prioridad
29. **Refactorizar `src/extension/index.ts` a registro de módulos** con manejo explícito de inicialización y fallos por integración.
30. **Encapsular `startgg` y `challonge` detrás de puertos/adaptadores** para que el dominio no dependa de APIs concretas.
31. **Agregar retry/backoff/timeouts centralizados** para llamadas externas.
32. **Registrar logs estructurados** (nivel, contexto, correlación) en vez de logs dispersos.
33. **Definir feature flags/config para habilitar/deshabilitar integraciones** sin tocar código.

### Media prioridad
34. Crear una capa de cache para respuestas repetidas de torneos.
35. Tipar estrictamente respuestas externas y validar payloads de entrada/salida.
36. Establecer límites de tasa por proveedor para evitar bloqueos.
37. Agregar pruebas de contrato para integraciones.

## 5) Esquemas, tipos y contratos

### Alta prioridad
38. **Alinear defaults de código con schemas JSON** y evitar drift entre `schemas/*` y stores.
39. **Automatizar comprobación en CI** de que `schema-types` está actualizado.
40. **Versionar schemas y definir estrategia de migración** para datos persistidos.
41. **Introducir invariantes de dominio explícitas** (scores >= 0, ids válidos, países válidos, etc.).

### Media prioridad
42. Centralizar tipos derivados repetidos en `src/types` para eliminar alias locales redundantes.
43. Definir `branded types` para IDs sensibles (`PlayerId`, `GameId`).
44. Crear tests de regresión de normalizadores contra casos borde.

## 6) Tooling, calidad y automatización

### Alta prioridad
45. **Agregar pipeline CI completo** (lint, typecheck, build, tests, schema drift check).
46. **Separar `lint` de `typecheck`** con scripts dedicados y fail-fast claro.
47. **Incluir tests unitarios** para stores, normalizadores y utilidades compartidas.
48. **Añadir tests de integración de replicants** simulando cambios bidireccionales dashboard/extension.
49. **Incorporar pruebas E2E críticas** para flujos de operación (swap players, update scores, reset).

### Media prioridad
50. Incorporar coverage mínimo y umbrales por carpeta.
51. Añadir pre-commit hooks (lint-staged + prettier/eslint).
52. Documentar comandos de release y versionado semántico.
53. Introducir changelog automático.

## 7) Rendimiento y robustez

### Alta prioridad
54. **Evitar recomputaciones costosas en cada render** cacheando opciones derivadas grandes (jugadores, países, personajes).
55. **Reducir escrituras frecuentes a localStorage/replicant** con debounce/throttle configurable.
56. **Optimizar payloads de replicants** para enviar solo campos cambiados cuando sea viable.

### Media prioridad
57. Medir tiempos de montaje de paneles y establecer presupuesto de rendimiento.
58. Revisar tamaño de bundle y lazy-load de vistas no críticas.
59. Añadir fallback robusto para assets de personajes faltantes.

## 8) Seguridad operativa y resiliencia

### Alta prioridad
60. **Sanitizar y validar inputs de usuario** antes de persistir/renderizar (nombres, handles, textos libres).
61. **Definir límites de longitud por campo** y truncado seguro para evitar overflows visuales.
62. **Manejar degradación controlada** cuando APIs externas fallen durante directo.

### Media prioridad
63. Auditar dependencia y política de actualizaciones de seguridad.
64. Añadir guía de incidentes operativos (qué hacer si falla startgg/challonge).

## 9) Limpieza y eliminación técnica

### Alta prioridad
65. **Eliminar código muerto y utilidades no usadas** tras dividir componentes/composables.
66. **Reducir duplicados izquierda/derecha** mediante abstracciones reutilizables.
67. **Homogeneizar manejo de errores silenciosos** (`catch {}`) con reporte opcional de diagnóstico.

### Media prioridad
68. Revisar assets/imágenes huérfanas y limpiar peso innecesario del repo.
69. Estandarizar comentarios y retirar comentarios obvios/desactualizados.
70. Reorganizar carpetas de `graphics` para facilitar escalado a nuevas overlays.

## 10) Plan sugerido por fases

- **Fase 1 (rápida, alto impacto):** 10, 19, 29, 38, 45, 47, 54, 55, 60, 65.
- **Fase 2 (estabilización):** 11, 13, 20, 30, 31, 39, 46, 48, 56, 67.
- **Fase 3 (escala y DX):** 1, 4, 5, 24, 33, 40, 49, 50, 58, 70.

## 11) Quick wins (1–2 días)

1. Añadir scripts `typecheck` y `test` en `package.json` + pipeline CI base.
2. Extraer filtros de `ScoreboardPanel` a composables (`useFilterOptions`, `useCountryFilter`).
3. Unificar normalizadores en `src/shared/normalize`.
4. Añadir tests unitarios de `syncStateWithReplicant` y normalizadores.
5. Convertir strings de juegos a una constante única internacionalizable.
6. Agregar debounce a persistencia de storage/replicant.