From 9066e6a643eda97aae3b4a6a2828337a30cf802c Mon Sep 17 00:00:00 2001 From: Pandipipas <62224708+Pandipipas@users.noreply.github.com> Date: Sat, 21 Feb 2026 13:55:58 +0100 Subject: [PATCH] docs: expand refactor audit to cover entire repository (#132) --- docs/refactor-audit-es.md | 175 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 docs/refactor-audit-es.md diff --git a/docs/refactor-audit-es.md b/docs/refactor-audit-es.md new file mode 100644 index 0000000..85d5ce1 --- /dev/null +++ b/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`) 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/*`.