rgonsal/comunidadhll
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6f0a781fb8e66b1de473bee78d5fded0f4b7e6ec
comunidadhll/backend/README.md
devRaGonSa 6f0a781fb8 initial export
2026-06-04 09:26:38 +02:00

58 KiB
Raw Blame History

Backend

Esta carpeta contiene el bootstrap minimo del futuro backend principal en Python para HLL Vietnam.

Objetivo en esta fase

  • dejar un punto de entrada claro para la aplicacion
  • validar que el backend puede arrancar localmente
  • exponer rutas placeholder coherentes con el contrato frontend-backend

Stack actual del bootstrap

  • Python 3
  • libreria estandar de Python (http.server, sin frameworks ni dependencias externas)

Estructura minima

backend/
|-- README.md
|-- requirements.txt
`-- app/
    |-- a2s_client.py
    |-- __init__.py
    |-- collector.py
    |-- main.py
    |-- historical_ingestion.py
    |-- historical_models.py
    |-- historical_runner.py
    |-- historical_storage.py
    |-- normalizers.py
    |-- payloads.py
    |-- routes.py
    |-- server_targets.py
    `-- snapshots.py

La persistencia local de desarrollo se crea bajo backend/data/ cuando el colector la necesita por primera vez.

app es el paquete Python del backend. El archivo correcto del paquete es backend/app/__init__.py; no debe existir una variante init.py.

Punto de entrada

El entrypoint real del backend es el modulo app.main, ubicado en backend/app/main.py.

Desde la carpeta backend/, se puede arrancar localmente con:

python -m app.main

Ese comando usa imports relativos de paquete (from .routes import ...), por lo que la forma soportada de arranque es por modulo y no ejecutando el archivo como script suelto.

Por defecto escuchara en 127.0.0.1:8000.

Variables opcionales:

  • HLL_BACKEND_HOST
  • HLL_BACKEND_PORT
  • HLL_BACKEND_ALLOWED_ORIGINS
  • HLL_BACKEND_REFRESH_INTERVAL_SECONDS
  • HLL_BACKEND_LIVE_DATA_SOURCE
  • HLL_BACKEND_HISTORICAL_DATA_SOURCE
  • HLL_BACKEND_RCON_TIMEOUT_SECONDS
  • HLL_BACKEND_RCON_TARGETS
  • HLL_RCON_HISTORICAL_CAPTURE_INTERVAL_SECONDS
  • HLL_RCON_HISTORICAL_CAPTURE_MAX_RETRIES
  • HLL_RCON_HISTORICAL_CAPTURE_RETRY_DELAY_SECONDS
  • HLL_RCON_BACKFILL_CHUNK_HOURS
  • HLL_RCON_BACKFILL_SLEEP_SECONDS
  • HLL_RCON_BACKFILL_MAX_DAYS_BACK
  • HLL_BACKEND_RCON_ADMIN_LOG_LOOKBACK_MINUTES
  • HLL_BACKEND_SQLITE_WRITER_TIMEOUT_SECONDS
  • HLL_BACKEND_SQLITE_BUSY_TIMEOUT_MS
  • HLL_BACKEND_WRITER_LOCK_TIMEOUT_SECONDS
  • HLL_BACKEND_WRITER_LOCK_POLL_INTERVAL_SECONDS
  • HLL_HISTORICAL_CRCON_PAGE_SIZE
  • HLL_HISTORICAL_CRCON_TIMEOUT_SECONDS
  • HLL_HISTORICAL_CRCON_DETAIL_WORKERS
  • HLL_HISTORICAL_CRCON_REQUEST_RETRIES
  • HLL_HISTORICAL_CRCON_RETRY_DELAY_SECONDS
  • HLL_HISTORICAL_REFRESH_INTERVAL_SECONDS
  • HLL_HISTORICAL_REFRESH_OVERLAP_HOURS
  • HLL_HISTORICAL_SNAPSHOT_REFRESH_INTERVAL_SECONDS
  • HLL_HISTORICAL_FULL_SNAPSHOT_EVERY_RUNS
  • HLL_HISTORICAL_REFRESH_MAX_RETRIES
  • HLL_HISTORICAL_REFRESH_RETRY_DELAY_SECONDS
  • HLL_BACKEND_SQLITE_WRITER_TIMEOUT_SECONDS
  • HLL_BACKEND_SQLITE_BUSY_TIMEOUT_MS
  • HLL_BACKEND_WRITER_LOCK_TIMEOUT_SECONDS
  • HLL_BACKEND_WRITER_LOCK_POLL_INTERVAL_SECONDS
  • HLL_HISTORICAL_WEEKLY_FALLBACK_MIN_MATCHES
  • HLL_HISTORICAL_WEEKLY_FALLBACK_MAX_WEEKDAY

Variables especialmente relevantes para Docker y Compose:

  • HLL_BACKEND_HOST
  • HLL_BACKEND_PORT
  • HLL_BACKEND_DATABASE_URL
  • HLL_BACKEND_STORAGE_PATH
  • HLL_BACKEND_ALLOWED_ORIGINS
  • HLL_BACKEND_LIVE_DATA_SOURCE
  • HLL_BACKEND_HISTORICAL_DATA_SOURCE
  • HLL_BACKEND_RCON_TIMEOUT_SECONDS
  • HLL_BACKEND_RCON_TARGETS
  • HLL_HISTORICAL_CRCON_PAGE_SIZE
  • HLL_HISTORICAL_CRCON_TIMEOUT_SECONDS
  • HLL_HISTORICAL_CRCON_DETAIL_WORKERS
  • HLL_HISTORICAL_CRCON_REQUEST_RETRIES
  • HLL_HISTORICAL_CRCON_RETRY_DELAY_SECONDS
  • HLL_HISTORICAL_REFRESH_OVERLAP_HOURS
  • HLL_HISTORICAL_SNAPSHOT_REFRESH_INTERVAL_SECONDS
  • HLL_HISTORICAL_FULL_SNAPSHOT_EVERY_RUNS
  • HLL_HISTORICAL_REFRESH_MAX_RETRIES
  • HLL_HISTORICAL_REFRESH_RETRY_DELAY_SECONDS

Para ejecucion containerizada, el repositorio incluye tambien:

  • backend/Dockerfile
  • backend/.dockerignore
  • backend/.env.example

El contenedor usa el mismo entrypoint real del proyecto:

python -m app.main

Dentro del contenedor arranca por defecto con:

  • HLL_BACKEND_HOST=0.0.0.0
  • HLL_BACKEND_PORT=8000
  • HLL_BACKEND_STORAGE_PATH=/app/data/hll_vietnam_dev.sqlite3

Compose configura ademas HLL_BACKEND_DATABASE_URL para que PostgreSQL sea el almacenamiento autoritativo de la fase 1 RCON: muestras/ventanas de captura, AdminLog, snapshots de perfil y partidas/estadisticas materializadas. Sin esa variable, la ejecucion local mantiene fallback SQLite para esos dominios.

Diagnostico rapido del backend activo:

python -m app.storage_diagnostics

La salida lista el backend RCON activo, counts de las tablas migradas, la ultima partida materializada por servidor y que superficies siguen temporalmente en SQLite en esta fase.

Build local:

docker build -t hll-vietnam-backend ./backend

Ejecucion local con persistencia bind-mounted:

docker run --rm `
  -p 8000:8000 `
  --env-file backend/.env.example `
  -v ${PWD}\backend\data:/app/data `
  hll-vietnam-backend

Si se prefiere no usar --env-file, el contenedor puede arrancar solo con sus defaults para host, puerto y path de SQLite. El bind mount de /app/data sigue siendo la forma recomendada de no perder persistencia al recrear el contenedor.

