docs: expand refactor audit to cover entire repository (#132)

docs/refactor-audit-es.md

@@ -0,0 +1,175 @@
+# 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/*`.