diff --git a/ai/architecture-index.md b/ai/architecture-index.md index 1e9240b..45b0eaf 100644 --- a/ai/architecture-index.md +++ b/ai/architecture-index.md @@ -71,5 +71,6 @@ Community website repository with a static landing in the current phase and a pl - The validated discovery for those historical sources is documented in `docs/historical-crcon-source-discovery.md`. - The persisted historical domain model for CRCON matches, players and ingestion runs is documented in `docs/historical-domain-model.md`. - The V1 monthly MVP scoring proposal for persisted historical player metrics is documented in `docs/monthly-mvp-ranking-scoring-design.md`. +- The audited boundary between direct live RCON and future event-driven RCON metrics is documented in `docs/rcon-data-capability-audit.md`. - 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`. diff --git a/ai/tasks/done/TASK-074-rcon-data-capability-audit.md b/ai/tasks/done/TASK-074-rcon-data-capability-audit.md new file mode 100644 index 0000000..ab08141 --- /dev/null +++ b/ai/tasks/done/TASK-074-rcon-data-capability-audit.md @@ -0,0 +1,108 @@ +# TASK-074-rcon-data-capability-audit + +## Goal +Auditar con precisión qué datos reales pueden obtenerse hoy mediante RCON en el proyecto, qué datos requieren captura de eventos o logs, y qué métricas serían viables para una futura V2 del ranking MVP. + +## Context +La integración live con RCON ya está funcionando en producción-like mode para el panel actual de servidores. Antes de evolucionar el sistema MVP mensual con métricas avanzadas, necesitamos saber con exactitud qué superficie de datos expone RCON realmente. + +Es importante no confundir: +- RCON puro +- CRCON / scoreboard público +- agregados históricos tipo HLL Records + +Algunas métricas deseadas para una futura V2 podrían incluir: +- kills por tipo de arma +- distinción de artillery / tank / infantry +- killer -> victim +- most_killed +- death_by +- teamkills por evento +- garrisons / OPs destruidos +- otras señales tácticas + +Pero todavía no sabemos cuáles salen realmente de RCON directo y cuáles requerirían una canalización propia de eventos o persistencia adicional. + +## Steps +1. Revisar la implementación actual del proveedor RCON: + - backend/app/rcon_client.py + - backend/app/providers/rcon_provider.py + - backend/app/data_sources.py +2. Auditar qué comandos/capacidades reales expone hoy el cliente RCON implementado. +3. Verificar qué datos live pueden obtenerse ya de forma directa: + - estado de servidor + - jugadores + - scoreboard actual + - mapa + - equipos + - cualquier otro campo ya expuesto +4. Investigar si la superficie RCON actual o el protocolo disponible permiten acceder a: + - kills por arma + - killer/victim + - death_by + - most_killed + - teamkills + - artillery/tank distinctions + - garrisons / OPs destruidos + - otras métricas tácticas útiles +5. Separar claramente para cada métrica: + - disponible por RCON directo hoy + - disponible solo si se captura un flujo de eventos/logs + - no confirmada + - no disponible +6. Documentar qué métricas podrían alimentar una V2 del ranking MVP y bajo qué condiciones. +7. Aclarar qué parte requeriría: + - ampliar el cliente RCON + - capturar eventos + - persistir nuevo histórico + - agregar métricas propias +8. No implementar todavía nuevas tablas, nuevas rutas, nuevas métricas visibles ni cambios de scoring. +9. Al completar la implementación: + - dejar el repositorio consistente + - hacer commit + - hacer push al remoto si el entorno lo permite + +## Files to Read First +- AGENTS.md +- ai/repo-context.md +- ai/architecture-index.md +- backend/README.md +- backend/app/rcon_client.py +- backend/app/providers/rcon_provider.py +- backend/app/data_sources.py +- backend/app/payloads.py +- docs/monthly-player-ranking-data-audit.md +- docs/monthly-mvp-ranking-scoring-design.md + +## Expected Files to Modify +- docs/rcon-data-capability-audit.md +- opcionalmente ai/architecture-index.md si conviene enlazar la auditoría +- opcionalmente docs/decisions.md si surge una decisión técnica clara sobre el alcance de RCON para V2 + +## Constraints +- No implementar todavía la V2 del MVP. +- No tocar producto visible. +- No confundir CRCON/source pública con RCON puro. +- No hacer cambios destructivos. +- Mantener el trabajo centrado en discovery técnico y viabilidad de métricas. + +## Validation +- Existe un documento claro que explica qué datos reales se pueden obtener hoy por RCON. +- Queda claro qué métricas requerirían eventos/logs o persistencia adicional. +- Queda claro qué subset de métricas sería viable para una futura V2 del MVP. +- Los cambios quedan committeados y se hace push si el entorno lo permite. + +## Change Budget +- Preferir menos de 4 archivos modificados o creados. +- Preferir menos de 220 líneas cambiadas. + +## Outcome +- Se documentó `docs/rcon-data-capability-audit.md` con el alcance real de RCON en la repo, separando RCON directo, CRCON público y métricas que requerirían pipeline de eventos/logs. +- La auditoría deja confirmado que la integración RCON operativa hoy solo cubre estado live basado en `ServerConnect`, `Login` y `GetServerInformation`. +- Quedó explícito que el proveedor histórico `rcon` sigue siendo un placeholder no operativo y que las métricas avanzadas para un MVP V2 no salen hoy de RCON directo en esta repo. +- `ai/architecture-index.md` enlaza ahora la nueva auditoría para mantener visible ese límite arquitectónico. + +## Validation Notes +- Revisión de código completada sobre `backend/app/rcon_client.py`, `backend/app/providers/rcon_provider.py`, `backend/app/data_sources.py` y `backend/app/payloads.py`. +- La auditoría se mantuvo dentro del alcance documental: no se añadieron tablas, rutas ni cambios visibles de producto. +- La evidencia del repositorio sigue separando correctamente live por RCON frente a histórico por CRCON / scoreboard público. diff --git a/docs/rcon-data-capability-audit.md b/docs/rcon-data-capability-audit.md new file mode 100644 index 0000000..4b115d9 --- /dev/null +++ b/docs/rcon-data-capability-audit.md @@ -0,0 +1,191 @@ +# RCON Data Capability Audit + +## Validation Date + +- 2026-03-24 + +## Scope + +Auditoria tecnica del alcance real de RCON en esta repo, separando con claridad: + +- RCON directo implementado hoy en el backend +- historico CRCON / scoreboard publico +- metricas que solo serian posibles con captura propia de eventos o logs + +No se implementa ninguna tabla, ruta, scoring ni captura adicional. + +## Evidence Reviewed + +- `backend/app/rcon_client.py` +- `backend/app/providers/rcon_provider.py` +- `backend/app/data_sources.py` +- `backend/app/payloads.py` +- `backend/README.md` +- `docs/historical-crcon-source-discovery.md` +- `docs/monthly-player-ranking-data-audit.md` +- `docs/monthly-mvp-ranking-scoring-design.md` + +## Current RCON Surface In This Repository + +La implementacion RCON actual es minima y solo cubre estado live. + +Capacidades confirmadas en codigo hoy: + +- handshake `ServerConnect` +- autenticacion `Login` +- consulta `GetServerInformation` + +No hay evidencia en la repo de otros comandos RCON ya integrados para: + +- eventos de kill +- detalle por arma +- relaciones killer -> victim +- teamkills por evento +- destruccion de garrisons u OPs +- historico de partidas cerradas + +## What The Current Live Provider Exposes Today + +El proveedor `RconLiveDataSource` solo normaliza estos campos para `/api/servers`: + +- `external_server_id` +- `server_name` +- `status` +- `players` +- `max_players` +- `current_map` +- `region` +- `source_name` +- `snapshot_origin` +- `source_ref` + +Esto significa que RCON directo hoy ya alimenta de forma confirmada: + +- disponibilidad online del servidor +- nombre del servidor +- numero de jugadores actual +- capacidad maxima +- mapa actual +- metadata de procedencia del snapshot + +## Data That Is Not Exposed By Direct RCON Today + +Aunque la task pide revisar equipos, scoreboard actual y otros campos live, la +repo no confirma que el proveedor actual los este devolviendo hoy. + +No quedan expuestos en el snapshot live actual: + +- composicion por equipos +- scoreboard de jugadores en tiempo real +- kills por jugador en la partida en curso +- deaths por jugador en la partida en curso +- support/combat/offense/defense live +- teamkills live + +Importante: + +- esto no prueba que el protocolo HLL RCON no pueda ofrecer mas cosas +- solo prueba que la implementacion actual de esta repo no las consulta ni las + serializa + +## Historical Boundary + +La separacion entre live e historico queda clara en la repo: + +- `get_live_data_source()` puede resolver `rcon` +- `get_historical_data_source()` devuelve un placeholder `RconHistoricalDataSource` +- ese proveedor historico lanza `RuntimeError("Historical RCON provider is not implemented yet.")` + +Conclusion operativa: + +- RCON esta operativo hoy para estado live de `/api/servers` +- RCON no esta operativo hoy para ingesta historica +- el historico reutilizable del proyecto sigue viniendo de CRCON / scoreboard publico + +## Capability Matrix For Future MVP V2 Metrics + +| Metrica / senal | RCON directo hoy en esta repo | Requeriria eventos/logs + persistencia | Estado actual | +| --- | --- | --- | --- | +| Estado del servidor | Si | No | Disponible | +| Jugadores actuales totales | Si | No | Disponible | +| Capacidad maxima | Si | No | Disponible | +| Mapa actual | Si | No | Disponible | +| Equipos live | No confirmado | Posiblemente no, depende de ampliar cliente | No expuesto hoy | +| Scoreboard live por jugador | No confirmado | Posiblemente no, depende de ampliar cliente | No expuesto hoy | +| Kills por arma | No | Si | Requiere pipeline nuevo | +| Distincion artillery / tank / infantry | No | Si | Requiere pipeline nuevo | +| Killer -> victim | No | Si | Requiere pipeline nuevo | +| `most_killed` | No | Si | Requiere pipeline nuevo | +| `death_by` | No | Si | Requiere pipeline nuevo | +| Teamkills por evento | No | Si | Requiere pipeline nuevo | +| Teamkills agregados por partida/mes | No desde RCON actual | Si | Requiere pipeline nuevo | +| Garrisons destruidos | No confirmado | Si como minimo | No confirmado | +| OPs destruidos | No confirmado | Si como minimo | No confirmado | +| Otras metricas tacticas finas | No | Si | Requiere pipeline nuevo | +| Partidas cerradas historicas | No | Si | No disponible hoy via RCON | + +## What Can Feed An MVP V2 From RCON + +Subset viable usando solo RCON directo ya implementado: + +- ninguno de los componentes avanzados de scoring MVP +- solo datos de presencia live del servidor, utiles para panel operativo pero no + para ranking mensual + +Subset viable si se amplia solo el cliente RCON pero sin pipeline historico: + +- quiza mas detalle live si el protocolo ofrece comandos adicionales +- aun asi no bastaria para un ranking mensual auditable, porque faltaria + persistencia por evento o por partida cerrada + +Subset viable si se construye una linea nueva de eventos/logs RCON: + +- kills por arma +- killer/victim +- teamkills por evento +- clasificacion artillery/tank/infantry +- senales tacticas si el origen real las emite + +Condiciones minimas para que eso sirva a un MVP V2: + +- ampliar el cliente RCON con comandos o feeds adicionales reales +- capturar eventos de forma continua fuera del request path HTTP +- persistir historico propio por partida, jugador y evento +- definir agregados reproducibles para mes y servidor + +## Separation From CRCON / Public Scoreboard + +La repo ya confirma que ciertas metricas avanzadas existen en CRCON publico, +pero eso no debe confundirse con RCON directo. + +La evidencia actual de CRCON/scoreboard publico incluye campos como: + +- `kills_by_type` +- `most_killed` +- `death_by` +- `weapons` +- `death_by_weapons` + +Eso pertenece al historico JSON publico ya documentado y no a la superficie +RCON hoy implementada en `rcon_client.py`. + +## Practical Conclusion + +Para esta repo, la respuesta precisa hoy es: + +- RCON directo sirve para estado live de servidores +- RCON directo no sirve todavia para alimentar un MVP mensual V2 +- cualquier MVP V2 con armas, duelos, teamkills por evento o tacticas requiere + una canalizacion nueva de eventos/logs y persistencia historica propia +- garrisons y OPs siguen sin evidencia confirmada en la repo como metrica + disponible por RCON + +## Recommended Next Step + +Antes de disenar scoring V2 sobre RCON, la siguiente decision tecnica correcta +seria una task separada de discovery para definir: + +- si el origen RCON real del servidor expone mas comandos aparte de `GetServerInformation` +- si existe flujo de eventos reutilizable +- que granularidad y frecuencia tendria la persistencia de esos eventos +- que subset minimo merece convertirse en modelo historico propio