From d69b294e0c0396e88b5e002eef4246cf881e427b Mon Sep 17 00:00:00 2001 From: Pandipipas <62224708+Pandipipas@users.noreply.github.com> Date: Wed, 25 Feb 2026 13:52:40 +0100 Subject: [PATCH] remove docs --- docs/refactor-audit-es.md | 175 -------------------------------------- 1 file changed, 175 deletions(-) delete mode 100644 docs/refactor-audit-es.md diff --git a/docs/refactor-audit-es.md b/docs/refactor-audit-es.md deleted file mode 100644 index 85d5ce1..0000000 --- a/docs/refactor-audit-es.md +++ /dev/null @@ -1,175 +0,0 @@ -# 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/*`.