docs: add detailed refactor and cleanup audit

docs/refactor-audit.md

@@ -0,0 +1,142 @@
+# 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.