mirror of
https://github.com/Pandipipas/scoreko-dev.git
synced 2026-06-06 03:32:06 +00:00
feat: add architectural documentation for refactor; include audit, migration plan, rules, target architecture, and session handoff
This commit is contained in:
@@ -0,0 +1,108 @@
|
||||
# Architecture Audit
|
||||
|
||||
Este documento resume el estado arquitectónico actual de Scoreko y debe usarse como referencia para el refactor. No redefine la arquitectura objetivo; documenta el diagnóstico existente y los riesgos detectados.
|
||||
|
||||
## Estado Actual
|
||||
|
||||
La repo es un bundle NodeCG con Vite, Vue 3, Quasar, Pinia y `vite-plugin-nodecg`.
|
||||
|
||||
| Área | Ruta | Responsabilidad actual |
|
||||
| --- | --- | --- |
|
||||
| Extension | `src/extension` | Lógica server NodeCG, OAuth, brackets y pack manager. |
|
||||
| Dashboard | `src/dashboard/scoreko-dev` | App Quasar/Pinia para control. |
|
||||
| Graphics | `src/graphics` | Overlays broadcast: `scoreboard`, `scoreboard-2xko`, `commentary`. |
|
||||
| Browser shared | `src/browser_shared/replicants.ts` | Acceso browser a replicants. |
|
||||
| Shared | `src/shared` | Tipos, utilidades, países, packs y personajes. |
|
||||
| Schemas | `schemas` | Schemas de replicants principales. |
|
||||
| Build outputs | `dashboard`, `graphics`, `extension`, `shared/dist` | Outputs ignorados por git. |
|
||||
|
||||
## Replicants
|
||||
|
||||
### Declarados por Schema
|
||||
|
||||
- `scoreboard`
|
||||
- `players`
|
||||
- `commentary`
|
||||
- `graphicsSettings`
|
||||
- `exampleReplicant`
|
||||
|
||||
### Declarados Solo en Código
|
||||
|
||||
- `installedPacks`
|
||||
- `packRegistry`
|
||||
- `downloadStates`
|
||||
- `availableUpdates`
|
||||
|
||||
### Problema Principal
|
||||
|
||||
El contrato realtime está dividido entre schemas y código runtime. Parte vive en `schemas`, y parte en `pack-manager` o `usePackRegistry`. Esto dificulta validar cambios, regenerar tipos y entender qué estado público existe realmente.
|
||||
|
||||
## Flujo de Datos
|
||||
|
||||
1. El dashboard escribe en Pinia stores.
|
||||
2. Los stores sincronizan con replicants mediante `store-sync.ts`.
|
||||
3. Los overlays leen replicants directamente desde `browser_shared/replicants.ts`.
|
||||
4. La extensión escucha mensajes NodeCG como `startgg:*`, `challonge:*` y `downloadPack`.
|
||||
5. La extensión actualiza replicants o disco.
|
||||
6. `graphicsSettings.scoreboardSkin` redirige entre overlays `scoreboard` y `scoreboard-2xko`.
|
||||
|
||||
## Zonas Grandes o de Riesgo
|
||||
|
||||
| Archivo | Riesgo |
|
||||
| --- | --- |
|
||||
| `src/dashboard/scoreko-dev/views/Players.vue` | Vista demasiado grande: tabla, CRUD, import/export, integraciones y dialogs. |
|
||||
| `src/dashboard/scoreko-dev/components/PlayerSidePanel.vue` | UI duplicada para left/right. |
|
||||
| `src/dashboard/scoreko-dev/views/Settings.vue` | Mezcla idioma, shortcuts, OAuth y tokens. |
|
||||
| `src/dashboard/scoreko-dev/composables/useIntegration.ts` | Mezcla estado UI, localStorage, polling OAuth, importación y cleanup. |
|
||||
| `src/extension/pack-manager.ts` | Mezcla config, tipos, FS, HTTP static, downloads, updates, replicants y handlers. |
|
||||
| `src/graphics/scoreboard/main.vue` | Lógica, layout, animaciones, flags y CSS mezclados. |
|
||||
| `src/graphics/scoreboard-2xko/main.vue` | Mismo riesgo que `scoreboard/main.vue`. |
|
||||
|
||||
## Hallazgos Técnicos
|
||||
|
||||
- No se detectaron ciclos de imports en los archivos TS/Vue revisados.
|
||||
- Sí hay accesos frágiles al entorno NodeCG:
|
||||
- `nodecg` global en composables.
|
||||
- `NodeCG.Replicant` declarado manualmente.
|
||||
- Imports a `package.json` desde UI.
|
||||
- Tipos generados desalineados.
|
||||
- Acceso directo a replicants fuera de stores o servicios.
|
||||
|
||||
## Problemas Reales
|
||||
|
||||
- La frontera NodeCG está rota: `browser_shared/replicants.ts`, stores, `Graphics.vue`, overlays y `usePackRegistry` acceden a NodeCG de formas distintas.
|
||||
- Los contratos realtime no están centralizados.
|
||||
- `pack-manager.ts` necesita reescritura controlada, no parcheo incremental.
|
||||
- `usePackRegistry.ts` y `fighting-characters.ts` necesitan reescritura controlada.
|
||||
- `startgg.ts` y `challonge.ts` duplican estructura: OAuth mode, proxy exchange, session polling API y parsing básico.
|
||||
- `Players.vue` y `Settings.vue` son feature modules completos metidos en vistas.
|
||||
- Los overlays son de alto riesgo visual y deben tocarse con mucho cuidado.
|
||||
- Hay dead code claro: `exampleReplicant`, `example.ts`, `ExampleType` y schema de ejemplo.
|
||||
- `src/types/schemas/configschema.d.ts` está stale: contiene `exampleProperty`, pero `configschema.json` ya no lo define.
|
||||
- `lint` falla por `_id` en `Players.vue` y `_config` en `startgg.ts` y `challonge.ts`.
|
||||
- El resto de lint son warnings de formato Vue.
|
||||
|
||||
## Impacto a Medio y Largo Plazo
|
||||
|
||||
- Añadir providers o skins duplicará lógica.
|
||||
- Contributors externos no sabrán dónde tocar: store, composable, replicant o extensión.
|
||||
- Refactors visuales pueden romper overlays porque no hay separación entre view model y presentación.
|
||||
- El sistema de packs es el mayor riesgo por acoplar descarga, estado realtime, manifests, FS y UI.
|
||||
|
||||
## Zonas a Preservar
|
||||
|
||||
- La idea de `syncStateWithReplicant`.
|
||||
- Stores `scoreboard`, `players` y `commentary` como base razonable.
|
||||
- `oauth-server.ts` como pieza reusable.
|
||||
- `countries.ts`, que está bien encapsulado.
|
||||
- Schemas JSON como fuente de tipos.
|
||||
- UI Quasar existente, preservando comportamiento visual mientras se divide.
|
||||
|
||||
## Baseline de Checks
|
||||
|
||||
| Check | Estado |
|
||||
| --- | --- |
|
||||
| `vue-tsc` | Pasa. |
|
||||
| `tsc` | Pasa. |
|
||||
| `lint` | Falla con 3 errores reales y 243 warnings de formato. |
|
||||
|
||||
Reference in New Issue
Block a user