comunidadhll/docs/rcon-historical-ingestion-design.md

# RCON Historical Ingestion Design

## Validation Date

- 2026-03-25

## Scope

Definir si la repo puede soportar historico por RCON con la implementacion
actual y, si no puede hacerlo de forma retroactiva, dejar una arquitectura
minima y defendible para una primera captura prospectiva.

Este documento se limita a la evidencia local de la repo. No asume comandos
RCON no integrados ni capacidades externas no demostradas aqui.

## Evidence Reviewed

- `backend/app/data_sources.py`
- `backend/app/providers/rcon_provider.py`
- `backend/app/rcon_client.py`
- `backend/app/historical_ingestion.py`
- `backend/app/historical_storage.py`
- `backend/app/player_event_worker.py`
- `backend/app/player_event_storage.py`
- `backend/README.md`
- `docs/rcon-data-capability-audit.md`
- `docs/crcon-advanced-metrics-origin-audit.md`

## Current State In Code

La separacion entre live e historico ya existe en la seleccion de proveedores:

- `get_live_data_source()` puede resolver `rcon`
- `get_historical_data_source()` puede resolver `rcon`, pero hoy devuelve un
  placeholder que falla

La implementacion RCON real disponible en la repo es minima y esta concentrada
en `backend/app/rcon_client.py`.

Comandos soportados hoy en codigo:

- `ServerConnect`
- `Login`
- `GetServerInformation`

No hay evidencia local de otros comandos ya integrados para:

- scoreboards por jugador
- detalle de partida cerrada
- eventos kill por kill
- logs tacticos
- historico retroactivo de matches cerrados

## Payload Available Today

La salida efectiva que la repo consume desde RCON hoy es la normalizada por
`query_live_server_state()`:

- `external_server_id`
- `server_name`
- `status`
- `players`
- `max_players`
- `current_map`
- `region`
- `source_name`
- `snapshot_origin`
- `source_ref`

Inferencia basada en `rcon_client.py`:

- el payload remoto de `GetServerInformation` contiene como minimo
  `serverName`, `playerCount`, `maxPlayerCount` y `mapId` o `mapName`
- la repo no persiste hoy el payload crudo ni deriva entidades historicas de
  match o jugador a partir de RCON

## Operational Frequency Assessment

Inferencia basada en la implementacion actual:

- cada pasada por target abre una conexion TCP
- realiza handshake `ServerConnect`
- autentica con `Login`
- ejecuta una consulta `GetServerInformation`

Con este alcance, una frecuencia inicial razonable para captura prospectiva es:

- cada `60` a `300` segundos para operativa normal
- `30` segundos solo como validacion o monitoreo puntual

No hay evidencia en la repo para defender un polling mas agresivo de forma
sostenida ni para asegurar que aportaria historico competitivo util.

## Viability Decision

Conclusion principal:

- no viable hoy para historico real retroactivo de partidas cerradas con el
  cliente actual
- viable solo para captura prospectiva

Motivos:

- el cliente actual solo consulta estado live puntual
- no existe base local para reconstruir partidas ya cerradas
- no existe feed raw de eventos ni logs persistidos
- `RconHistoricalDataSource` sigue siendo un placeholder y no puede sustituir a
  `public-scoreboard`

Conclusion secundaria:

- una capa historica parcial por RCON si es defendible, pero solo si se define
  como captura prospectiva de muestras live y no como backfill de matches ya
  perdidos

## Recommended Minimal Architecture

### Storage

Separar completamente la persistencia prospectiva RCON del historico actual
`historical_*`.

Tablas minimas recomendadas:

- `rcon_historical_targets`
  - identidad estable del target configurado
  - ultimo estado conocido de configuracion
- `rcon_historical_capture_runs`
  - una fila por ejecucion del worker
  - estado, inicio, fin, errores y target scope
- `rcon_historical_samples`
  - una fila por muestra y target
  - `captured_at`
  - identidad de target
  - payload normalizado
  - payload crudo opcional de `GetServerInformation`

Si se quiere checkpoint explicito desde la primera version:

- `rcon_historical_checkpoints`
  - `target_key`
  - `last_successful_capture_at`
  - `last_sample_at`
  - `last_error`

### Workers

Worker dedicado fuera del request path HTTP:

- `python -m app.rcon_historical_worker capture`
- `python -m app.rcon_historical_worker loop --interval 120`

Responsabilidades:

- cargar `HLL_BACKEND_RCON_TARGETS`
- consultar cada target con el cliente RCON actual
- persistir run tracking
- persistir muestras idempotentes por target y timestamp
- actualizar checkpoints

### Checkpoints

Como no existe backfill retroactivo real, el checkpoint no debe modelarse como
pagina o offset de archivo historico. Debe modelarse como tiempo de captura.

Checkpoint minimo defendible:

- ultimo `captured_at` exitoso por target
- ultimo error por target
- ultimo run exitoso global

### Compatibility With `public-scoreboard`

Politica recomendada:

- `public-scoreboard` sigue siendo la fuente historica principal para:
  - leaderboards semanales y mensuales
  - MVP V1 y V2
  - recent matches cerrados
  - player events derivados de la capa publica actual
- RCON prospectivo convive en una linea paralela para:
  - cobertura temporal hacia delante
  - disponibilidad del servidor
  - actividad reciente
  - trazabilidad de frescura por target

## Recommended Degradation Policy

Si en una fase posterior se habilita `HLL_BACKEND_HISTORICAL_DATA_SOURCE=rcon`,
la degradacion minima correcta es esta:

- solo exponer endpoints o bloques claramente soportados por la persistencia
  prospectiva RCON
- no simular leaderboards completos cuando no existan
- devolver metadata de cobertura y frescura antes que rankings vacios

Contratos defendibles en una primera lectura minima:

- resumen de cobertura por servidor
- actividad reciente por servidor
- estado de frescura
- rango temporal disponible

Contratos que deben seguir dependiendo de `public-scoreboard` hasta nueva
evidencia:

- weekly leaderboards completos
- monthly leaderboards completos
- monthly MVP V1
- monthly MVP V2
- player profiles competitivos
- equivalencia completa con `historico.html`

## Recommended Phases

### Phase 1: Prospective Capture

Objetivo:

- empezar a guardar muestras live RCON hacia delante

Incluye:

- storage separado
- worker dedicado
- run tracking
- checkpoints temporales
- ejecucion manual y en loop

No incluye:

- backfill retroactivo
- paridad con `public-scoreboard`
- endpoints competitivos nuevos

### Phase 2: Minimal Operational Read Model

Objetivo:

- leer la persistencia prospectiva RCON sin consultar RCON on-demand en HTTP

Incluye:

- resumen por servidor
- ultima muestra
- cobertura disponible
- actividad reciente

### Phase 3: Competitive Metrics Only If Signal Improves

Objetivo:

- evaluar si aparecen comandos, eventos o logs suficientes para enriquecer la
  capa historica RCON

Solo deberia abrirse si existe evidencia real de:

- eventos reutilizables
- scoreboards historificables
- granularidad por jugador o por encounter

## Final Recommendation

La decision tecnica correcta para esta repo es:

- mantener `public-scoreboard` como fuente historica por defecto
- tratar RCON historico como una linea prospectiva separada
- no prometer reconstruccion retroactiva con el cliente actual
- abrir implementacion incremental en dos tasks:
  - captura prospectiva persistida
  - lectura minima sobre persistencia local