scoreko-dev/docs/refactor-audit-es.md

Auditoría técnica integral (repositorio completo)

Objetivo: proponer una lista detallada de refactors, limpiezas, reworks y mejoras para todo el repositorio, con enfoque incremental y sin romper comportamiento.

Alcance revisado (full repo)

• Extension (backend NodeCG): src/extension/*
• Dashboard (UI panel): src/dashboard/*
• Graphics (overlays): src/graphics/*
• Shared (catálogos y utilidades): src/shared/* y src/browser_shared/*
• Schemas y tipos generados: schemas/*, src/types/*, configschema.json
• Tooling y build: package.json, vite.config.ts, tsconfig*.json, eslint*.js
• Docs y metadatos: README.md, LICENSE, .vscode/*

---

1) Refactorización de arquitectura (backend + frontend)

1. Separar módulos grandes de integración (startgg.ts, challonge.ts) en capas:
   • oauth/ (sesiones, callback server, token exchange),
   • api/ (requests, retries, parsing),
   • mappers/ (normalización a modelo interno),
   • listeners/ (registro nodecg.listenFor).
2. Crear una capa de dominio compartida (src/domain/):
   • Tipos como Tournament, ImportedPlayer, OAuthSession, IntegrationError.
   • Evita duplicidad de interfaces entre extension/dashboard.
3. Aislar la lógica de sincronización de stores:
   • Mantener store-sync.ts como base, pero separar responsabilidades:
     • snapshot local,
     • sincronización replicant,
     • normalización.

2) Limpieza y unificación de integraciones externas

1. Eliminar duplicación StartGG/Challonge:
   • Actualmente hay utilidades repetidas (getStringProp, sendAck, OAuth session lifecycle, callback HTML).
   • Crear utilidades comunes en src/extension/util/integrations.ts.
2. Estandarizar respuestas de listeners:
   • Contrato único: { ok: boolean, data?: T, error?: string, code?: string }.
   • Mejora manejo de errores en dashboard.
3. Timeout + retry con backoff para fetch:
   • Abortar peticiones lentas, reintentar 429 y 5xx.
4. Logging estructurado:
   • Añadir requestId, integration, operation, durationMs, status.

3) Endurecimiento de seguridad

1. Escapar contenido HTML en callbacks OAuth (renderCallbackHtml).
2. Minimizar exposición de secretos:
   • Nunca serializar client secrets en logs/acks.
3. Validación defensiva de payloads de listeners:
   • Evitar aceptar estructuras parciales no esperadas.
4. Cleanup de sesiones OAuth más robusto:
   • Barrido periódico + límite de sesiones en memoria.

4) Tipado y calidad TypeScript

1. Sustituir casts amplios (as unknown as Record<string, unknown>) por parsers tipados.
2. Centralizar normalizadores (normalizeX) por dominio en shared/normalizers/.
3. Discriminated unions para eventos:
   • Listeners de extension y acciones de dashboard más seguros.
4. Endurecer tsconfig progresivamente:
   • revisar noUncheckedIndexedAccess, exactOptionalPropertyTypes y flags estrictos adicionales.

5) Dashboard: UX, estructura y deuda técnica

1. Descomponer ScoreboardPanel.vue en subcomponentes:
   • Selectores de jugador,
   • Selectores de personaje,
   • Bloque de score/round/game,
   • Acciones rápidas.
2. Extraer lógica repetida de filtros/autocomplete a composables:
   • useFilteredOptions, useCountryFilter, useCharacterFilter.
3. Unificar persistencia local:
   • commentary no persiste snapshot local y players/scoreboard sí.
   • Definir política única.
4. Accesibilidad:
   • Labels explícitos, foco visible, atajos de teclado básicos.
5. I18n completo:
   • Detectar cadenas hardcodeadas en componentes y moverlas a i18n.ts.

6) Graphics: mantenibilidad y consistencia visual

1. Crear una base compartida de render para scoreboard, scoreboard-2xko, commentary:
   • formato de nombre/equipo,
   • fallback de banderas,
   • truncado/ellipsis,
   • placeholders de assets.
2. Normalizar fuentes y assets:
   • directorio por overlay + convención de naming.
3. Modo degradado (“safe render”):
   • Cuando faltan datos del replicant, render estable sin romper layout.
4. Pruebas visuales smoke:
   • snapshots por estado base (vacío / datos completos / datos parciales).

7) Shared data: países, personajes e imágenes

1. Separar catálogo de personajes de lógica de presentación:
   • JSON/TS puro para data,
   • utilidades aparte para slug, placeholder, imagen.
2. Detectar drift catálogo vs assets:
   • script que valide personaje declarado pero imagen inexistente (y viceversa).
3. Optimización de imágenes:
   • convertir PNG grandes a WebP/AVIF (mantener fallback si hace falta).
4. Consolidar reglas de slugificado para evitar inconsistencias por juego.

8) Schemas, replicants y migraciones

1. Versionar schemas de replicants:
   • incluir schemaVersion y migraciones compatibles.
2. Contrato de migración al iniciar extension:
   • migrar datos viejos antes de exponerlos al dashboard/graphics.
3. Validación runtime adicional tras importaciones externas.
4. Automatizar verificación de tipos generados (schema-types) en CI.

9) Testing (deuda principal del repo)

1. Unit tests extension:
   • parsers de payload,
   • normalizadores de torneos/jugadores,
   • utilidades OAuth.
2. Unit tests shared:
   • países, personaje por juego, slug/imagen fallback.
3. Tests de stores Pinia:
   • sincronización replicants,
   • swap/reset,
   • persistencia local.
4. E2E smoke dashboard + graphics:
   • editar datos en panel y verificar overlays.
5. Contract tests de integraciones con respuestas mockeadas.

10) Build, tooling y CI/CD

1. Pipeline mínima obligatoria:
   • npm ci
   • npm run lint
   • npm run schema-types
   • npm run build
2. Script dev estándar (mantener watch como alias).
3. Checks de tamaño de bundle/assets para detectar regresiones.
4. Renovación de .vscode settings para alinearse con lint/format del repo.

11) Naming, convenciones y limpieza general

1. Unificar branding scoreko-dev / Scoreko en UI y docs.
2. Convención de nombres consistente:
   • archivos Vue en PascalCase, utilidades en kebab-case o camelCase según regla definida.
3. Depurar archivos de ejemplo:
   • mantener example solo si aporta onboarding real.
4. Eliminar dead code / imports no usados de módulos grandes en cada iteración.

12) Documentación que crearía o ampliaría

1. docs/architecture.md (flujo completo NodeCG).
2. docs/integrations/startgg.md y docs/integrations/challonge.md.
3. docs/replicants-and-schemas.md (versionado + migraciones).
4. docs/testing-strategy.md (unit/integration/e2e).
5. docs/release-checklist.md (build, smoke, rollback).

13) Roadmap por fases (sin romper producción)

1. Fase 1 (bajo riesgo): tests unitarios shared + extension, utilidades comunes de integración, documentación base.
2. Fase 2 (riesgo medio): refactor interno de StartGG/Challonge sin cambiar contratos externos.
3. Fase 3 (riesgo medio): descomposición de paneles dashboard y composables reutilizables.
4. Fase 4 (riesgo medio/alto): migraciones de schemas + endurecimiento TypeScript.
5. Fase 5 (continuo): optimización de assets, tests visuales y budget de performance.

Inventario inspeccionado para esta auditoría global

• Configuración y tooling: package.json, vite.config.ts, tsconfig*.json, eslint*.js, README.md, configschema.json.
• Extension: src/extension/index.ts, src/extension/startgg.ts, src/extension/challonge.ts, src/extension/util/*, src/extension/example.ts.
• Dashboard: src/dashboard/scoreko-dev/*, src/dashboard/loading/*, src/dashboard/template.html, src/dashboard/quasar-variables.sass.
• Graphics: src/graphics/scoreboard/*, src/graphics/scoreboard-2xko/*, src/graphics/commentary/*, src/graphics/template.html.
• Shared/browser_shared: src/shared/countries.ts, src/shared/fighting-characters.ts, src/shared/character-images/*, src/browser_shared/replicants.ts.
• Schemas y tipos: schemas/*, src/types/*.