1539 lines
52 KiB
Python
1539 lines
52 KiB
Python
"""Leaderboard read model over materialized RCON/AdminLog match stats."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import json
|
|
import os
|
|
import sqlite3
|
|
from contextlib import closing
|
|
from contextlib import contextmanager
|
|
from datetime import date, datetime, timedelta, timezone
|
|
from pathlib import Path
|
|
from typing import Literal
|
|
|
|
from .config import (
|
|
get_historical_weekly_fallback_min_matches,
|
|
get_storage_path,
|
|
use_postgres_rcon_storage,
|
|
)
|
|
from .historical_storage import ALL_SERVERS_SLUG
|
|
from .rcon_admin_log_materialization import (
|
|
MATCH_RESULT_SOURCE,
|
|
initialize_rcon_materialized_storage,
|
|
)
|
|
from .sqlite_utils import connect_sqlite_readonly, connect_sqlite_writer
|
|
|
|
LeaderboardTimeframe = Literal["weekly", "monthly"]
|
|
LeaderboardMetric = Literal[
|
|
"kills",
|
|
"deaths",
|
|
"teamkills",
|
|
"matches_considered",
|
|
"kd_ratio",
|
|
"kills_per_match",
|
|
"matches_over_100_kills",
|
|
"support",
|
|
]
|
|
|
|
SNAPSHOT_GENERATOR_TIMEFRAMES = ("weekly", "monthly")
|
|
SNAPSHOT_GENERATOR_SERVER_KEYS = (
|
|
ALL_SERVERS_SLUG,
|
|
"comunidad-hispana-01",
|
|
"comunidad-hispana-02",
|
|
)
|
|
SNAPSHOT_GENERATOR_METRICS = (
|
|
"kills",
|
|
"deaths",
|
|
"teamkills",
|
|
"matches_considered",
|
|
"kd_ratio",
|
|
"kills_per_match",
|
|
)
|
|
DEFAULT_RANKING_SNAPSHOT_REFRESH_LIMIT = 30
|
|
|
|
RANKING_SNAPSHOT_SQLITE_SCHEMA_SQL = """
|
|
CREATE TABLE IF NOT EXISTS ranking_snapshots (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
timeframe TEXT NOT NULL,
|
|
server_id TEXT NOT NULL,
|
|
metric TEXT NOT NULL,
|
|
window_start TEXT NOT NULL,
|
|
window_end TEXT NOT NULL,
|
|
generated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
|
source TEXT NOT NULL DEFAULT 'rcon-materialized-admin-log',
|
|
snapshot_status TEXT NOT NULL DEFAULT 'ready',
|
|
item_count INTEGER NOT NULL DEFAULT 0,
|
|
limit_size INTEGER NOT NULL DEFAULT 20,
|
|
source_matches_count INTEGER NOT NULL DEFAULT 0,
|
|
freshness TEXT NOT NULL DEFAULT 'fresh',
|
|
window_kind TEXT,
|
|
window_label TEXT,
|
|
error_message TEXT,
|
|
UNIQUE(timeframe, server_id, metric, window_start, window_end)
|
|
);
|
|
|
|
CREATE INDEX IF NOT EXISTS idx_ranking_snapshots_lookup
|
|
ON ranking_snapshots(timeframe, server_id, metric, snapshot_status, window_end DESC, generated_at DESC);
|
|
|
|
CREATE TABLE IF NOT EXISTS ranking_snapshot_items (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
snapshot_id INTEGER NOT NULL REFERENCES ranking_snapshots(id) ON DELETE CASCADE,
|
|
ranking_position INTEGER NOT NULL,
|
|
player_id TEXT NOT NULL,
|
|
player_name TEXT NOT NULL,
|
|
metric_value REAL NOT NULL DEFAULT 0,
|
|
matches_considered INTEGER NOT NULL DEFAULT 0,
|
|
kills INTEGER NOT NULL DEFAULT 0,
|
|
deaths INTEGER NOT NULL DEFAULT 0,
|
|
teamkills INTEGER NOT NULL DEFAULT 0,
|
|
kd_ratio REAL NOT NULL DEFAULT 0.0,
|
|
kills_per_match REAL NOT NULL DEFAULT 0.0,
|
|
UNIQUE(snapshot_id, ranking_position),
|
|
UNIQUE(snapshot_id, player_id)
|
|
);
|
|
|
|
CREATE INDEX IF NOT EXISTS idx_ranking_snapshot_items_snapshot
|
|
ON ranking_snapshot_items(snapshot_id, ranking_position);
|
|
|
|
CREATE INDEX IF NOT EXISTS idx_ranking_snapshot_items_player
|
|
ON ranking_snapshot_items(snapshot_id, player_id);
|
|
"""
|
|
|
|
|
|
def initialize_ranking_snapshot_storage(
|
|
*,
|
|
db_path: Path | None = None,
|
|
ensure_storage: bool = True,
|
|
) -> Path:
|
|
"""Create ranking snapshot tables used by weekly/monthly public ranking reads."""
|
|
resolved_path = initialize_rcon_materialized_storage(
|
|
db_path=db_path,
|
|
ensure_storage=ensure_storage,
|
|
)
|
|
if use_postgres_rcon_storage(explicit_sqlite_path=db_path):
|
|
if ensure_storage:
|
|
from .postgres_rcon_storage import initialize_postgres_rcon_storage
|
|
|
|
initialize_postgres_rcon_storage()
|
|
return resolved_path
|
|
|
|
with closing(connect_sqlite_writer(resolved_path)) as connection:
|
|
with connection:
|
|
connection.executescript(RANKING_SNAPSHOT_SQLITE_SCHEMA_SQL)
|
|
return resolved_path
|
|
|
|
|
|
def is_ranking_runtime_fallback_enabled() -> bool:
|
|
"""Return whether `/api/ranking` may fall back to runtime reads in explicit internal mode."""
|
|
normalized = os.getenv(
|
|
"HLL_BACKEND_RANKING_RUNTIME_FALLBACK_ENABLED",
|
|
"false",
|
|
).strip().lower()
|
|
return normalized in {"1", "true", "yes", "on"}
|
|
|
|
|
|
def generate_ranking_snapshot(
|
|
*,
|
|
timeframe: str,
|
|
server_key: str | None,
|
|
metric: str,
|
|
limit: int,
|
|
replace_existing: bool = True,
|
|
ensure_storage: bool = True,
|
|
now: datetime | None = None,
|
|
db_path: Path | None = None,
|
|
) -> dict[str, object]:
|
|
"""Generate and persist one weekly/monthly ranking snapshot."""
|
|
normalized_timeframe = _normalize_generator_timeframe(timeframe)
|
|
normalized_server_key = _normalize_generator_server_key(server_key)
|
|
normalized_metric = _normalize_generator_metric(metric)
|
|
normalized_limit = _normalize_limit(limit)
|
|
anchor = _as_utc(now or datetime.now(timezone.utc))
|
|
|
|
resolved_path = initialize_ranking_snapshot_storage(
|
|
db_path=db_path,
|
|
ensure_storage=ensure_storage,
|
|
)
|
|
connection_scope = _connect_write_scope(
|
|
resolved_path,
|
|
db_path=db_path,
|
|
initialize=ensure_storage,
|
|
)
|
|
with connection_scope as connection:
|
|
window = select_leaderboard_window(
|
|
connection=connection,
|
|
server_key=normalized_server_key,
|
|
timeframe=normalized_timeframe,
|
|
now=anchor,
|
|
)
|
|
window_start = _to_iso(window["start"])
|
|
window_end = _to_iso(window["end"])
|
|
existing_snapshot_id = _find_existing_snapshot_for_window(
|
|
connection=connection,
|
|
timeframe=normalized_timeframe,
|
|
server_key=normalized_server_key,
|
|
metric=normalized_metric,
|
|
window_start=window_start,
|
|
window_end=window_end,
|
|
)
|
|
if existing_snapshot_id is not None and not replace_existing:
|
|
snapshot = _get_snapshot_record(connection=connection, snapshot_id=existing_snapshot_id)
|
|
items = _list_snapshot_items(connection=connection, snapshot_id=existing_snapshot_id)
|
|
return {
|
|
"status": "ok",
|
|
"snapshot": snapshot,
|
|
"items": items,
|
|
"source_matches_count": int(snapshot.get("source_matches_count") or 0)
|
|
if snapshot
|
|
else 0,
|
|
"ranked_players": len(items),
|
|
"skipped_regeneration": True,
|
|
}
|
|
|
|
ranking_rows = _fetch_leaderboard_rows(
|
|
connection,
|
|
server_key=normalized_server_key,
|
|
metric=normalized_metric,
|
|
limit=normalized_limit,
|
|
window_start=window["start"],
|
|
window_end=window["end"],
|
|
)
|
|
source_matches_count = _count_matches(
|
|
connection,
|
|
server_key=normalized_server_key,
|
|
start=window["start"],
|
|
end=window["end"],
|
|
)
|
|
|
|
if existing_snapshot_id is not None:
|
|
_delete_snapshot(connection=connection, snapshot_id=existing_snapshot_id)
|
|
|
|
snapshot_id = _insert_snapshot_record(
|
|
connection=connection,
|
|
timeframe=normalized_timeframe,
|
|
server_key=normalized_server_key,
|
|
metric=normalized_metric,
|
|
limit=normalized_limit,
|
|
source_matches_count=source_matches_count,
|
|
window_start=window_start,
|
|
window_end=window_end,
|
|
generated_at=_to_iso(datetime.now(timezone.utc)),
|
|
window_kind=str(window["kind"]),
|
|
window_label=str(window["label"]),
|
|
item_count=len(ranking_rows),
|
|
)
|
|
_insert_snapshot_items(
|
|
connection=connection,
|
|
snapshot_id=snapshot_id,
|
|
rows=ranking_rows,
|
|
limit=normalized_limit,
|
|
)
|
|
snapshot = _get_snapshot_record(connection=connection, snapshot_id=snapshot_id)
|
|
items = _list_snapshot_items(connection=connection, snapshot_id=snapshot_id)
|
|
|
|
return {
|
|
"status": "ok",
|
|
"snapshot": snapshot,
|
|
"items": items,
|
|
"source_matches_count": source_matches_count,
|
|
"ranked_players": len(items),
|
|
"skipped_regeneration": False,
|
|
}
|
|
|
|
|
|
def refresh_ranking_snapshots(
|
|
*,
|
|
limit: int = DEFAULT_RANKING_SNAPSHOT_REFRESH_LIMIT,
|
|
replace_existing: bool = True,
|
|
timeframes: tuple[str, ...] | None = None,
|
|
ensure_storage: bool = True,
|
|
now: datetime | None = None,
|
|
db_path: Path | None = None,
|
|
) -> dict[str, object]:
|
|
"""Generate the full weekly/monthly ranking snapshot matrix with partial-failure reporting."""
|
|
normalized_limit = _normalize_limit(limit)
|
|
anchor = _as_utc(now or datetime.now(timezone.utc))
|
|
normalized_timeframes = tuple(
|
|
_normalize_generator_timeframe(timeframe)
|
|
for timeframe in (timeframes or SNAPSHOT_GENERATOR_TIMEFRAMES)
|
|
)
|
|
combinations = [
|
|
(timeframe, server_key, metric)
|
|
for timeframe in normalized_timeframes
|
|
for server_key in SNAPSHOT_GENERATOR_SERVER_KEYS
|
|
for metric in SNAPSHOT_GENERATOR_METRICS
|
|
]
|
|
results: list[dict[str, object]] = []
|
|
succeeded = 0
|
|
failed = 0
|
|
skipped_regeneration = 0
|
|
|
|
for timeframe, server_key, metric in combinations:
|
|
try:
|
|
payload = generate_ranking_snapshot(
|
|
timeframe=timeframe,
|
|
server_key=server_key,
|
|
metric=metric,
|
|
limit=normalized_limit,
|
|
replace_existing=replace_existing,
|
|
ensure_storage=ensure_storage if not results else False,
|
|
now=anchor,
|
|
db_path=db_path,
|
|
)
|
|
snapshot = payload.get("snapshot") if isinstance(payload, dict) else {}
|
|
skipped = bool(payload.get("skipped_regeneration")) if isinstance(payload, dict) else False
|
|
if skipped:
|
|
skipped_regeneration += 1
|
|
succeeded += 1
|
|
results.append(
|
|
{
|
|
"status": "ok",
|
|
"timeframe": timeframe,
|
|
"server_key": server_key,
|
|
"metric": metric,
|
|
"limit": normalized_limit,
|
|
"snapshot_id": snapshot.get("id") if isinstance(snapshot, dict) else None,
|
|
"snapshot_status": snapshot.get("snapshot_status")
|
|
if isinstance(snapshot, dict)
|
|
else None,
|
|
"window_start": snapshot.get("window_start") if isinstance(snapshot, dict) else None,
|
|
"window_end": snapshot.get("window_end") if isinstance(snapshot, dict) else None,
|
|
"generated_at": snapshot.get("generated_at") if isinstance(snapshot, dict) else None,
|
|
"ranked_players": int(payload.get("ranked_players") or 0),
|
|
"source_matches_count": int(payload.get("source_matches_count") or 0),
|
|
"skipped_regeneration": skipped,
|
|
}
|
|
)
|
|
except Exception as exc: # noqa: BLE001 - bulk refresh must report per-combination failures
|
|
failed += 1
|
|
results.append(
|
|
{
|
|
"status": "error",
|
|
"timeframe": timeframe,
|
|
"server_key": server_key,
|
|
"metric": metric,
|
|
"limit": normalized_limit,
|
|
"error_type": type(exc).__name__,
|
|
"error": str(exc),
|
|
}
|
|
)
|
|
|
|
overall_status = "ok"
|
|
if failed and succeeded:
|
|
overall_status = "partial"
|
|
elif failed:
|
|
overall_status = "error"
|
|
|
|
return {
|
|
"status": overall_status,
|
|
"generated_at": _to_iso(anchor),
|
|
"timeframes": list(normalized_timeframes),
|
|
"limit": normalized_limit,
|
|
"replace_existing": replace_existing,
|
|
"combinations_expected": len(combinations),
|
|
"totals": {
|
|
"combinations_expected": len(combinations),
|
|
"succeeded": succeeded,
|
|
"failed": failed,
|
|
"skipped_regeneration": skipped_regeneration,
|
|
},
|
|
"results": results,
|
|
}
|
|
|
|
|
|
def get_latest_ranking_snapshot(
|
|
*,
|
|
server_key: str | None = None,
|
|
timeframe: str = "weekly",
|
|
metric: str = "kills",
|
|
limit: int = 10,
|
|
db_path: Path | None = None,
|
|
) -> dict[str, object]:
|
|
"""Return the latest ready weekly/monthly ranking snapshot for the requested scope."""
|
|
normalized_server_key = _normalize_snapshot_server_key(server_key)
|
|
normalized_timeframe = _normalize_timeframe(timeframe)
|
|
normalized_metric = _normalize_metric(metric)
|
|
normalized_limit = max(1, int(limit or 10))
|
|
|
|
try:
|
|
with _open_ranking_snapshot_read_connection(db_path=db_path) as connection:
|
|
snapshot = _find_latest_snapshot(
|
|
connection=connection,
|
|
timeframe=normalized_timeframe,
|
|
server_key=normalized_server_key,
|
|
metric=normalized_metric,
|
|
)
|
|
if snapshot is None:
|
|
return _build_missing_ranking_snapshot_result(
|
|
timeframe=normalized_timeframe,
|
|
server_key=normalized_server_key,
|
|
metric=normalized_metric,
|
|
limit=normalized_limit,
|
|
)
|
|
|
|
snapshot_limit = max(1, int(snapshot.get("limit_size") or normalized_limit))
|
|
item_count = int(snapshot.get("item_count") or 0)
|
|
effective_limit = max(0, min(normalized_limit, snapshot_limit, item_count))
|
|
items = _list_snapshot_items(
|
|
connection=connection,
|
|
snapshot_id=int(snapshot["id"]),
|
|
limit=effective_limit if effective_limit > 0 else None,
|
|
)
|
|
except (FileNotFoundError, sqlite3.OperationalError):
|
|
return _build_missing_ranking_snapshot_result(
|
|
timeframe=normalized_timeframe,
|
|
server_key=normalized_server_key,
|
|
metric=normalized_metric,
|
|
limit=normalized_limit,
|
|
)
|
|
|
|
return {
|
|
"snapshot_status": "ready",
|
|
"timeframe": normalized_timeframe,
|
|
"server_id": normalized_server_key,
|
|
"metric": normalized_metric,
|
|
"limit": effective_limit,
|
|
"requested_limit": normalized_limit,
|
|
"effective_limit": effective_limit,
|
|
"snapshot_limit": snapshot_limit,
|
|
"item_count": item_count,
|
|
"generated_at": snapshot.get("generated_at"),
|
|
"window_start": snapshot.get("window_start"),
|
|
"window_end": snapshot.get("window_end"),
|
|
"window_kind": snapshot.get("window_kind"),
|
|
"window_label": snapshot.get("window_label"),
|
|
"source": snapshot.get("source") or "ranking-snapshot",
|
|
"freshness": snapshot.get("freshness") or "fresh",
|
|
"source_matches_count": int(snapshot.get("source_matches_count") or 0),
|
|
"items": items,
|
|
}
|
|
|
|
|
|
@contextmanager
|
|
def _open_ranking_snapshot_read_connection(*, db_path: Path | None = None):
|
|
if use_postgres_rcon_storage(explicit_sqlite_path=db_path):
|
|
from .postgres_rcon_storage import PostgresCompatConnection, connect_postgres
|
|
|
|
with connect_postgres() as connection:
|
|
yield PostgresCompatConnection(connection)
|
|
return
|
|
|
|
resolved_path = _resolve_ranking_snapshot_sqlite_path(db_path=db_path)
|
|
if not resolved_path.exists():
|
|
raise FileNotFoundError(resolved_path)
|
|
with closing(connect_sqlite_readonly(resolved_path)) as connection:
|
|
yield connection
|
|
|
|
|
|
def _resolve_ranking_snapshot_sqlite_path(*, db_path: Path | None = None) -> Path:
|
|
return db_path if db_path is not None else get_storage_path()
|
|
|
|
|
|
def _build_missing_ranking_snapshot_result(
|
|
*,
|
|
timeframe: str,
|
|
server_key: str,
|
|
metric: str,
|
|
limit: int,
|
|
) -> dict[str, object]:
|
|
return {
|
|
"snapshot_status": "missing",
|
|
"timeframe": timeframe,
|
|
"server_id": server_key,
|
|
"metric": metric,
|
|
"limit": limit,
|
|
"requested_limit": limit,
|
|
"effective_limit": 0,
|
|
"snapshot_limit": None,
|
|
"item_count": 0,
|
|
"generated_at": None,
|
|
"window_start": None,
|
|
"window_end": None,
|
|
"window_kind": None,
|
|
"window_label": None,
|
|
"source": "ranking-snapshot",
|
|
"freshness": "missing",
|
|
"source_matches_count": 0,
|
|
"items": [],
|
|
}
|
|
|
|
|
|
def build_rcon_materialized_leaderboard_snapshot_payload(
|
|
*,
|
|
server_id: str | None = None,
|
|
timeframe: str = "weekly",
|
|
metric: str = "kills",
|
|
limit: int = 10,
|
|
) -> dict[str, object]:
|
|
"""Return an API payload for RCON-backed leaderboard snapshots.
|
|
|
|
This is a runtime fast read over the materialized AdminLog tables. It intentionally
|
|
avoids the old public-scoreboard fallback because the UI is running in RCON mode.
|
|
"""
|
|
|
|
normalized_timeframe = _normalize_timeframe(timeframe)
|
|
normalized_metric = _normalize_metric(metric)
|
|
result = list_rcon_materialized_leaderboard(
|
|
server_key=server_id,
|
|
timeframe=normalized_timeframe,
|
|
metric=normalized_metric,
|
|
limit=limit,
|
|
)
|
|
items = list(result.get("items") or [])[:limit]
|
|
return {
|
|
"status": "ok",
|
|
"data": {
|
|
"title": _build_title(
|
|
metric=normalized_metric,
|
|
timeframe=normalized_timeframe,
|
|
server_id=server_id,
|
|
),
|
|
"context": f"historical-{normalized_timeframe}-leaderboard-snapshot",
|
|
"source": "rcon-materialized-admin-log-leaderboard",
|
|
"server_slug": server_id,
|
|
"timeframe": normalized_timeframe,
|
|
"metric": normalized_metric,
|
|
"found": True,
|
|
"snapshot_status": "ready",
|
|
"missing_reason": None,
|
|
"request_path_policy": "runtime-rcon-materialized-fast-path",
|
|
"generation_policy": "runtime-materialized-read",
|
|
"generated_at": _to_iso(datetime.now(timezone.utc)),
|
|
"source_range_start": result.get("source_range_start"),
|
|
"source_range_end": result.get("source_range_end"),
|
|
"is_stale": False,
|
|
"freshness": "runtime",
|
|
"window_days": result.get("window_days"),
|
|
"window_start": result.get("window_start"),
|
|
"window_end": result.get("window_end"),
|
|
"window_kind": result.get("window_kind"),
|
|
"window_label": result.get("window_label"),
|
|
"uses_fallback": False,
|
|
"selection_reason": result.get("selection_reason"),
|
|
"current_week_start": result.get("current_week_start"),
|
|
"current_week_closed_matches": result.get("current_week_closed_matches"),
|
|
"previous_week_closed_matches": result.get("previous_week_closed_matches"),
|
|
"current_month_start": result.get("current_month_start"),
|
|
"selected_month_start": result.get("selected_month_start"),
|
|
"selected_month_end": result.get("selected_month_end"),
|
|
"current_month_closed_matches": result.get("current_month_closed_matches"),
|
|
"previous_month_closed_matches": result.get("previous_month_closed_matches"),
|
|
"sufficient_sample": result.get("sufficient_sample"),
|
|
"snapshot_limit": result.get("limit"),
|
|
"limit": limit,
|
|
"runtime_enrichment": {
|
|
"applied": False,
|
|
"reason": None,
|
|
},
|
|
"primary_source": "rcon",
|
|
"selected_source": "rcon",
|
|
"fallback_used": False,
|
|
"fallback_reason": None,
|
|
"source_attempts": [
|
|
{
|
|
"source": "rcon",
|
|
"role": "primary",
|
|
"status": "success",
|
|
"reason": "leaderboard-served-by-rcon-materialized-admin-log",
|
|
"message": None,
|
|
}
|
|
],
|
|
"items": items,
|
|
},
|
|
}
|
|
|
|
|
|
def list_rcon_materialized_leaderboard(
|
|
*,
|
|
server_key: str | None = None,
|
|
timeframe: str = "weekly",
|
|
metric: str = "kills",
|
|
limit: int = 10,
|
|
ensure_storage: bool = True,
|
|
db_path: Path | None = None,
|
|
now: datetime | None = None,
|
|
) -> dict[str, object]:
|
|
"""Return a leaderboard built from materialized RCON/AdminLog player stats.
|
|
|
|
RCON/AdminLog materialization currently has reliable kill/death/teamkill counters,
|
|
but not public-scoreboard support points. For support, return an explicitly empty
|
|
supported payload rather than falling back to unrelated public scoreboard storage.
|
|
"""
|
|
|
|
normalized_timeframe = _normalize_timeframe(timeframe)
|
|
normalized_metric = _normalize_metric(metric)
|
|
normalized_limit = max(1, int(limit or 10))
|
|
anchor = _as_utc(now or datetime.now(timezone.utc))
|
|
|
|
resolved_path = initialize_rcon_materialized_storage(
|
|
db_path=db_path,
|
|
ensure_storage=ensure_storage,
|
|
)
|
|
connection_scope = _connect_scope(
|
|
resolved_path,
|
|
db_path=db_path,
|
|
initialize=ensure_storage,
|
|
)
|
|
with connection_scope as connection:
|
|
window = select_leaderboard_window(
|
|
connection=connection,
|
|
server_key=server_key,
|
|
timeframe=normalized_timeframe,
|
|
now=anchor,
|
|
)
|
|
if normalized_metric == "support":
|
|
return _empty_payload(
|
|
server_key=server_key,
|
|
timeframe=normalized_timeframe,
|
|
metric=normalized_metric,
|
|
limit=normalized_limit,
|
|
window=window,
|
|
reason="rcon-materialized-stats-do-not-include-support-score",
|
|
)
|
|
rows = _fetch_leaderboard_rows(
|
|
connection,
|
|
server_key=server_key,
|
|
metric=normalized_metric,
|
|
limit=normalized_limit,
|
|
window_start=window["start"],
|
|
window_end=window["end"],
|
|
)
|
|
source_range = _fetch_source_range(
|
|
connection,
|
|
server_key=server_key,
|
|
window_start=window["start"],
|
|
window_end=window["end"],
|
|
)
|
|
|
|
items = [_build_item(row, index=index + 1) for index, row in enumerate(rows)]
|
|
return {
|
|
"source": "rcon-materialized-admin-log-leaderboard",
|
|
"server_key": server_key,
|
|
"metric": normalized_metric,
|
|
"limit": normalized_limit,
|
|
"window_days": window["days"],
|
|
"window_start": _to_iso(window["start"]),
|
|
"window_end": _to_iso(window["end"]),
|
|
"window_kind": window["kind"],
|
|
"window_label": window["label"],
|
|
"uses_fallback": False,
|
|
"selection_reason": window["selection_reason"],
|
|
"current_week_start": _to_iso(window["current_week_start"]),
|
|
"current_week_closed_matches": window["current_week_closed_matches"],
|
|
"previous_week_closed_matches": window["previous_week_closed_matches"],
|
|
"current_month_start": _to_iso(window["current_month_start"]),
|
|
"selected_month_start": _to_iso(window["selected_month_start"]),
|
|
"selected_month_end": _to_iso(window["selected_month_end"]),
|
|
"current_month_closed_matches": window["current_month_closed_matches"],
|
|
"previous_month_closed_matches": window["previous_month_closed_matches"],
|
|
"sufficient_sample": window["sufficient_sample"],
|
|
"source_range_start": _to_iso(source_range[0]) if source_range[0] else None,
|
|
"source_range_end": _to_iso(source_range[1]) if source_range[1] else None,
|
|
"items": items,
|
|
}
|
|
|
|
|
|
def _find_latest_snapshot(
|
|
*,
|
|
connection: object,
|
|
timeframe: str,
|
|
server_key: str,
|
|
metric: str,
|
|
) -> dict[str, object] | None:
|
|
row = connection.execute(
|
|
"""
|
|
SELECT
|
|
id,
|
|
timeframe,
|
|
server_id,
|
|
metric,
|
|
window_start,
|
|
window_end,
|
|
generated_at,
|
|
source,
|
|
snapshot_status,
|
|
item_count,
|
|
limit_size,
|
|
source_matches_count,
|
|
freshness,
|
|
window_kind,
|
|
window_label
|
|
FROM ranking_snapshots
|
|
WHERE timeframe = ?
|
|
AND server_id = ?
|
|
AND metric = ?
|
|
AND snapshot_status = 'ready'
|
|
ORDER BY window_end DESC, generated_at DESC
|
|
LIMIT 1
|
|
""",
|
|
[timeframe, server_key, metric],
|
|
).fetchone()
|
|
return dict(row) if row else None
|
|
|
|
|
|
def _find_existing_snapshot_for_window(
|
|
*,
|
|
connection: object,
|
|
timeframe: str,
|
|
server_key: str,
|
|
metric: str,
|
|
window_start: str,
|
|
window_end: str,
|
|
) -> int | None:
|
|
row = connection.execute(
|
|
"""
|
|
SELECT id
|
|
FROM ranking_snapshots
|
|
WHERE timeframe = ?
|
|
AND server_id = ?
|
|
AND metric = ?
|
|
AND window_start = ?
|
|
AND window_end = ?
|
|
LIMIT 1
|
|
""",
|
|
[timeframe, server_key, metric, window_start, window_end],
|
|
).fetchone()
|
|
return int(row["id"]) if row else None
|
|
|
|
|
|
def _get_snapshot_record(
|
|
*,
|
|
connection: object,
|
|
snapshot_id: int,
|
|
) -> dict[str, object] | None:
|
|
row = connection.execute(
|
|
"""
|
|
SELECT
|
|
id,
|
|
timeframe,
|
|
server_id,
|
|
metric,
|
|
window_start,
|
|
window_end,
|
|
generated_at,
|
|
source,
|
|
snapshot_status,
|
|
item_count,
|
|
limit_size,
|
|
source_matches_count,
|
|
freshness,
|
|
window_kind,
|
|
window_label,
|
|
error_message
|
|
FROM ranking_snapshots
|
|
WHERE id = ?
|
|
LIMIT 1
|
|
""",
|
|
[snapshot_id],
|
|
).fetchone()
|
|
return dict(row) if row else None
|
|
|
|
|
|
def _list_snapshot_items(
|
|
*,
|
|
connection: object,
|
|
snapshot_id: int,
|
|
limit: int | None = None,
|
|
) -> list[dict[str, object]]:
|
|
params: list[object] = [snapshot_id]
|
|
query = """
|
|
SELECT
|
|
ranking_position,
|
|
player_id,
|
|
player_name,
|
|
metric_value,
|
|
matches_considered,
|
|
kills,
|
|
deaths,
|
|
teamkills,
|
|
kd_ratio,
|
|
kills_per_match
|
|
FROM ranking_snapshot_items
|
|
WHERE snapshot_id = ?
|
|
ORDER BY ranking_position ASC
|
|
"""
|
|
if limit is not None:
|
|
query = f"{query}\n LIMIT ?"
|
|
params.append(limit)
|
|
rows = connection.execute(query, params).fetchall()
|
|
return [dict(row) for row in rows]
|
|
|
|
|
|
def _delete_snapshot(*, connection: object, snapshot_id: int) -> None:
|
|
connection.execute(
|
|
"DELETE FROM ranking_snapshot_items WHERE snapshot_id = ?",
|
|
[snapshot_id],
|
|
)
|
|
connection.execute(
|
|
"DELETE FROM ranking_snapshots WHERE id = ?",
|
|
[snapshot_id],
|
|
)
|
|
|
|
|
|
def _insert_snapshot_record(
|
|
*,
|
|
connection: object,
|
|
timeframe: str,
|
|
server_key: str,
|
|
metric: str,
|
|
limit: int,
|
|
source_matches_count: int,
|
|
window_start: str,
|
|
window_end: str,
|
|
generated_at: str,
|
|
window_kind: str,
|
|
window_label: str,
|
|
item_count: int,
|
|
) -> int:
|
|
cursor = connection.execute(
|
|
"""
|
|
INSERT INTO ranking_snapshots (
|
|
timeframe,
|
|
server_id,
|
|
metric,
|
|
window_start,
|
|
window_end,
|
|
generated_at,
|
|
source,
|
|
snapshot_status,
|
|
item_count,
|
|
limit_size,
|
|
source_matches_count,
|
|
freshness,
|
|
window_kind,
|
|
window_label,
|
|
error_message
|
|
) VALUES (?, ?, ?, ?, ?, ?, ?, 'ready', ?, ?, ?, 'fresh', ?, ?, NULL)
|
|
RETURNING id
|
|
""",
|
|
[
|
|
timeframe,
|
|
server_key,
|
|
metric,
|
|
window_start,
|
|
window_end,
|
|
generated_at,
|
|
"rcon-materialized-admin-log",
|
|
item_count,
|
|
limit,
|
|
source_matches_count,
|
|
window_kind,
|
|
window_label,
|
|
],
|
|
)
|
|
row = cursor.fetchone()
|
|
if row is None or row["id"] is None:
|
|
raise RuntimeError("Unable to resolve ranking snapshot id after insert.")
|
|
return int(row["id"])
|
|
|
|
|
|
def _insert_snapshot_items(
|
|
*,
|
|
connection: object,
|
|
snapshot_id: int,
|
|
rows: list[dict[str, object]],
|
|
limit: int,
|
|
) -> None:
|
|
deduplicated_rows = _dedupe_snapshot_rows(rows)
|
|
for index, row in enumerate(deduplicated_rows[:limit], start=1):
|
|
item = _build_item(row, index=index)
|
|
connection.execute(
|
|
"""
|
|
INSERT INTO ranking_snapshot_items (
|
|
snapshot_id,
|
|
ranking_position,
|
|
player_id,
|
|
player_name,
|
|
metric_value,
|
|
matches_considered,
|
|
kills,
|
|
deaths,
|
|
teamkills,
|
|
kd_ratio,
|
|
kills_per_match
|
|
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
|
""",
|
|
[
|
|
snapshot_id,
|
|
int(item["ranking_position"]),
|
|
str(item["player_id"]),
|
|
str(item["player_name"]),
|
|
float(item["metric_value"]),
|
|
int(item["matches_considered"]),
|
|
int(item["kills"]),
|
|
int(item["deaths"]),
|
|
int(item["teamkills"]),
|
|
float(item["kd_ratio"]),
|
|
float(item["kills_per_match"]),
|
|
],
|
|
)
|
|
|
|
|
|
def _dedupe_snapshot_rows(rows: list[dict[str, object]]) -> list[dict[str, object]]:
|
|
"""Keep the first ranked row for each player id to preserve deterministic snapshot order."""
|
|
deduplicated_rows: list[dict[str, object]] = []
|
|
seen_player_ids: set[str] = set()
|
|
for row in rows:
|
|
player_id = str(row.get("player_id") or "").strip()
|
|
if not player_id or player_id in seen_player_ids:
|
|
continue
|
|
seen_player_ids.add(player_id)
|
|
deduplicated_rows.append(row)
|
|
return deduplicated_rows
|
|
|
|
|
|
def _fetch_leaderboard_rows(
|
|
connection: object,
|
|
*,
|
|
server_key: str | None,
|
|
metric: str,
|
|
limit: int,
|
|
window_start: datetime,
|
|
window_end: datetime,
|
|
) -> list[dict[str, object]]:
|
|
scope_sql, scope_params = _build_scope_sql(server_key)
|
|
metric_sql, having_sql, order_by_sql = _resolve_metric_sql(metric)
|
|
params: list[object] = [
|
|
_to_iso(window_start),
|
|
_to_iso(window_end),
|
|
*scope_params,
|
|
limit,
|
|
]
|
|
rows = connection.execute(
|
|
f"""
|
|
SELECT
|
|
stats.player_id,
|
|
stats.player_name,
|
|
{metric_sql} AS metric_value,
|
|
COUNT(DISTINCT stats.match_key) AS matches_considered,
|
|
SUM(COALESCE(stats.kills, 0)) AS kills,
|
|
SUM(COALESCE(stats.deaths, 0)) AS deaths,
|
|
SUM(COALESCE(stats.teamkills, 0)) AS teamkills
|
|
FROM rcon_match_player_stats AS stats
|
|
INNER JOIN rcon_materialized_matches AS matches
|
|
ON matches.target_key = stats.target_key
|
|
AND matches.match_key = stats.match_key
|
|
WHERE matches.source_basis = ?
|
|
AND COALESCE(CAST(matches.ended_at AS TEXT), CAST(matches.started_at AS TEXT)) >= ?
|
|
AND COALESCE(CAST(matches.ended_at AS TEXT), CAST(matches.started_at AS TEXT)) <= ?
|
|
{scope_sql}
|
|
AND TRIM(COALESCE(stats.player_name, '')) != ''
|
|
GROUP BY stats.player_id, stats.player_name
|
|
{having_sql}
|
|
ORDER BY {order_by_sql}
|
|
LIMIT ?
|
|
""",
|
|
[MATCH_RESULT_SOURCE, *params],
|
|
).fetchall()
|
|
return [dict(row) for row in rows]
|
|
|
|
|
|
def _fetch_match_counts(
|
|
connection: object,
|
|
*,
|
|
server_key: str | None,
|
|
timeframe: str,
|
|
window_start: datetime,
|
|
window_end: datetime,
|
|
) -> dict[str, int]:
|
|
current_week_start = _week_start(window_end)
|
|
previous_week_start = current_week_start - timedelta(days=7)
|
|
current_month_start = _month_start(window_end)
|
|
previous_month_start = _previous_month_start(current_month_start)
|
|
return {
|
|
"current_week_closed_matches": _count_matches(
|
|
connection,
|
|
server_key=server_key,
|
|
start=current_week_start,
|
|
end=window_end,
|
|
),
|
|
"previous_week_closed_matches": _count_matches(
|
|
connection,
|
|
server_key=server_key,
|
|
start=previous_week_start,
|
|
end=current_week_start,
|
|
),
|
|
"current_month_closed_matches": _count_matches(
|
|
connection,
|
|
server_key=server_key,
|
|
start=current_month_start,
|
|
end=window_end,
|
|
),
|
|
"previous_month_closed_matches": _count_matches(
|
|
connection,
|
|
server_key=server_key,
|
|
start=previous_month_start,
|
|
end=current_month_start,
|
|
),
|
|
}
|
|
|
|
|
|
def select_leaderboard_window(
|
|
*,
|
|
connection: object,
|
|
server_key: str | None,
|
|
timeframe: str,
|
|
now: datetime | None = None,
|
|
) -> dict[str, object]:
|
|
"""Select the RCON leaderboard window using weekly/monthly fallback policy."""
|
|
anchor = _as_utc(now or datetime.now(timezone.utc))
|
|
current_week_start = _week_start(anchor)
|
|
previous_week_start = current_week_start - timedelta(days=7)
|
|
current_month_start = _month_start(anchor)
|
|
previous_month_start = _previous_month_start(current_month_start)
|
|
minimum_week_matches = get_historical_weekly_fallback_min_matches()
|
|
current_week_count = _count_matches(
|
|
connection,
|
|
server_key=server_key,
|
|
start=current_week_start,
|
|
end=anchor,
|
|
)
|
|
previous_week_count = _count_matches(
|
|
connection,
|
|
server_key=server_key,
|
|
start=previous_week_start,
|
|
end=current_week_start,
|
|
)
|
|
current_month_count = _count_matches(
|
|
connection,
|
|
server_key=server_key,
|
|
start=current_month_start,
|
|
end=anchor,
|
|
)
|
|
previous_month_count = _count_matches(
|
|
connection,
|
|
server_key=server_key,
|
|
start=previous_month_start,
|
|
end=current_month_start,
|
|
)
|
|
|
|
if timeframe == "monthly":
|
|
use_previous_month = anchor.day <= 7
|
|
start = previous_month_start if use_previous_month else current_month_start
|
|
end = current_month_start if use_previous_month else anchor
|
|
return {
|
|
"start": start,
|
|
"end": end,
|
|
"days": max(1, (end.date() - start.date()).days),
|
|
"kind": "previous-month" if use_previous_month else "current-month",
|
|
"label": "Mes anterior" if use_previous_month else "Mes actual",
|
|
"selection_reason": (
|
|
"monthly-uses-previous-month-until-day-8"
|
|
if use_previous_month
|
|
else "monthly-uses-current-month-after-day-7"
|
|
),
|
|
"current_week_start": current_week_start,
|
|
"current_week_closed_matches": current_week_count,
|
|
"previous_week_closed_matches": previous_week_count,
|
|
"current_month_start": current_month_start,
|
|
"selected_month_start": start,
|
|
"selected_month_end": end,
|
|
"current_month_closed_matches": current_month_count,
|
|
"previous_month_closed_matches": previous_month_count,
|
|
"sufficient_sample": {
|
|
"minimum_closed_matches": 1,
|
|
"current_month_closed_matches": current_month_count,
|
|
"previous_month_closed_matches": previous_month_count,
|
|
"current_month_has_sufficient_sample": current_month_count >= 1,
|
|
"uses_previous_month_until_day": 7,
|
|
},
|
|
}
|
|
|
|
current_week_has_sample = current_week_count >= minimum_week_matches
|
|
start = current_week_start if current_week_has_sample else previous_week_start
|
|
end = anchor if current_week_has_sample else current_week_start
|
|
return {
|
|
"start": start,
|
|
"end": end,
|
|
"days": max(1, (end.date() - start.date()).days),
|
|
"kind": "current-week" if current_week_has_sample else "previous-week",
|
|
"label": "Semana actual" if current_week_has_sample else "Semana anterior",
|
|
"selection_reason": (
|
|
"weekly-current-week-has-sufficient-closed-matches"
|
|
if current_week_has_sample
|
|
else "weekly-fallback-previous-week-insufficient-current-week-data"
|
|
),
|
|
"current_week_start": current_week_start,
|
|
"current_week_closed_matches": current_week_count,
|
|
"previous_week_closed_matches": previous_week_count,
|
|
"current_month_start": current_month_start,
|
|
"selected_month_start": current_month_start,
|
|
"selected_month_end": anchor,
|
|
"current_month_closed_matches": current_month_count,
|
|
"previous_month_closed_matches": previous_month_count,
|
|
"sufficient_sample": {
|
|
"minimum_closed_matches": minimum_week_matches,
|
|
"current_week_closed_matches": current_week_count,
|
|
"current_week_has_sufficient_sample": current_week_has_sample,
|
|
"previous_week_closed_matches": previous_week_count,
|
|
},
|
|
}
|
|
|
|
|
|
def _fetch_source_range(
|
|
connection: object,
|
|
*,
|
|
server_key: str | None,
|
|
window_start: datetime,
|
|
window_end: datetime,
|
|
) -> tuple[datetime | None, datetime | None]:
|
|
scope_sql, scope_params = _build_scope_sql(server_key, table_alias="matches")
|
|
row = connection.execute(
|
|
f"""
|
|
SELECT
|
|
MIN(COALESCE(CAST(matches.ended_at AS TEXT), CAST(matches.started_at AS TEXT))) AS source_range_start,
|
|
MAX(COALESCE(CAST(matches.ended_at AS TEXT), CAST(matches.started_at AS TEXT))) AS source_range_end
|
|
FROM rcon_materialized_matches AS matches
|
|
WHERE matches.source_basis = ?
|
|
AND COALESCE(CAST(matches.ended_at AS TEXT), CAST(matches.started_at AS TEXT)) >= ?
|
|
AND COALESCE(CAST(matches.ended_at AS TEXT), CAST(matches.started_at AS TEXT)) <= ?
|
|
{scope_sql}
|
|
""",
|
|
[MATCH_RESULT_SOURCE, _to_iso(window_start), _to_iso(window_end), *scope_params],
|
|
).fetchone()
|
|
if not row:
|
|
return None, None
|
|
return _parse_datetime(row["source_range_start"]), _parse_datetime(row["source_range_end"])
|
|
|
|
|
|
def _count_matches(
|
|
connection: object,
|
|
*,
|
|
server_key: str | None,
|
|
start: datetime,
|
|
end: datetime,
|
|
) -> int:
|
|
scope_sql, scope_params = _build_scope_sql(server_key, table_alias="matches")
|
|
row = connection.execute(
|
|
f"""
|
|
SELECT COUNT(*) AS count
|
|
FROM rcon_materialized_matches AS matches
|
|
WHERE matches.source_basis = ?
|
|
AND COALESCE(CAST(matches.ended_at AS TEXT), CAST(matches.started_at AS TEXT)) >= ?
|
|
AND COALESCE(CAST(matches.ended_at AS TEXT), CAST(matches.started_at AS TEXT)) < ?
|
|
{scope_sql}
|
|
""",
|
|
[MATCH_RESULT_SOURCE, _to_iso(start), _to_iso(end), *scope_params],
|
|
).fetchone()
|
|
return int(row["count"] or 0) if row else 0
|
|
|
|
|
|
def _build_item(row: dict[str, object], *, index: int) -> dict[str, object]:
|
|
kills = _coerce_int(row.get("kills"))
|
|
deaths = _coerce_int(row.get("deaths"))
|
|
matches_considered = _coerce_int(row.get("matches_considered"))
|
|
kd_ratio = round(kills / deaths, 2) if deaths else float(kills)
|
|
kills_per_match = round(kills / matches_considered, 2) if matches_considered else 0.0
|
|
return {
|
|
"ranking_position": index,
|
|
"player": {
|
|
"id": row.get("player_id"),
|
|
"name": row.get("player_name"),
|
|
},
|
|
"player_id": row.get("player_id"),
|
|
"player_name": row.get("player_name"),
|
|
"metric_value": _coerce_metric_value(row.get("metric_value")),
|
|
"matches_considered": matches_considered,
|
|
"kills": kills,
|
|
"deaths": deaths,
|
|
"teamkills": _coerce_int(row.get("teamkills")),
|
|
"kd_ratio": kd_ratio,
|
|
"kills_per_match": kills_per_match,
|
|
}
|
|
|
|
|
|
def _build_scope_sql(
|
|
server_key: str | None,
|
|
*,
|
|
table_alias: str = "matches",
|
|
) -> tuple[str, list[object]]:
|
|
if not server_key or server_key == ALL_SERVERS_SLUG:
|
|
return "", []
|
|
return f"AND ({table_alias}.target_key = ? OR {table_alias}.external_server_id = ?)", [
|
|
server_key,
|
|
server_key,
|
|
]
|
|
|
|
|
|
def _normalize_snapshot_server_key(server_key: str | None) -> str:
|
|
normalized = str(server_key or "").strip()
|
|
normalized_lower = normalized.lower()
|
|
if not normalized or normalized_lower in {ALL_SERVERS_SLUG, "all"}:
|
|
return ALL_SERVERS_SLUG
|
|
return normalized
|
|
|
|
|
|
def _connect_scope(resolved_path: Path, *, db_path: Path | None, initialize: bool = True):
|
|
if use_postgres_rcon_storage(explicit_sqlite_path=db_path):
|
|
from .postgres_rcon_storage import connect_postgres_compat
|
|
|
|
return connect_postgres_compat(initialize=initialize)
|
|
return closing(connect_sqlite_readonly(resolved_path))
|
|
|
|
|
|
def _connect_write_scope(
|
|
resolved_path: Path,
|
|
*,
|
|
db_path: Path | None,
|
|
initialize: bool = True,
|
|
):
|
|
if use_postgres_rcon_storage(explicit_sqlite_path=db_path):
|
|
from .postgres_rcon_storage import connect_postgres_compat
|
|
|
|
return connect_postgres_compat(initialize=initialize)
|
|
return connect_sqlite_writer(resolved_path)
|
|
|
|
|
|
def _empty_payload(
|
|
*,
|
|
server_key: str | None,
|
|
timeframe: str,
|
|
metric: str,
|
|
limit: int,
|
|
window: dict[str, object],
|
|
reason: str,
|
|
) -> dict[str, object]:
|
|
return {
|
|
"source": "rcon-materialized-admin-log-leaderboard",
|
|
"server_key": server_key,
|
|
"metric": metric,
|
|
"limit": limit,
|
|
"window_days": window["days"],
|
|
"window_start": _to_iso(window["start"]),
|
|
"window_end": _to_iso(window["end"]),
|
|
"window_kind": window["kind"],
|
|
"window_label": window["label"],
|
|
"uses_fallback": False,
|
|
"selection_reason": reason,
|
|
"current_week_start": _to_iso(window["current_week_start"]),
|
|
"current_week_closed_matches": window["current_week_closed_matches"],
|
|
"previous_week_closed_matches": window["previous_week_closed_matches"],
|
|
"current_month_start": _to_iso(window["current_month_start"]),
|
|
"selected_month_start": _to_iso(window["selected_month_start"]),
|
|
"selected_month_end": _to_iso(window["selected_month_end"]),
|
|
"current_month_closed_matches": window["current_month_closed_matches"],
|
|
"previous_month_closed_matches": window["previous_month_closed_matches"],
|
|
"sufficient_sample": window["sufficient_sample"],
|
|
"source_range_start": None,
|
|
"source_range_end": None,
|
|
"items": [],
|
|
}
|
|
|
|
|
|
def _build_window(timeframe: str) -> dict[str, object]:
|
|
now = datetime.now(timezone.utc)
|
|
if timeframe == "monthly":
|
|
start = _month_start(now)
|
|
return {
|
|
"start": start,
|
|
"end": now,
|
|
"days": max(1, (now.date() - start.date()).days + 1),
|
|
"kind": "current-month",
|
|
"label": "Mes actual",
|
|
}
|
|
start = _week_start(now)
|
|
return {
|
|
"start": start,
|
|
"end": now,
|
|
"days": max(1, (now.date() - start.date()).days + 1),
|
|
"kind": "current-week",
|
|
"label": "Semana actual",
|
|
}
|
|
|
|
|
|
def _as_utc(value: datetime) -> datetime:
|
|
if value.tzinfo is None:
|
|
return value.replace(tzinfo=timezone.utc)
|
|
return value.astimezone(timezone.utc)
|
|
|
|
|
|
def _week_start(value: datetime) -> datetime:
|
|
point = value.astimezone(timezone.utc)
|
|
start = point - timedelta(days=point.weekday())
|
|
return start.replace(hour=0, minute=0, second=0, microsecond=0)
|
|
|
|
|
|
def _month_start(value: datetime) -> datetime:
|
|
point = value.astimezone(timezone.utc)
|
|
return point.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
|
|
|
|
|
|
def _previous_month_start(current_month_start: datetime) -> datetime:
|
|
previous_month_end = current_month_start - timedelta(days=1)
|
|
return _month_start(previous_month_end)
|
|
|
|
|
|
def _normalize_timeframe(value: str) -> LeaderboardTimeframe:
|
|
return "monthly" if str(value or "").strip().lower() == "monthly" else "weekly"
|
|
|
|
|
|
def _normalize_generator_timeframe(value: str) -> str:
|
|
normalized = str(value or "").strip().lower()
|
|
if normalized not in SNAPSHOT_GENERATOR_TIMEFRAMES:
|
|
raise ValueError(
|
|
f"timeframe must be one of: {', '.join(SNAPSHOT_GENERATOR_TIMEFRAMES)}"
|
|
)
|
|
return normalized
|
|
|
|
|
|
def _normalize_generator_server_key(server_key: str | None) -> str:
|
|
normalized = _normalize_snapshot_server_key(server_key)
|
|
if normalized not in SNAPSHOT_GENERATOR_SERVER_KEYS:
|
|
raise ValueError(
|
|
"server_key must be one of: all, all-servers, comunidad-hispana-01, comunidad-hispana-02"
|
|
)
|
|
return normalized
|
|
|
|
|
|
def _normalize_generator_metric(metric: str) -> str:
|
|
normalized = str(metric or "").strip().lower()
|
|
if normalized not in SNAPSHOT_GENERATOR_METRICS:
|
|
raise ValueError(
|
|
f"metric must be one of: {', '.join(SNAPSHOT_GENERATOR_METRICS)}"
|
|
)
|
|
return normalized
|
|
|
|
|
|
def _normalize_limit(limit: object, *, maximum: int = 100) -> int:
|
|
normalized_limit = int(limit or 1)
|
|
if normalized_limit < 1:
|
|
raise ValueError("limit must be greater than zero")
|
|
return min(normalized_limit, maximum)
|
|
|
|
|
|
def _normalize_metric(value: str) -> LeaderboardMetric:
|
|
normalized = str(value or "kills").strip().lower()
|
|
if normalized in {
|
|
"kills",
|
|
"deaths",
|
|
"teamkills",
|
|
"matches_considered",
|
|
"kd_ratio",
|
|
"kills_per_match",
|
|
"matches_over_100_kills",
|
|
"support",
|
|
}:
|
|
return normalized # type: ignore[return-value]
|
|
return "kills"
|
|
|
|
|
|
def _build_title(*, metric: str, timeframe: str, server_id: str | None) -> str:
|
|
timeframe_label = "mensual" if timeframe == "monthly" else "semanal"
|
|
scope = "totales" if server_id == ALL_SERVERS_SLUG else "por servidor"
|
|
metric_label = {
|
|
"kills": "Top kills",
|
|
"deaths": "Top muertes",
|
|
"teamkills": "Top teamkills",
|
|
"matches_considered": "Top partidas jugadas",
|
|
"kd_ratio": "Top K/D",
|
|
"kills_per_match": "Top kills por partida",
|
|
"matches_over_100_kills": "Partidas 100+ kills",
|
|
"support": "Top soporte",
|
|
}.get(metric, "Top kills")
|
|
return f"Snapshot {metric_label} {timeframe_label} {scope}"
|
|
|
|
|
|
def _coerce_int(value: object) -> int:
|
|
try:
|
|
return int(value or 0)
|
|
except (TypeError, ValueError):
|
|
return 0
|
|
|
|
|
|
def _coerce_metric_value(value: object) -> int | float:
|
|
numeric = _coerce_float(value)
|
|
if numeric.is_integer():
|
|
return int(numeric)
|
|
return round(numeric, 2)
|
|
|
|
|
|
def _coerce_float(value: object) -> float:
|
|
try:
|
|
return float(value or 0)
|
|
except (TypeError, ValueError):
|
|
return 0.0
|
|
|
|
|
|
def _resolve_metric_sql(metric: str) -> tuple[str, str, str]:
|
|
metric_sql_by_metric = {
|
|
"kills": "SUM(COALESCE(stats.kills, 0))",
|
|
"deaths": "SUM(COALESCE(stats.deaths, 0))",
|
|
"teamkills": "SUM(COALESCE(stats.teamkills, 0))",
|
|
"matches_considered": "COUNT(DISTINCT stats.match_key)",
|
|
"kd_ratio": (
|
|
"CASE "
|
|
"WHEN SUM(COALESCE(stats.deaths, 0)) > 0 "
|
|
"THEN ROUND(CAST(SUM(COALESCE(stats.kills, 0)) AS NUMERIC) / "
|
|
"CAST(SUM(COALESCE(stats.deaths, 0)) AS NUMERIC), 2) "
|
|
"ELSE CAST(SUM(COALESCE(stats.kills, 0)) AS NUMERIC) "
|
|
"END"
|
|
),
|
|
"kills_per_match": (
|
|
"CASE "
|
|
"WHEN COUNT(DISTINCT stats.match_key) > 0 "
|
|
"THEN ROUND(CAST(SUM(COALESCE(stats.kills, 0)) AS NUMERIC) / "
|
|
"CAST(COUNT(DISTINCT stats.match_key) AS NUMERIC), 2) "
|
|
"ELSE CAST(0 AS NUMERIC) "
|
|
"END"
|
|
),
|
|
"matches_over_100_kills": "SUM(CASE WHEN COALESCE(stats.kills, 0) >= 100 THEN 1 ELSE 0 END)",
|
|
}
|
|
having_sql_by_metric = {
|
|
"kills": "HAVING SUM(COALESCE(stats.kills, 0)) > 0",
|
|
"deaths": "HAVING SUM(COALESCE(stats.deaths, 0)) > 0",
|
|
"teamkills": "HAVING SUM(COALESCE(stats.teamkills, 0)) > 0",
|
|
"matches_considered": "HAVING COUNT(DISTINCT stats.match_key) > 0",
|
|
"kd_ratio": "HAVING SUM(COALESCE(stats.kills, 0)) > 0",
|
|
"kills_per_match": "HAVING COUNT(DISTINCT stats.match_key) > 0 AND SUM(COALESCE(stats.kills, 0)) > 0",
|
|
"matches_over_100_kills": "HAVING SUM(CASE WHEN COALESCE(stats.kills, 0) >= 100 THEN 1 ELSE 0 END) > 0",
|
|
}
|
|
order_by_sql_by_metric = {
|
|
"kills": "metric_value DESC, matches_considered DESC, stats.player_name ASC",
|
|
"deaths": "metric_value DESC, matches_considered DESC, stats.player_name ASC",
|
|
"teamkills": "metric_value DESC, matches_considered DESC, stats.player_name ASC",
|
|
"matches_considered": "metric_value DESC, kills DESC, stats.player_name ASC",
|
|
"kd_ratio": "metric_value DESC, kills DESC, matches_considered DESC, stats.player_name ASC",
|
|
"kills_per_match": "metric_value DESC, kills DESC, matches_considered DESC, stats.player_name ASC",
|
|
"matches_over_100_kills": "metric_value DESC, matches_considered DESC, stats.player_name ASC",
|
|
}
|
|
if metric == "support":
|
|
raise ValueError("support is handled separately")
|
|
return (
|
|
metric_sql_by_metric[metric],
|
|
having_sql_by_metric[metric],
|
|
order_by_sql_by_metric[metric],
|
|
)
|
|
|
|
|
|
def _parse_datetime(value: object) -> datetime | None:
|
|
if isinstance(value, datetime):
|
|
parsed = value
|
|
elif isinstance(value, str) and value.strip():
|
|
try:
|
|
parsed = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
|
|
except ValueError:
|
|
return None
|
|
else:
|
|
return None
|
|
if parsed.tzinfo is None:
|
|
parsed = parsed.replace(tzinfo=timezone.utc)
|
|
return parsed.astimezone(timezone.utc)
|
|
|
|
|
|
def _to_iso(value: object) -> str:
|
|
parsed = _parse_datetime(value)
|
|
if parsed is None:
|
|
parsed = datetime.now(timezone.utc)
|
|
return parsed.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
|
|
|
|
|
|
def _json_default(value: object) -> str:
|
|
if isinstance(value, datetime):
|
|
return _to_iso(value)
|
|
if isinstance(value, date):
|
|
return value.isoformat()
|
|
raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
|
|
|
|
|
|
def _main(argv: list[str] | None = None) -> int:
|
|
parser = argparse.ArgumentParser(
|
|
description="Read and generate weekly/monthly ranking snapshots.",
|
|
)
|
|
subparsers = parser.add_subparsers(dest="command")
|
|
generate_parser = subparsers.add_parser("generate-ranking-snapshot")
|
|
generate_parser.add_argument(
|
|
"--timeframe",
|
|
required=True,
|
|
choices=SNAPSHOT_GENERATOR_TIMEFRAMES,
|
|
)
|
|
generate_parser.add_argument("--server-key", default=None)
|
|
generate_parser.add_argument(
|
|
"--metric",
|
|
required=True,
|
|
choices=SNAPSHOT_GENERATOR_METRICS,
|
|
)
|
|
generate_parser.add_argument("--limit", type=int, default=20)
|
|
generate_parser.add_argument(
|
|
"--sqlite-path",
|
|
type=Path,
|
|
default=None,
|
|
help="explicit local SQLite override; default operational mode uses PostgreSQL when configured",
|
|
)
|
|
generate_parser.add_argument(
|
|
"--no-replace-existing",
|
|
action="store_false",
|
|
dest="replace_existing",
|
|
help="keep an existing snapshot for the selected exact window and metric scope",
|
|
)
|
|
refresh_parser = subparsers.add_parser("refresh-ranking-snapshots")
|
|
refresh_parser.add_argument(
|
|
"--limit",
|
|
type=int,
|
|
default=DEFAULT_RANKING_SNAPSHOT_REFRESH_LIMIT,
|
|
)
|
|
refresh_parser.add_argument(
|
|
"--timeframe",
|
|
choices=SNAPSHOT_GENERATOR_TIMEFRAMES,
|
|
action="append",
|
|
dest="timeframes",
|
|
help="Optional timeframe filter. Repeat to refresh more than one timeframe.",
|
|
)
|
|
refresh_parser.add_argument(
|
|
"--sqlite-path",
|
|
type=Path,
|
|
default=None,
|
|
help="explicit local SQLite override; default operational mode uses PostgreSQL when configured",
|
|
)
|
|
refresh_parser.add_argument(
|
|
"--no-replace-existing",
|
|
action="store_false",
|
|
dest="replace_existing",
|
|
help="keep an existing snapshot for the selected exact window and metric scope",
|
|
)
|
|
parser.set_defaults(replace_existing=True)
|
|
args = parser.parse_args(argv)
|
|
|
|
if args.command == "generate-ranking-snapshot":
|
|
payload = generate_ranking_snapshot(
|
|
timeframe=args.timeframe,
|
|
server_key=args.server_key,
|
|
metric=args.metric,
|
|
limit=args.limit,
|
|
replace_existing=args.replace_existing,
|
|
db_path=args.sqlite_path,
|
|
)
|
|
print(
|
|
json.dumps(
|
|
{"status": "ok", "data": payload},
|
|
ensure_ascii=True,
|
|
indent=2,
|
|
default=_json_default,
|
|
)
|
|
)
|
|
return 0
|
|
|
|
if args.command == "refresh-ranking-snapshots":
|
|
payload = refresh_ranking_snapshots(
|
|
limit=args.limit,
|
|
replace_existing=args.replace_existing,
|
|
timeframes=tuple(args.timeframes) if args.timeframes else None,
|
|
db_path=args.sqlite_path,
|
|
)
|
|
print(
|
|
json.dumps(
|
|
{"status": "ok", "data": payload},
|
|
ensure_ascii=True,
|
|
indent=2,
|
|
default=_json_default,
|
|
)
|
|
)
|
|
return 0
|
|
|
|
parser.print_help()
|
|
return 2
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(_main())
|