El frontend/index.html viene preparado para volver a consultar el bloque de servidores cada 120000 ms (120s) sin recargar la pagina completa. La landing lee ese valor desde data-server-refresh-ms, por lo que puede ajustarse en el HTML si una demo local necesita un intervalo distinto.

Valor por defecto de HLL_BACKEND_ALLOWED_ORIGINS:

  • null
  • http://127.0.0.1
  • http://127.0.0.1:5500
  • http://127.0.0.1:8080
  • http://localhost
  • http://localhost:5500
  • http://localhost:8080

Esto cubre el caso de abrir frontend/index.html directamente desde file:// y los puertos locales mas habituales cuando el frontend se sirve con un servidor sencillo.

Prueba local recomendada para validar frontend y backend juntos:

  1. En una terminal, desde backend/, arrancar el backend:

    python -m app.main

  2. En otra terminal, desde frontend/, servir la landing:

    python -m http.server 8080

  3. Abrir http://localhost:8080.

Si se necesita otra combinacion de origenes locales, puede sobrescribirse HLL_BACKEND_ALLOWED_ORIGINS con una lista separada por comas. El backend normaliza espacios y barras finales para mantener la comparacion con el header Origin del navegador.

Endpoints placeholder disponibles

  • GET /health
  • GET /api/community
  • GET /api/trailer
  • GET /api/discord
  • GET /api/servers
  • GET /api/servers/latest
  • GET /api/servers/history?limit=20
  • GET /api/servers/{id}/history?limit=20
  • GET /api/historical/weekly-top-kills?limit=10&server=comunidad-hispana-01
  • GET /api/historical/weekly-leaderboard?metric=kills&limit=10&server=comunidad-hispana-01
  • GET /api/historical/leaderboard?timeframe=monthly&metric=kills&limit=10&server=comunidad-hispana-01
  • GET /api/historical/monthly-mvp?limit=10&server=comunidad-hispana-01
  • GET /api/historical/monthly-mvp-v2?limit=10&server=comunidad-hispana-01
  • GET /api/historical/player-events?view=most-killed&limit=10&server=comunidad-hispana-01
  • GET /api/historical/recent-matches?limit=20&server=comunidad-hispana-01
  • GET /api/historical/server-summary?server=comunidad-hispana-01
  • GET /api/historical/snapshots/server-summary?server=comunidad-hispana-01
  • GET /api/historical/snapshots/weekly-leaderboard?metric=kills&limit=10&server=comunidad-hispana-01
  • GET /api/historical/snapshots/leaderboard?timeframe=monthly&metric=kills&limit=10&server=comunidad-hispana-01
  • GET /api/historical/snapshots/monthly-mvp?limit=10&server=comunidad-hispana-01
  • GET /api/historical/snapshots/monthly-mvp-v2?limit=10&server=comunidad-hispana-01
  • GET /api/historical/snapshots/player-events?view=most-killed&limit=10&server=comunidad-hispana-01
  • GET /api/historical/snapshots/recent-matches?limit=6&server=comunidad-hispana-01
  • GET /api/historical/player-profile?player=steam%3A76561198000000000

GET /health expone tambien:

  • live_data_source
  • historical_data_source

GET /api/servers trata el ultimo snapshot persistido como cache local y lo reutiliza solo si sigue dentro del objetivo de 120 segundos. Si ese snapshot esta vencido, el endpoint intenta primero una consulta RCON real inmediata contra los targets configurados. Solo si RCON falla o no devuelve snapshots utilizables, cae a A2S de forma controlada antes de responder.

La respuesta incluye metadata de frescura pensada para frontend:

  • last_snapshot_at
  • snapshot_age_seconds
  • snapshot_age_minutes
  • max_snapshot_age_seconds
  • is_stale
  • freshness
  • source
  • refresh_attempted
  • refresh_status
  • primary_source
  • selected_source
  • fallback_used
  • fallback_reason
  • source_attempts

Si la consulta real falla, /api/servers devuelve el ultimo snapshot valido disponible marcado como stale. Si no existe ningun snapshot valido, responde items: [] en lugar de reintroducir servidores de respaldo ajenos a la comunidad. Cada respuesta deja tambien trazabilidad de arbitraje de fuente para que sea visible si se sirvio RCON directo o si hubo fallback a A2S.

Los endpoints historicos leen la persistencia local SQLite creada por el colector. Si todavia no hay snapshots guardados, responden status: "ok" con items: [] para mantener un contrato simple en desarrollo.

Seleccion de fuente de datos

El backend separa ahora la fuente de datos del contrato HTTP del producto. Esto permite cambiar proveedores por entorno sin tocar routes.py, payloads de UI ni el formato consumido por frontend.

Variables nuevas:

  • HLL_BACKEND_LIVE_DATA_SOURCE
  • HLL_BACKEND_HISTORICAL_DATA_SOURCE

Valores soportados en esta fase:

  • live:
    • rcon como camino primario recomendado
    • a2s como fallback legacy o override explicito
  • historico:
    • rcon como camino primario recomendado para captura y writer path primario
    • public-scoreboard como fallback legacy controlado

Defaults actuales:

  • HLL_BACKEND_LIVE_DATA_SOURCE=rcon
  • HLL_BACKEND_HISTORICAL_DATA_SOURCE=rcon

La seleccion efectiva se resuelve en app/data_sources.py y en adapters dedicados dentro de app/providers/:

  • get_live_data_source() entrega el proveedor usado por payloads.py cuando /api/servers necesita un refresh real
  • get_historical_data_source() entrega el proveedor usado por historical_ingestion.py para bootstrap y refresh incremental
  • providers/public_scoreboard_provider.py encapsula la semantica actual del scoreboard/CRCON publico bajo el contrato historico
  • providers/rcon_provider.py encapsula el proveedor live basado en comandos RCON HLL v2 mediante ServerConnect, Login y GetServerInformation

Proveedores operativos en esta fase:

  • live rcon
  • live a2s
  • historico rcon solo para read model minimo y captura prospectiva
  • historico public-scoreboard como fallback para cobertura competitiva sin paridad RCON

Politica funcional actual:

  • live:
    • RCON primero
    • A2S solo si RCON falla o no devuelve snapshots utilizables
  • historico/recopilacion:
    • RCON primero
    • public-scoreboard solo si RCON no soporta aun esa operacion concreta o falla la captura primaria

Estado real de "historico por RCON" en esta repo:

  • no existe backfill retroactivo por RCON con el cliente actual
  • la viabilidad documentada hoy es solo para captura prospectiva separada
  • historical_ingestion.py intenta primero el writer path prospectivo RCON
  • la persistencia competitiva historical_* sigue necesitando fallback a public-scoreboard mientras RCON no exponga pagina historica/detalle de match cerrada con paridad suficiente
  • el diseno tecnico de esa linea prospectiva queda en docs/rcon-historical-ingestion-design.md

Variables especificas de RCON live:

  • HLL_BACKEND_RCON_TIMEOUT_SECONDS
  • HLL_BACKEND_RCON_TARGETS

Variables especificas de captura historica prospectiva RCON:

  • HLL_RCON_HISTORICAL_CAPTURE_INTERVAL_SECONDS
  • HLL_RCON_HISTORICAL_CAPTURE_MAX_RETRIES
  • HLL_RCON_HISTORICAL_CAPTURE_RETRY_DELAY_SECONDS

HLL_BACKEND_RCON_TARGETS acepta un array JSON con:

  • name
  • slug opcional como alias legacy
  • host
  • port
  • password
  • external_server_id opcional
  • region opcional
  • game_port opcional
  • query_port opcional
  • source_name opcional

