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/*`.