From a2ec70220dbfc2a199df8f32f2a7aa584a979575 Mon Sep 17 00:00:00 2001 From: devRaGonSa Date: Tue, 19 May 2026 15:37:50 +0200 Subject: [PATCH] Document RCON-first historical architecture --- README.md | 24 +++++++++++++++++++ ai/architecture-index.md | 3 +++ ai/repo-context.md | 2 ++ ...ment-rcon-first-historical-architecture.md | 9 ++++++- backend/README.md | 22 +++++++++++++++++ docs/decisions.md | 13 ++++++++++ 6 files changed, 72 insertions(+), 1 deletion(-) rename ai/tasks/{pending => done}/TASK-132-document-rcon-first-historical-architecture.md (77%) diff --git a/README.md b/README.md index e8b9453..2ac8dbc 100644 --- a/README.md +++ b/README.md @@ -230,6 +230,30 @@ Verificacion minima: - `docker compose logs -f historical-runner` - revisar `generated_at` en `backend/data/snapshots/` +## Arquitectura historica RCON-first + +La linea historica actual usa RCON como fuente primaria. El flujo previsto es: + +- captura de sesiones RCON para cobertura, frescura y ventanas competitivas +- ingesta de AdminLog mediante `app.rcon_admin_log_ingestion` +- parsing de eventos AdminLog hacia eventos normalizados +- almacenamiento en tablas `rcon_admin_log_*` y `rcon_historical_*` +- materializacion de partidas cerradas y estadisticas de jugador desde eventos RCON +- enriquecimiento opcional con snapshots de perfil de jugador, sin tratarlos + como hechos autoritativos de una partida + +El scoreboard publico queda limitado a enriquecimiento, links confiables o +fallback historico cuando RCON falla, no tiene cobertura suficiente o no cubre +una operacion concreta. Elo/MMR sigue pausado y Comunidad Hispana #03 permanece +fuera de los targets RCON por defecto. + +Comandos manuales RCON dentro del contenedor backend: + +```powershell +docker compose exec backend python -m app.rcon_admin_log_ingestion --minutes 1440 +docker compose exec backend python -m app.rcon_historical_worker capture +``` + Si se prefiere operar fuera de Docker, el backend sigue pudiendo arrancar localmente con `python -m app.main` desde `backend/`. ## Evolucion prevista diff --git a/ai/architecture-index.md b/ai/architecture-index.md index 2b1f83c..507afb9 100644 --- a/ai/architecture-index.md +++ b/ai/architecture-index.md @@ -80,3 +80,6 @@ Community website repository with a static landing in the current phase and a pl - Comunidad Hispana #03 is disabled from default RCON targets, while existing historical/Elo code and persisted data remain available for explicit future reintroduction. Elo/MMR remains paused and decoupled from backend startup. - Frontend data consumption should remain progressive, endpoint by endpoint, with static fallbacks preserved during migration. - The frontend integration strategy is documented in `docs/frontend-data-consumption-plan.md`. +- Historical RCON architecture is RCON-first end to end: session capture, AdminLog ingestion, parsed event storage, materialized matches/player stats and optional profile-snapshot enrichment. +- Public-scoreboard data remains optional enrichment/link source or fallback only; it must not become the normal primary historical path while RCON coverage is available. +- Manual RCON validation commands include `docker compose exec backend python -m app.rcon_admin_log_ingestion --minutes 1440` and `docker compose exec backend python -m app.rcon_historical_worker capture`. diff --git a/ai/repo-context.md b/ai/repo-context.md index d7777d5..7d6e8ae 100644 --- a/ai/repo-context.md +++ b/ai/repo-context.md @@ -22,6 +22,8 @@ This repository is in foundation stage. The objective is to grow in a controlled - Default deployment: `backend` + `frontend`; historical workers are advanced/manual only. - Live and historical defaults are RCON-first, with public-scoreboard kept only as historical fallback. - Comunidad Hispana #03 is not part of default RCON targets. Historical/Elo code and persisted data are preserved, while Elo/MMR remains paused and decoupled from backend startup. +- RCON historical data flow is session capture plus AdminLog ingestion, parsed event storage, materialized matches/player stats and optional player profile snapshot enrichment. +- Public scoreboard may enrich links or fill unsupported historical gaps, but it is not the primary historical source when RCON coverage exists. ## Repository Areas diff --git a/ai/tasks/pending/TASK-132-document-rcon-first-historical-architecture.md b/ai/tasks/done/TASK-132-document-rcon-first-historical-architecture.md similarity index 77% rename from ai/tasks/pending/TASK-132-document-rcon-first-historical-architecture.md rename to ai/tasks/done/TASK-132-document-rcon-first-historical-architecture.md index 1250006..e0ce7c0 100644 --- a/ai/tasks/pending/TASK-132-document-rcon-first-historical-architecture.md +++ b/ai/tasks/done/TASK-132-document-rcon-first-historical-architecture.md @@ -1,7 +1,7 @@ --- id: TASK-132 title: Document RCON-first historical architecture -status: pending +status: done type: documentation team: PM supporting_teams: @@ -84,3 +84,10 @@ HLL Vietnam is building a historical/live data platform for Comunidad Hispana se - Stage only intended files. - Commit the completed implementation. - Push the branch to origin. + +## Outcome + +- Documented the RCON-first historical architecture in README, backend README, decisions and AI context. +- Covered RCON session capture, AdminLog ingestion/parser/storage, materialized matches/player stats, profile snapshot enrichment, public-scoreboard fallback boundaries, Elo/MMR paused state and Comunidad Hispana #03 disabled defaults. +- Added the requested manual Docker commands for AdminLog ingestion and historical capture. +- Validation: `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1` returned exit code 0, but its nested historical UI regression check emitted an existing frontend assertion about the missing recent-match external action label. No frontend/backend behavior files were changed in this documentation-only task. diff --git a/backend/README.md b/backend/README.md index ab98277..adbcaac 100644 --- a/backend/README.md +++ b/backend/README.md @@ -426,6 +426,28 @@ Captura historica prospectiva por RCON: como fallback para operaciones competitivas que aun no tienen paridad RCON - no promete backfill retroactivo de matches ya perdidos +Arquitectura RCON-first de datos historicos: + +- `app.rcon_historical_worker` captura sesiones RCON y mantiene ventanas + competitivas prospectivas. +- `app.rcon_admin_log_ingestion` ingiere AdminLog para el periodo solicitado. +- `app.rcon_admin_log_parser` normaliza eventos como inicio/cierre de partida, + kills, cambios de equipo, chat y mensajes de perfil. +- `app.rcon_admin_log_storage` persiste eventos AdminLog deduplicados y + snapshots de perfil de jugador. +- `app.rcon_admin_log_materialization` materializa partidas cerradas y + estadisticas por jugador desde eventos RCON. +- `app.rcon_historical_read_model` expone las lecturas historicas actuales y + solo recurre a `public-scoreboard` como fallback/enriquecimiento cuando RCON + no cubre la operacion. + +Comandos manuales equivalentes dentro de Docker Compose: + +```powershell +docker compose exec backend python -m app.rcon_admin_log_ingestion --minutes 1440 +docker compose exec backend python -m app.rcon_historical_worker capture +``` + Comandos manuales desde `backend/`: ```powershell diff --git a/docs/decisions.md b/docs/decisions.md index e8f20f1..e93b019 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -147,6 +147,19 @@ La politica por defecto para historico vuelve a ser RCON-first: mantiene como fallback controlado cuando RCON falla, no tiene cobertura util o no soporta todavia una operacion competitiva concreta. +La arquitectura historica RCON-first se compone de captura de sesiones RCON, +ingesta de AdminLog, parser de eventos, almacenamiento de eventos/snapshots y +materializacion de partidas y estadisticas por jugador. Los snapshots de perfil +procedentes de `MESSAGE` enriquecen lecturas de jugador, pero no sustituyen los +hechos de partida derivados de eventos RCON. + +Comandos operativos manuales: + +```powershell +docker compose exec backend python -m app.rcon_admin_log_ingestion --minutes 1440 +docker compose exec backend python -m app.rcon_historical_worker capture +``` + Esta decision no reactiva Elo/MMR dentro del arranque normal del backend. Las piezas Elo/MMR, migraciones, datos persistidos y modulos historicos se conservan, pero su operativa compleja sigue pausada y desacoplada salvo task