Compatibilidad operativa del loader:

  • si llega slug pero no external_server_id, el backend reutiliza slug como external_server_id
  • si falta name pero existe slug, el backend genera un nombre razonable a partir del slug en vez de dejar Unnamed RCON target
  • los errores de validacion indican el campo que falta y las claves efectivamente recibidas

Timeout recomendado por defecto:

  • HLL_BACKEND_RCON_TIMEOUT_SECONDS=20

Diagnostico operativo del cliente RCON:

  • el cliente informa ahora el stage exacto del fallo cuando puede distinguirlo
  • stages observables:
    • tcp_connect
    • server_connect_request
    • server_connect_response
    • xor_key_decode
    • login_request
    • login_response
    • get_server_information_request
    • get_server_information_response
    • payload_decode
    • unexpected_response
    • timeout
  • esto mejora el diagnostico del protocolo, pero no resuelve por si solo la conectividad real si el servidor acepta TCP y luego no responde al handshake RCON o al comando GetServerInformation

Ejemplo:

$env:HLL_BACKEND_RCON_TARGETS='[
  {
    "name": "Comunidad Hispana #01",
    "slug": "comunidad-hispana-01",
    "host": "152.114.195.174",
    "port": 7779,
    "password": "replace-me",
    "external_server_id": "comunidad-hispana-01",
    "region": "ES",
    "game_port": null,
    "query_port": null,
    "source_name": "community-hispana-rcon"
  }
]'

Runbook operativo minimo:

  • modo recomendado por defecto:
    • HLL_BACKEND_LIVE_DATA_SOURCE=rcon
    • HLL_BACKEND_HISTORICAL_DATA_SOURCE=rcon
    • usar solo comunidad-hispana-01 y comunidad-hispana-02 en los targets RCON por defecto
  • modo historico/RCON avanzado:
    • iniciar workers solo de forma explicita
    • no reintroducir comunidad-hispana-03 salvo validacion nueva
  • override legacy live/A2S:
    • HLL_BACKEND_LIVE_DATA_SOURCE=a2s
    • HLL_BACKEND_HISTORICAL_DATA_SOURCE=rcon

Verificacion minima del proveedor activo:

Invoke-WebRequest http://127.0.0.1:8000/health | Select-Object -Expand Content

La respuesta incluye live_data_source y historical_data_source, util para confirmar si la instancia esta usando a2s o rcon para live.

Captura historica prospectiva por RCON:

  • se ejecuta fuera del request path HTTP
  • persiste muestras live hacia delante en tablas rcon_historical_*
  • usa RCON como camino historico primario y mantiene public-scoreboard solo 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:

docker compose exec backend python -m app.rcon_admin_log_ingestion --minutes 1440
docker compose exec backend python -m app.rcon_historical_worker capture

Backfill historico RCON/AdminLog:

  • runbook: docs/historical-rcon-backfill.md

  • ejemplo seco:

    docker compose run --rm rcon-historical-worker python -m app.rcon_historical_backfill --ensure-recent-matches 100 --servers comunidad-hispana-01,comunidad-hispana-02 --dry-run

Comandos manuales desde backend/:

python -m app.rcon_historical_worker capture
python -m app.rcon_historical_worker capture --target comunidad-hispana-01
python -m app.rcon_historical_worker loop --interval 120

Runbook minimo:

  • una pasada manual sobre todos los targets RCON configurados:

    python -m app.rcon_historical_worker capture

  • una validacion acotada sobre un target concreto:

    python -m app.rcon_historical_worker capture --target comunidad-hispana-01

  • un worker local en bucle:

    python -m app.rcon_historical_worker loop --interval 120 --max-runs 1

La salida del worker incluye:

  • target_scope
  • captured_at
  • targets
  • errors
  • storage_status

Cuando una captura falla, cada error incluye como minimo:

  • target_key
  • external_server_id
  • name
  • host
  • port
  • timeout_seconds
  • error_type
  • error_stage
  • message

error_type intenta clasificar al menos:

  • timeout
  • auth/login
  • connection-refused
  • payload-invalid
  • other-error

La persistencia queda separada del historico historical_* actual y usa:

  • rcon_historical_targets
  • rcon_historical_capture_runs
  • rcon_historical_samples
  • rcon_historical_checkpoints

