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.