Lectura historica minima cuando HLL_BACKEND_HISTORICAL_DATA_SOURCE=rcon:

  • endpoints soportados hoy directamente por RCON persistido:
    • GET /api/historical/server-summary
    • GET /api/historical/recent-matches
  • lo que devuelven:
    • cobertura por target RCON configurado
    • frescura del ultimo capture exitoso
    • actividad reciente persistida
  • endpoints que hoy caen automaticamente a public-scoreboard para mantener el contrato completo:
    • GET /api/historical/weekly-top-kills
    • GET /api/historical/weekly-leaderboard
    • GET /api/historical/leaderboard
    • GET /api/historical/monthly-mvp
    • GET /api/historical/monthly-mvp-v2
    • GET /api/historical/player-events
    • GET /api/historical/player-profile
    • GET /api/historical/snapshots/*

Cuando esos endpoints se consultan con historical_data_source=rcon, el backend intenta primero RCON para la operacion soportada y, si no hay cobertura o la capacidad aun no existe, cae automaticamente a public-scoreboard. La respuesta deja trazabilidad con primary_source, selected_source, fallback_used, fallback_reason y source_attempts.

Criterio de estructura

  • __init__.py declara el paquete app y reexporta las utilidades publicas minimas del bootstrap.
  • collector.py define el flujo minimo de captura para desarrollo usando una fuente controlada.
  • a2s_client.py encapsula una consulta minima A2S_INFO por UDP para probar servidores reales sin acoplar todavia el backend a una fuente mas compleja.
  • rcon_client.py encapsula una conexion minima HLL RCON v2 por TCP con ServerConnect, XOR key base64, authToken y GetServerInformation para consultas live de produccion.
  • config.py centraliza host, puerto y allowlist minima de origenes locales.
  • data_sources.py define los contratos y la seleccion por entorno para live e historico.
  • historical_ingestion.py intenta primero el writer path RCON y, si hace falta poblar historical_*, cae de forma explicita a la capa JSON publica de CRCON.
  • historical_models.py fija las entidades historicas minimas del dominio.
  • historical_snapshots.py fija los tipos y selectores validos de snapshots historicos precalculados.
  • historical_snapshot_storage.py persiste snapshots historicos precalculados listos para lectura rapida.
  • historical_runner.py ejecuta refresh incremental periodico con reintentos basicos.
  • historical_storage.py prepara la persistencia historical_* y las consultas agregadas iniciales.
  • main.py contiene el entrypoint HTTP y la creacion del servidor.
  • normalizers.py transforma registros crudos o respuestas A2S a un modelo comun del colector.
  • routes.py resuelve las rutas GET soportadas.
  • payloads.py centraliza respuestas placeholder y mock.
  • server_targets.py registra targets A2S de prueba de forma desacoplada del flujo principal del colector.
  • snapshots.py construye snapshots consistentes con timestamp comun de captura.
  • storage.py prepara una persistencia local minima en SQLite para game_sources, servers y server_snapshots.

Persistencia local minima

El backend ya puede guardar snapshots en un SQLite local de desarrollo usando solo libreria estandar de Python. Esta base minima sigue el modelo logico de:

  • game_sources
  • servers
  • server_snapshots
  • historical_servers
  • historical_maps
  • historical_matches
  • historical_players
  • historical_player_match_stats
  • historical_ingestion_runs

Por defecto el archivo se crea en:

backend/data/hll_vietnam_dev.sqlite3

En Docker, ese mismo rol de persistencia debe montarse fuera del contenedor en:

/app/data/hll_vietnam_dev.sqlite3

Politica comun SQLite para writers:

  • timeout explicito compartido
  • PRAGMA foreign_keys = ON
  • PRAGMA journal_mode = WAL
  • PRAGMA busy_timeout
  • row_factory = sqlite3.Row

Esta politica se aplica de forma uniforme a las capas writer-capable que comparten el mismo SQLite, incluyendo:

  • historical_storage.py
  • player_event_storage.py
  • rcon_historical_storage.py
  • storage.py

Politica read-only para historico:

  • las rutas de lectura de historical_storage.py no ejecutan ya initialize_historical_storage()
  • si el SQLite historico todavia no existe, esas lecturas devuelven resultados vacios o defaults estables sin crear archivo ni correr seed/migraciones
  • cuando el archivo ya existe, esas lecturas abren mode=ro con row_factory = sqlite3.Row y PRAGMA busy_timeout
  • la inicializacion, migraciones, seed y normalizaciones siguen reservadas al writer path explicito

Variable opcional:

  • HLL_BACKEND_STORAGE_PATH
  • HLL_BACKEND_A2S_TARGETS

La base logica sigue documentada en docs/stats-database-schema-foundation.md para snapshots live y en docs/historical-domain-model.md para el historico CRCON. Esta implementacion no introduce ORM, migraciones ni una decision de almacenamiento productivo.

Snapshots historicos precalculados

La capa historica persiste ahora los snapshots precalculados orientados a UI como archivos JSON independientes en disco, separados del SQLite del historico bruto. Esta capa esta preparada para guardar:

  • server-summary
  • weekly-leaderboard con metricas kills, deaths, support y matches_over_100_kills
  • monthly-leaderboard con las mismas metricas semanticas
  • monthly-mvp
  • recent-matches

Por defecto se escriben bajo:

backend/data/snapshots/<server_key>/

En Docker, estos snapshots deben persistirse bajo:

/app/data/snapshots/<server_key>/

Ejemplos:

  • backend/data/snapshots/comunidad-hispana-01/server-summary.json
  • backend/data/snapshots/comunidad-hispana-01/weekly-kills.json
  • backend/data/snapshots/comunidad-hispana-02/recent-matches.json
  • backend/data/snapshots/all-servers/weekly-support.json
  • backend/data/snapshots/all-servers/monthly-mvp.json

Cada archivo conserva metadatos operativos minimos:

  • server_key
  • snapshot_type
  • metric
  • window
  • payload
  • generated_at
  • source_range_start
  • source_range_end
  • is_stale

La persistencia usa una identidad de archivo estable por combinacion de servidor, tipo y metrica para que cada refresh reemplace el artefacto anterior sin mezclarlo con el historico bruto.

Resumen de persistencia recomendada para contenedor:

  • montar /app/data
  • conservar el SQLite historico en /app/data/hll_vietnam_dev.sqlite3
  • conservar los snapshots JSON en /app/data/snapshots/

Con docker compose, esa persistencia ya queda montada desde:

  • ./backend/data -> /app/data

Bootstrap del colector

El backend incluye un bootstrap minimo para el futuro flujo de snapshots:

  • fetch_controlled_server_source() obtiene datos controlados de desarrollo
  • query_server_info() permite consultar metadata basica real por A2S_INFO
  • fetch_a2s_probe() adapta una consulta A2S real al modelo interno del colector
  • fetch_configured_a2s_probes() consulta la lista configurada de targets A2S
  • normalize_server_record() reduce los registros a una forma comun
  • normalize_a2s_server_info() reduce una respuesta A2S al mismo contrato interno
  • build_server_snapshot() y build_snapshot_batch() generan snapshots con captured_at
  • collect_server_snapshots() orquesta captura, normalizacion, ensamblado y persistencia opcional
  • persist_snapshot_batch() escribe el lote en SQLite y mantiene identidad de servidor separada del historico

Ejecucion manual desde backend/:

python -m app.collector --source auto

Ese comando intenta consultar primero los targets A2S configurados. Si ninguno responde y no se ha desactivado el fallback, usa la fuente controlada de desarrollo para no romper el flujo local. El resultado imprime el modo usado, los errores de consulta y el lote de snapshots persistido en SQLite.

Si se quiere forzar solo A2S real:

python -m app.collector --source a2s --no-fallback

Ese flujo es la validacion local minima extremo a extremo para los targets reales configurados de Comunidad Hispana. El timeout por defecto del cliente A2S es 6.0s para tolerar mejor latencia puntual entre multiples consultas reales consecutivas. Cuando responden ambos targets por defecto, el comando debe devolver:

  • collection_mode: "a2s"
  • target_count: 2
  • success_count: 2
  • un snapshot con external_server_id: "comunidad-hispana-01"
  • un snapshot con external_server_id: "comunidad-hispana-02"
  • source_name: "community-hispana-a2s"
  • snapshot_origin: "real-a2s" en ambos
  • source_ref: "a2s://152.114.195.174:7778"
  • source_ref: "a2s://152.114.195.150:7878"
  • persistencia en backend/data/hll_vietnam_dev.sqlite3

Si la consulta se ejecuta desde un entorno con red restringida, sin salida UDP o con latencia puntual alta, el cliente puede devolver timeout aunque el target este sano. En ese caso el resultado conserva errores controlados por target y puede acabar con success_count parcial o 0 segun cuantas consultas fallen.

Los snapshots persistidos y los endpoints historicos exponen ademas:

  • snapshot_origin para distinguir real-a2s frente a controlled-fallback
  • source_ref para conservar una referencia de procedencia util en historico

Si se quiere seguir usando solo datos controlados:

python -m app.collector --source controlled

Refresco local periodico de snapshots

Para evitar lanzar el colector manualmente en cada captura, el backend incluye un bucle local de refresco periodico pensado solo para desarrollo:

python -m app.scheduler

Ese comando ejecuta capturas persistidas de forma repetida usando el mismo flujo del colector y la base SQLite local. Por defecto:

  • usa --source auto
  • espera 120 segundos entre ejecuciones
  • permite fallback controlado si A2S no responde
  • sigue en ejecucion hasta que se detiene manualmente

Se puede detener de forma segura con Ctrl+C.

Variables y flags utiles:

  • HLL_BACKEND_REFRESH_INTERVAL_SECONDS para cambiar el intervalo por defecto
  • --interval 120 para fijar el intervalo en segundos en una ejecucion concreta
  • --source a2s --no-fallback para forzar solo capturas reales
  • --max-runs 3 para limitar el numero de ciclos y evitar un bucle indefinido

Ejemplos:

python -m app.scheduler --interval 120
python -m app.scheduler --source a2s --no-fallback --max-runs 2

Flujo local recomendado para ver datos vivos en la landing:

  1. Desde backend/, arrancar la API:

    python -m app.main

  2. En otra terminal, dejar el scheduler corriendo:

    python -m app.scheduler

  3. Servir frontend/ con un servidor local sencillo y abrir la landing. El frontend volvera a pedir /api/servers cada 120 segundos, por lo que los cambios de mapa o poblacion apareceran sin recarga manual cuando existan snapshots nuevos.

Este mecanismo deja el refresco desacoplado del servidor HTTP y es facil de reemplazar mas adelante por un scheduler mas serio sin rehacer el colector.

Prueba manual minima de A2S desde backend/:

python -m app.a2s_client 203.0.113.10 27015

Ese comando lanza una consulta A2S_INFO por UDP y devuelve JSON con nombre de servidor, mapa, jugadores y capacidad maxima cuando el query port responde. Tambien puede reutilizarse desde Python con query_server_info() o fetch_a2s_probe(). Si el servidor no responde o el puerto es incorrecto, el cliente eleva errores controlados de timeout o protocolo para que la siguiente task pueda integrarlo en el pipeline de snapshots sin romper el backend.

Registro local de targets A2S

La lista de targets A2S vive en app/server_targets.py. Por defecto el backend registra solo el primer target real verificado del proyecto:

  • Comunidad Hispana #01
  • host/IP: 152.114.195.174
  • query_port: 7778
  • game_port: 7777
  • source_name: community-hispana-a2s
  • external_server_id: comunidad-hispana-01

query_port es el puerto usado para A2S_INFO; game_port se conserva por separado para documentar el puerto de juego real sin mezclar ambos conceptos en la configuracion.

El registro por defecto incluye dos targets reales verificados:

  • Comunidad Hispana #01
    • host/IP: 152.114.195.174
    • query_port: 7778
    • game_port: 7777
    • external_server_id: comunidad-hispana-01
  • Comunidad Hispana #02
    • host/IP: 152.114.195.150
    • query_port: 7878
    • game_port: 7877
    • external_server_id: comunidad-hispana-02

Si se quiere cambiar la lista sin editar codigo, puede definirse HLL_BACKEND_A2S_TARGETS como un array JSON:

$env:HLL_BACKEND_A2S_TARGETS='[
  {
    "name": "Comunidad Hispana #01",
    "host": "152.114.195.174",
    "query_port": 7778,
    "game_port": 7777,
    "source_name": "community-hispana-a2s",
    "external_server_id": "comunidad-hispana-01",
    "region": "ES"
  },
  {
    "name": "Comunidad Hispana #02",
    "host": "152.114.195.150",
    "query_port": 7878,
    "game_port": 7877,
    "source_name": "community-hispana-a2s",
    "external_server_id": "comunidad-hispana-02",
    "region": "ES"
  }
]'

Cada target soporta:

  • name
  • host
  • query_port
  • game_port opcional
  • source_name
  • external_server_id opcional
  • region opcional

El colector puede resolver esos targets con load_a2s_targets() o fetch_configured_a2s_probes() sin depender de constantes dispersas.

Consulta historica minima

Una vez existen snapshots persistidos, el backend expone una primera capa de consulta historica:

  • /api/servers/latest devuelve el ultimo snapshot conocido por servidor
  • /api/servers/history devuelve snapshots recientes agregados
  • /api/servers/{id}/history devuelve el historial reciente de un servidor

{id} acepta el server_id numerico interno o el external_server_id persistido por el colector. El parametro opcional limit acepta valores entre 1 y 100.

La capa historica propia expone:

  • /api/historical/weekly-top-kills
  • /api/historical/weekly-leaderboard
  • /api/historical/leaderboard
  • /api/historical/recent-matches
  • /api/historical/server-summary
  • /api/historical/snapshots/server-summary
  • /api/historical/snapshots/weekly-leaderboard
  • /api/historical/snapshots/leaderboard
  • /api/historical/snapshots/recent-matches
  • /api/historical/player-profile

Parametros opcionales:

  • limit entre 1 y 100
  • server con slug historico como comunidad-hispana-01
  • player en /api/historical/player-profile aceptando stable_player_key, steam_id o source_player_id

Ademas de los slugs fisicos de cada scoreboard, la capa historica acepta la clave logica all-servers para devolver agregados globales sobre los tres servidores de Comunidad Hispana sin tratarla como un origen CRCON real aparte.

La ventana temporal usa semana calendario UTC y solo considera partidas cerradas con ended_at para no mezclar partidas aun en curso ni filas historicas transitorias. El payload devuelve servidor, rango temporal, jugador, kills semanales, posicion y numero de partidas consideradas.

weekly-leaderboard generaliza ese bloque para varias metricas semanales por servidor usando el mismo filtro de partidas cerradas. Si la semana actual cae entre lunes y miercoles UTC y todavia no acumula al menos 3 partidas cerradas, el backend activa un fallback temporal a la semana cerrada anterior. Metricas soportadas:

  • kills
  • deaths
  • support
  • matches_over_100_kills

El endpoint legacy /api/historical/weekly-top-kills se conserva como alias compatible para la metrica kills.

/api/historical/leaderboard y /api/historical/snapshots/leaderboard generalizan ese mismo contrato con timeframe=weekly|monthly. Para monthly, la politica temporal usa el mes natural UTC en curso y hace fallback al mes cerrado anterior solo cuando el mes actual todavia no tiene ningun cierre. Ambas variantes exponen el rango real usado mediante window_start, window_end, window_kind, window_label y selection_reason.

recent-matches devuelve cierres recientes por servidor con marcador, mapa y conteo de jugadores. server-summary agrega volumen historico, jugadores unicos, kills, mapas dominantes y rango temporal cubierto. player-profile deja lista la base de consulta agregada por jugador para futuras vistas.

La familia /api/historical/snapshots/* lee directamente los archivos JSON precalculados bajo backend/data/snapshots/ y evita recalcular agregados pesados en cada request. Estos endpoints devuelven payloads ligeros listos para frontend con:

  • snapshot_status
  • missing_reason
  • request_path_policy
  • generation_policy
  • generated_at
  • source_range_start
  • source_range_end
  • is_stale
  • freshness
  • found
  • window_start
  • window_end
  • window_kind
  • window_label
  • uses_fallback
  • selection_reason
  • current_week_closed_matches
  • previous_week_closed_matches
  • sufficient_sample

Si un snapshot todavia no existe en backend/data/snapshots/, la API responde rapido con found: false, snapshot_status: "missing" y missing_reason: "snapshot-not-generated". La generacion y refresco de esos artefactos debe ocurrir fuera del request path mediante historical_ingestion o historical_runner; la lectura HTTP se mantiene como fast path de solo lectura.

/api/historical/snapshots/server-summary devuelve item con el resumen del servidor. /api/historical/snapshots/weekly-leaderboard devuelve items ya precalculados para una metrica semanal y acepta limit para recortar el payload ya persistido sin recalcularlo. /api/historical/snapshots/recent-matches devuelve items de cierres recientes ya preparados y tambien acepta limit para servir solo una parte del snapshot persistido.

La misma capa de snapshots guarda tambien monthly-leaderboard por servidor y por agregado all-servers, con archivos como monthly-kills.json y monthly-support.json.

Tambien persiste monthly-mvp.json por servidor y para all-servers, listo para lectura rapida desde /api/historical/monthly-mvp y /api/historical/snapshots/monthly-mvp sin recalculo pesado en request.

La misma operativa persiste tambien snapshots V2 de eventos de jugador para el ultimo mes con datos disponible por servidor y para all-servers, listos para lectura rapida sin consultas pesadas on-demand:

  • player-events-most-killed.json
  • player-events-death-by.json
  • player-events-duels.json
  • player-events-weapon-kills.json
  • player-events-teamkills.json

Los endpoints /api/historical/player-events y /api/historical/snapshots/player-events aceptan:

  • view=most-killed
  • view=death-by
  • view=duels
  • view=weapon-kills
  • view=teamkills

La respuesta expone metadata operativa alineada con el resto de snapshots:

  • generated_at
  • month_key
  • source_range_start
  • source_range_end
  • found
  • is_stale

El backend incluye ademas el calculo interno de monthly MVP V1 en app/monthly_mvp.py, separado de los leaderboards mensuales simples por metrica. Ese calculo:

  • usa solo kills, support, time_seconds, deaths y teamkills persistidos
  • recompone KPM y KDA desde totales mensuales
  • aplica elegibilidad minima de 6 partidas cerradas y 6 horas
  • soporta servidor individual y el agregado logico all-servers

En esta fase el ranking MVP queda listo para serializar en snapshots o payloads sin reemplazar los leaderboards mensuales ya existentes por kills, deaths, support y matches_over_100_kills.

La repo incluye tambien un calculo backend separado de monthly MVP V2 en app/monthly_mvp_v2.py, expuesto de momento por /api/historical/monthly-mvp-v2.

Esta V2:

  • convive sin reemplazar monthly MVP V1
  • reusa la misma ventana mensual y la misma elegibilidad base
  • anade rivalry_edge y duel_control derivados del ledger V2 de eventos
  • aplica una penalizacion de teamkills mas estricta
  • mantiene fuera del score el peso por arma o tipo de kill hasta validar mejor esas senales

Esa capacidad V2 se persiste tambien en snapshots dedicados monthly-mvp-v2.json por servidor y para all-servers, leidos por:

  • /api/historical/monthly-mvp-v2
  • /api/historical/snapshots/monthly-mvp-v2

La lectura HTTP de V2 sigue asi la misma politica de fast path de solo lectura que el resto de snapshots historicos, con metadata util como:

  • generated_at
  • month_key
  • found
  • source_range_start
  • source_range_end
  • event_coverage

Ingesta historica CRCON

La ingesta historica no usa A2S ni scraping del HTML de /games. Consume la capa JSON publica detectada en los scoreboards CRCON de Comunidad Hispana y persiste el resultado en las tablas historical_*.

Fuentes configuradas:

  • https://scoreboard.comunidadhll.es
  • https://scoreboard.comunidadhll.es:5443
  • https://scoreboard.comunidadhll.es:3443

Comandos manuales desde backend/:

python -m app.historical_ingestion bootstrap
python -m app.historical_ingestion refresh
python -m app.historical_runner --interval 1800

Los mismos flujos desde Docker Compose:

docker compose exec backend python -m app.historical_ingestion bootstrap
docker compose exec backend python -m app.historical_ingestion refresh
docker compose exec backend python -m app.historical_runner --interval 1800

Flags utiles:

  • --server comunidad-hispana-01 para limitar a un servidor
  • --server comunidad-hispana-02 para validar solo el segundo servidor activo
  • --overlap-hours 48 para releer una ventana reciente mayor sin relanzar bootstrap
  • --max-pages 2 para validacion local acotada
  • --page-size 25 para ajustar paginacion
  • --start-page 4 para forzar una pagina concreta en bootstraps largos
  • --detail-workers 16 para paralelizar el detalle por partida

La ejecucion bootstrap recorre paginas historicas hasta agotar resultados. La ejecucion refresh usa una ventana de solape sobre la ultima partida persistida por servidor para releer solo paginas recientes y absorber updates tardios sin reimportar todo el historico. Cuando una ejecucion termina correctamente, tambien recompone los snapshots historicos precalculados para el servidor afectado o para todos los servidores si la ingesta fue global. Si la recomposicion se lanza para un servidor fisico concreto, el backend rehace tambien el agregado logico all-servers para mantener Todos alineado con #01 y #02 aunque #03 siga sin bootstrap.

En esta fase, el comando muestra progreso operativo util sin saturar stdout:

  • intento primario RCON
  • fuente finalmente seleccionada
  • servidor actual
  • pagina actual
  • match_ids_to_detail de cada pagina

Si RCON no puede cubrir la operacion competitiva real, el fallback a public-scoreboard queda visible tanto durante la ejecucion como en el JSON final mediante:

  • primary_source
  • selected_source
  • fallback_used
  • fallback_reason
  • source_attempts
  • primary_writer_result

El comando devuelve ademas un resumen de cobertura persistida por servidor. Esto ayuda a validar rapidamente cuantos matches reales quedaron importados, el rango temporal cubierto y si la carga ya supera la ultima semana movil que usa la UI. Ese resumen incluye tambien checkpoint y estado operativo de backfill por servidor:

  • next_page
  • last_completed_page
  • discovered_total_matches
  • discovered_total_pages
  • archive_exhausted
  • last_run

Como la fuente CRCON publica expone un archivo muy profundo y puede devolver errores 502 intermitentes bajo carga sostenida, el bootstrap completo debe tratarse como una operacion reanudable. Flujo recomendado:

python -m app.historical_ingestion bootstrap --detail-workers 16
python -m app.historical_ingestion bootstrap --detail-workers 16

La segunda invocacion reutiliza automaticamente el checkpoint persistido en historical_backfill_progress y continua desde la siguiente pagina pendiente si la sesion anterior se corta por tiempo disponible o por inestabilidad puntual del origen. --start-page queda como override manual cuando se quiera reprocesar o inspeccionar un tramo concreto.

Runbook operativo para overlap manual:

python -m app.historical_ingestion refresh --overlap-hours 48
python -m app.historical_ingestion refresh --server comunidad-hispana-01 --overlap-hours 48 --max-pages 2
python -m app.historical_runner --max-runs 1

La primera pasada relee 48 horas sobre los tres servidores historicos ya registrados. La segunda sirve para validar un solo servidor con alcance acotado. La tercera recompone snapshots despues de una pasada manual cuando se quiere confirmar que la capa precalculada vuelve a quedar alineada.

Interpretacion operativa recomendada:

  • si aparece historical-ingestion-rcon-primary-succeeded, RCON se intento de verdad primero y la captura prospectiva quedo registrada
  • si despues selected_source termina en public-scoreboard, eso significa que la reconstruccion del archivo competitivo historical_* siguio necesitando fallback clasico
  • si RCON falla por red, auth o timeout, el motivo queda visible en fallback_reason y en source_attempts

Los reintentos de cada request JSON pueden ajustarse sin tocar codigo con:

  • HLL_HISTORICAL_CRCON_REQUEST_RETRIES
  • HLL_HISTORICAL_CRCON_RETRY_DELAY_SECONDS

El runner python -m app.historical_runner deja ahora una orquestacion RCON-first lista para ejecucion local repetida sin depender de infraestructura externa y mantiene calientes los snapshots historicos mas visibles cuando el fallback clasico entra de forma controlada. Por defecto:

  • intenta primero una captura prospectiva RCON en cada ciclo
  • solo lanza el refresh historico clasico cuando RCON falla, cuando se pide un scope manual que sigue requiriendo cobertura competitiva, o en la cadencia periodica de fallback para mantener rankings y snapshots clasicos
  • refresca cada 900 segundos
  • prewarmea en cada ciclo:
    • server-summary para comunidad-hispana-01, comunidad-hispana-02 y all-servers
    • weekly-leaderboard de la metrica por defecto kills para esos mismos alcances
    • monthly-leaderboard de la metrica por defecto kills para esos mismos alcances
    • recent-matches para esos mismos alcances
  • recompone la matriz completa de snapshots cada 4 ciclos para mantener el resto de metricas al dia sin penalizar todos los refresh
  • reintenta hasta 2 veces tras un fallo
  • espera 30 segundos entre reintentos
  • reutiliza el registro de historical_ingestion_runs para dejar trazabilidad de ultimo refresh, resultado y errores basicos
  • persiste por servidor:
    • server-summary
    • weekly-leaderboard para kills, deaths, support y matches_over_100_kills
    • monthly-leaderboard para kills, deaths, support y matches_over_100_kills
    • recent-matches

Flags utiles del runner:

  • --server comunidad-hispana-01 para limitar a un servidor
  • --interval 900 para fijar la frecuencia recomendada de snapshots
  • --hourly para fijar directamente un ciclo horario de 3600 segundos
  • --retries 1 para reducir reintentos
  • --retry-delay 10 para bajar la espera entre fallos
  • --max-runs 1 para una validacion puntual sin bucle indefinido

Para dejar automatizado el refresh historico horario en local, el comando avanzado sigue disponible:

python -m app.historical_runner --hourly

Sin --server, ese runner refresca:

  • comunidad-hispana-01
  • comunidad-hispana-02

Despues de cada fallback clasico correcto, recompone snapshots para los servidores afectados y vuelve a alinear el agregado all-servers. Si el ciclo RCON primario fue suficiente y no hizo falta el fallback clasico, el runner deja constancia explicita de ese motivo en su salida JSON.

Para regenerar snapshots de forma puntual dentro del contenedor sin dejar un bucle permanente, la validacion operativa minima es:

docker compose exec backend python -m app.historical_runner --max-runs 1

Operativa local minima:

  1. Desde backend/, arrancar la API con python -m app.main.
  2. En otra terminal, dejar corriendo python -m app.historical_runner --hourly.
  3. Verificar el proceso revisando la salida del runner: al arrancar imprime un bloque JSON con event: "historical-refresh-loop-started", server_scope y snapshot_scope.
  4. Confirmar que los snapshots siguen actualizandose revisando generated_at en archivos bajo backend/data/snapshots/, por ejemplo:
    • backend/data/snapshots/comunidad-hispana-01/server-summary.json
    • backend/data/snapshots/comunidad-hispana-02/recent-matches.json
    • backend/data/snapshots/comunidad-hispana-02/weekly-kills.json
    • backend/data/snapshots/all-servers/monthly-kills.json

Operativa avanzada con Docker Compose:

docker compose --profile advanced up -d backend historical-runner frontend

El servicio historical-runner usa el mismo volumen persistente ./backend/data y ejecuta python -m app.historical_runner --hourly como bucle operativo dedicado, sin mezclar el scheduler con el proceso HTTP principal. No forma parte del despliegue normal, que queda limitado a backend + frontend.

En frontend, la landing ya no arranca con cards fake estaticas para servidores:

  • el contenedor queda en estado de loading
  • solo se renderizan cards con datos reales al hidratar
  • si la API falla, se muestra una degradacion limpia en lugar de datos falsos

Coordinacion single-writer para automatizaciones y CLI

Todos los procesos writer-oriented que comparten el mismo SQLite usan ahora un lock comun derivado de HLL_BACKEND_STORAGE_PATH y persistido junto al volumen de datos compartido. Ese lock coordina:

  • app.historical_ingestion
  • app.historical_runner
  • app.player_event_worker
  • app.rcon_historical_worker

Rutas HTTP read-only como /api/historical/snapshots/*, /api/servers en modo cache local y el read model minimo RCON no adquieren este lock.

Variables operativas:

  • HLL_BACKEND_WRITER_LOCK_TIMEOUT_SECONDS
  • HLL_BACKEND_WRITER_LOCK_POLL_INTERVAL_SECONDS

Comportamiento:

  • si un writer ya esta ejecutandose, el siguiente espera de forma controlada hasta agotar el timeout configurado
  • si no puede adquirir el lock, falla con un error claro indicando:
    • lock path
    • holder
    • started_at
    • host
    • pid
  • si el lock parece venir de un contenedor Docker ya parado, el backend puede recuperarlo automaticamente cuando:
    • el holder venia de un cwd tipo /app
    • el lock ya supero una gracia minima de seguridad
  • la coordinacion principal es este single-writer lock; WAL y busy_timeout quedan como endurecimiento complementario, no como solucion unica

Runbook minimo:

  • pasada manual del historico base mientras el runner automatico existe:

    docker compose exec backend python -m app.historical_ingestion refresh --overlap-hours 48

    Si el lock esta ocupado, el comando esperara hasta el timeout configurado y, si no se libera, terminara con un mensaje claro de lock ocupado.

  • pasada manual de player-events:

    docker compose exec backend python -m app.player_event_worker refresh --overlap-hours 48

  • pasada manual de captura prospectiva RCON:

    docker compose exec backend python -m app.rcon_historical_worker capture

  • convivencia recomendada con automatizaciones:

    • no hace falta parar contenedores por defecto
    • dejar que el lock coordine la exclusión mutua
    • usar --max-runs 1 o comandos manuales puntuales cuando se quiera una pasada controlada

Comprobaciones utiles con Compose:

  • docker compose ps historical-runner
  • docker compose logs -f historical-runner
  • docker compose exec backend python -m app.historical_runner --max-runs 1

Compose para captura prospectiva RCON:

docker compose --profile advanced up -d rcon-historical-worker
docker compose logs -f rcon-historical-worker
docker compose exec backend python -m app.rcon_historical_worker capture

Variables utiles del runner:

  • HLL_HISTORICAL_SNAPSHOT_REFRESH_INTERVAL_SECONDS
  • HLL_HISTORICAL_FULL_SNAPSHOT_EVERY_RUNS
  • HLL_HISTORICAL_REFRESH_MAX_RETRIES
  • HLL_HISTORICAL_REFRESH_RETRY_DELAY_SECONDS
  • HLL_HISTORICAL_WEEKLY_FALLBACK_MIN_MATCHES
  • HLL_HISTORICAL_WEEKLY_FALLBACK_MAX_WEEKDAY

Al inicializar la persistencia local, el backend normaliza tambien la identidad historica ya guardada:

  • prioriza steaminfo.profile.steamid cuando existe
  • si player_id ya parece un SteamID real, lo promueve igualmente a steam:*
  • si no hay SteamID, usa player_id como clave crcon-player:*
  • deja steaminfo.id como ultimo fallback cuando faltan las claves anteriores

La misma inicializacion fusiona filas duplicadas si una partida abierta quedo guardada con un id sintetico y mas tarde CRCON la expone con un id numerico definitivo. Esto evita que el ranking semanal cuente dos veces la misma sesion.

CORS local minimo

El backend responde con Access-Control-Allow-Origin solo si la peticion llega desde uno de los origenes permitidos en desarrollo local. No se habilita un comodin global ni configuracion de produccion en esta fase.

La allowlist por defecto cubre file:// mediante el origen null y los flujos locales mas comunes del proyecto:

  • http://127.0.0.1:5500
  • http://localhost:5500
  • http://127.0.0.1
  • http://127.0.0.1:8080
  • http://localhost
  • http://localhost:8080

Las respuestas GET y OPTIONS incluyen Access-Control-Allow-Origin cuando el origen esta permitido, suficiente para probar la landing contra la API local sin tocar endpoints ni payloads.

Esta separacion mantiene el backend simple y deja una base clara para futuras tasks sin introducir integraciones reales todavia.

Fuente y ledger de eventos de jugador V2

La repo incluye ahora una primera base V2 separada del historico historical_* para preparar metricas avanzadas de duelos, armas y teamkills sin tocar todavia la UI ni el scoring final.

Fuente minima elegida en esta fase:

  • detalle de partida GET /api/get_map_scoreboard?map_id={id} del scoreboard CRCON

Importante:

  • esta fuente no es un feed raw por kill
  • el adaptador actual normaliza solo senales parciales ya visibles en el resumen de partida:
    • most_killed
    • death_by
    • weapons
    • death_by_weapons
    • teamkills
  • occurred_at usa el timestamp de cierre o inicio de la partida, no el instante exacto del kill
  • el ledger raw es append-only y deduplica por event_id
  • la persistencia queda separada de historical_matches y historical_player_match_stats aunque comparte el mismo SQLite de desarrollo

Contrato minimo normalizado por evento:

  • event_id
  • event_type
  • occurred_at
  • server_slug
  • external_match_id
  • source_kind
  • source_ref
  • killer_player_key
  • victim_player_key
  • weapon_name
  • kill_category
  • is_teamkill
  • event_value

Tablas nuevas:

  • player_event_raw_ledger
  • player_event_ingestion_runs
  • player_event_backfill_progress

Comandos manuales desde backend/:

python -m app.player_event_worker refresh
python -m app.player_event_worker refresh --server comunidad-hispana-01 --max-pages 1
python -m app.player_event_worker loop --interval 1800

Variables opcionales del worker:

  • HLL_PLAYER_EVENT_REFRESH_INTERVAL_SECONDS
  • HLL_PLAYER_EVENT_REFRESH_OVERLAP_HOURS
  • HLL_PLAYER_EVENT_REFRESH_MAX_RETRIES
  • HLL_PLAYER_EVENT_REFRESH_RETRY_DELAY_SECONDS

Flags utiles del worker:

  • --server comunidad-hispana-01 para validar un solo servidor
  • --overlap-hours 48 para releer una ventana reciente mayor
  • --max-pages 1 para una comprobacion acotada

Ejemplos operativos:

python -m app.player_event_worker refresh --overlap-hours 48
python -m app.player_event_worker refresh --server comunidad-hispana-01 --overlap-hours 48 --max-pages 1

Politica operativa minima:

  • el worker corre fuera del request path HTTP
  • reusa la capa historica public-scoreboard solo como fuente de detalle
  • persiste checkpoints por servidor y pagina
  • la reejecucion es segura porque el ledger usa insercion idempotente por event_id

Agregados V2 ya disponibles desde codigo:

  • list_most_killed()
  • list_death_by()
  • list_net_duel_summaries()
  • list_weapon_kills()
  • list_teamkill_summaries()

Limitaciones actuales de esta fase:

  • no existe todavia un ledger raw por kill individual
  • los agregados de duelos y armas son parciales, porque dependen del mejor resumen disponible por jugador en CRCON y no de todos los encounters del match
  • la V2 no expone aun endpoints HTTP ni snapshots propios

Historical Runtime Policy

El backend queda orientado a RCON-first tambien para historico:

  • live:
    • rcon primero
    • a2s solo como fallback
  • historico:
    • rcon primero tanto para lectura minima como para el writer path primario de historical_ingestion
    • public-scoreboard solo como fallback cuando RCON no cubre una operacion competitiva concreta, no tiene cobertura suficiente o falla la captura primaria

Metadata observable en payloads historicos:

  • primary_source
  • selected_source
  • fallback_used
  • fallback_reason
  • source_attempts

Estado real a fecha de esta fase:

  • el read model historico RCON soporta ya una capa competitiva primaria basada en ventanas derivadas desde persistencia rcon_historical_*
  • server-summary y recent-matches pasan a usar esa capa RCON-backed como camino principal real
  • en runtime, esas dos rutas solo se sirven como rcon cuando la capability sigue soportada y existe cobertura RCON util para el scope pedido
  • cobertura util en esta frontera significa:
    • server-summary: al menos una fila con coverage.status != "empty" y window_count o sample_count mayor que cero
    • recent-matches: al menos una ventana con match_id, closed_at y sample_count > 0
  • si el target persistido quedo con clave legacy rcon:<host>:<port> pero el runtime actual ya conoce su external_server_id, la capa read model intenta resolver ambos aliases antes de caer a fallback
  • si no hay coverage suficiente o la lectura RCON falla, el backend mantiene fallback explicito a public-scoreboard con fallback_used = true y fallback_reason visible
  • historical_ingestion intenta primero una captura writer-oriented por RCON y deja esa tentativa visible en su salida
  • leaderboards semanales/mensuales, MVP V1/V2 y player-events siguen teniendo fallback a public-scoreboard mientras RCON no disponga de señal competitiva por jugador con paridad suficiente
  • Elo/MMR permanece pausado y desacoplado del arranque del backend; cuando se reactive mediante una task explicita, debera respetar el contexto RCON-backed primario y usar public-scoreboard solo como suplemento/fallback para estadisticas por jugador sin paridad RCON

PostgreSQL Phase 2 Displayed Data Migration

Cuando HLL_BACKEND_DATABASE_URL esta configurado, los endpoints visibles de historico y el cache mostrado por /api/servers leen PostgreSQL. SQLite y los JSON legacy quedan como fuente de migracion o fixture explicito con db_path.

Migracion idempotente:

cd backend
python -m app.sqlite_to_postgres_migration
python -m app.storage_diagnostics

La salida JSON de sqlite_to_postgres_migration lista rutas fuente, dominios y tablas migradas, filas leidas, insertadas, actualizadas, omitidas y errores. La migracion conserva external_match_id, IDs legacy y match_key RCON para que URLs de detalle existentes sigan resolviendo. Tambien copia candidatos y URLs seguras de scoreboard; no vuelve a activar filas visibles de comunidad-hispana-03.

Paridad minima a revisar en storage_diagnostics:

  • admin_log_events, materialized_matches, player_stats
  • public_scoreboard_historical_matches
  • fuentes de rankings semanales y mensuales
  • server_summary_cache, server_snapshots, player_event_ledger
  • scoreboard_candidates
  • ultimas partidas materializadas y ultimos eventos AdminLog match_end

Fuera de phase 2 quedan checkpoints/runs de ingesta publica que no se muestran en frontend y Elo/MMR pausado. Si un endpoint de mantenimiento recibe un db_path explicito, sigue trabajando contra SQLite para migracion, tests o compatibilidad operativa controlada.

Elo/MMR Monthly Ranking

Se añade una primera base operativa inspirada en el documento sistema_elo_mensual_hll.pdf, pero adaptada a la telemetria real disponible.

Superficies nuevas:

  • python -m app.elo_mmr_engine rebuild
  • python -m app.elo_mmr_engine leaderboard --server all-servers --limit 10
  • python -m app.elo_mmr_engine player --server all-servers --player <stable_player_key>
  • /api/historical/elo-mmr/leaderboard
  • /api/historical/elo-mmr/player

Persistencia nueva en SQLite:

  • elo_mmr_player_ratings
  • elo_mmr_match_results
  • elo_mmr_monthly_rankings
  • elo_mmr_monthly_checkpoints

Politica de exactitud:

  • exact: outcome, combat, utility, disciplina por teamkills, MMR persistente
  • approximate: role bucket, objective index, strength of schedule
  • not_available: leadership y tacticas finas no persistidas

Cuando historical_data_source=rcon, el motor Elo/MMR deja visible una frontera hibrida y honesta:

  • primary_source = rcon
  • selected_source = hybrid-rcon-competitive-plus-public-scoreboard
  • fallback_used = true

Eso significa que la capa RCON-backed ya aporta el contexto competitivo de cobertura y calidad de match, pero las estadisticas competitivas por jugador siguen necesitando el suplemento clasico hasta que RCON tenga esa granularidad.

La especificacion detallada y el mapa de capabilities quedan en:

  • docs/elo-mmr-monthly-ranking-design.md

Alcance

Esta fase no implementa:

  • logica real de Discord
  • integraciones con servidores de juego
  • base de datos
  • autenticacion
  • dependencias nuevas

La idea es dejar un esqueleto funcional, pequeno y coherente con docs/frontend-backend-contract.md.

Reference in New Issue View Git Blame Copy Permalink