Add historical UI and backend API slice

backend/app/config.py

@@ -12,6 +12,9 @@ DEFAULT_STORAGE_FILENAME = "hll_vietnam_dev.sqlite3"
 DEFAULT_REFRESH_INTERVAL_SECONDS = 120
 DEFAULT_HISTORICAL_CRCON_PAGE_SIZE = 50
 DEFAULT_HISTORICAL_CRCON_TIMEOUT_SECONDS = 15.0
+DEFAULT_HISTORICAL_REFRESH_INTERVAL_SECONDS = 1800
+DEFAULT_HISTORICAL_REFRESH_MAX_RETRIES = 2
+DEFAULT_HISTORICAL_REFRESH_RETRY_DELAY_SECONDS = 30
 DEFAULT_ALLOWED_ORIGINS = (
     "null",
     "http://127.0.0.1:5500",
@@ -95,6 +98,47 @@ def get_historical_crcon_request_timeout_seconds() -> float:
     return timeout_seconds
 
 
+def get_historical_refresh_interval_seconds() -> int:
+    """Return the default interval used by the historical refresh loop."""
+    configured_value = os.getenv(
+        "HLL_HISTORICAL_REFRESH_INTERVAL_SECONDS",
+        str(DEFAULT_HISTORICAL_REFRESH_INTERVAL_SECONDS),
+    )
+    interval_seconds = int(configured_value)
+    if interval_seconds <= 0:
+        raise ValueError("HLL_HISTORICAL_REFRESH_INTERVAL_SECONDS must be positive.")
+
+    return interval_seconds
+
+
+def get_historical_refresh_max_retries() -> int:
+    """Return the retry count used by the historical refresh loop."""
+    configured_value = os.getenv(
+        "HLL_HISTORICAL_REFRESH_MAX_RETRIES",
+        str(DEFAULT_HISTORICAL_REFRESH_MAX_RETRIES),
+    )
+    max_retries = int(configured_value)
+    if max_retries < 0:
+        raise ValueError("HLL_HISTORICAL_REFRESH_MAX_RETRIES must be zero or positive.")
+
+    return max_retries
+
+
+def get_historical_refresh_retry_delay_seconds() -> int:
+    """Return the wait time between historical refresh retries."""
+    configured_value = os.getenv(
+        "HLL_HISTORICAL_REFRESH_RETRY_DELAY_SECONDS",
+        str(DEFAULT_HISTORICAL_REFRESH_RETRY_DELAY_SECONDS),
+    )
+    retry_delay_seconds = int(configured_value)
+    if retry_delay_seconds < 0:
+        raise ValueError(
+            "HLL_HISTORICAL_REFRESH_RETRY_DELAY_SECONDS must be zero or positive."
+        )
+
+    return retry_delay_seconds
+
+
 def get_a2s_targets_payload() -> str | None:
     """Return the optional JSON payload that overrides local A2S targets."""
     raw_payload = os.getenv(DEFAULT_A2S_TARGETS_ENV_VAR)

backend/app/historical_runner.py

@@ -0,0 +1,160 @@
+"""Local development loop for periodic historical CRCON refreshes."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import time
+from typing import Any
+
+from .config import (
+    get_historical_refresh_interval_seconds,
+    get_historical_refresh_max_retries,
+    get_historical_refresh_retry_delay_seconds,
+)
+from .historical_ingestion import run_incremental_refresh
+
+
+def run_periodic_historical_refresh(
+    *,
+    interval_seconds: int,
+    max_retries: int,
+    retry_delay_seconds: int,
+    server_slug: str | None = None,
+    max_pages: int | None = None,
+    page_size: int | None = None,
+    max_runs: int | None = None,
+) -> None:
+    """Run periodic historical refreshes until interrupted or the limit is reached."""
+    completed_runs = 0
+    print(
+        "Starting historical refresh loop "
+        f"(interval={interval_seconds}s, retries={max_retries}, server={server_slug or 'all'})."
+    )
+    print("Press Ctrl+C to stop.")
+
+    try:
+        while max_runs is None or completed_runs < max_runs:
+            completed_runs += 1
+            payload = _run_refresh_with_retries(
+                max_retries=max_retries,
+                retry_delay_seconds=retry_delay_seconds,
+                server_slug=server_slug,
+                max_pages=max_pages,
+                page_size=page_size,
+            )
+            print(json.dumps({"run": completed_runs, **payload}, indent=2))
+
+            if max_runs is not None and completed_runs >= max_runs:
+                break
+
+            time.sleep(interval_seconds)
+    except KeyboardInterrupt:
+        print("\nHistorical refresh loop stopped by user.")
+
+
+def _run_refresh_with_retries(
+    *,
+    max_retries: int,
+    retry_delay_seconds: int,
+    server_slug: str | None,
+    max_pages: int | None,
+    page_size: int | None,
+) -> dict[str, Any]:
+    attempt = 0
+    while True:
+        attempt += 1
+        try:
+            result = run_incremental_refresh(
+                server_slug=server_slug,
+                max_pages=max_pages,
+                page_size=page_size,
+            )
+            return {
+                "status": "ok",
+                "attempts_used": attempt,
+                "max_retries": max_retries,
+                "result": result,
+            }
+        except Exception as exc:
+            if attempt > max_retries:
+                return {
+                    "status": "error",
+                    "attempts_used": attempt,
+                    "max_retries": max_retries,
+                    "error": str(exc),
+                }
+            if retry_delay_seconds > 0:
+                time.sleep(retry_delay_seconds)
+
+
+def main() -> None:
+    """Allow local scheduled historical refresh execution without external infra."""
+    parser = argparse.ArgumentParser(
+        description="Run periodic historical CRCON refreshes for HLL Vietnam.",
+    )
+    parser.add_argument(
+        "--interval",
+        type=int,
+        default=get_historical_refresh_interval_seconds(),
+        help="Seconds to wait between incremental refresh runs.",
+    )
+    parser.add_argument(
+        "--retries",
+        type=int,
+        default=get_historical_refresh_max_retries(),
+        help="Retry attempts after a failed incremental refresh.",
+    )
+    parser.add_argument(
+        "--retry-delay",
+        type=int,
+        default=get_historical_refresh_retry_delay_seconds(),
+        help="Seconds to wait between failed attempts.",
+    )
+    parser.add_argument(
+        "--server",
+        dest="server_slug",
+        help="Optional historical server slug.",
+    )
+    parser.add_argument(
+        "--max-pages",
+        type=int,
+        default=None,
+        help="Optional page cap for local validation.",
+    )
+    parser.add_argument(
+        "--page-size",
+        type=int,
+        default=None,
+        help="Optional override for CRCON page size.",
+    )
+    parser.add_argument(
+        "--max-runs",
+        type=int,
+        default=None,
+        help="Optional safety limit for the number of refresh cycles to execute.",
+    )
+    args = parser.parse_args()
+
+    if args.interval <= 0:
+        raise ValueError("--interval must be a positive integer.")
+    if args.retries < 0:
+        raise ValueError("--retries must be zero or positive.")
+    if args.retry_delay < 0:
+        raise ValueError("--retry-delay must be zero or positive.")
+    if args.max_runs is not None and args.max_runs <= 0:
+        raise ValueError("--max-runs must be positive when provided.")
+
+    run_periodic_historical_refresh(
+        interval_seconds=args.interval,
+        max_retries=args.retries,
+        retry_delay_seconds=args.retry_delay,
+        server_slug=args.server_slug,
+        max_pages=args.max_pages,
+        page_size=args.page_size,
+        max_runs=args.max_runs,
+    )
+
+
+if __name__ == "__main__":
+    main()

backend/app/historical_storage.py

@@ -439,7 +439,7 @@ def list_recent_historical_matches(
     limit: int = 20,
     db_path: Path | None = None,
 ) -> list[dict[str, object]]:
-    """Return recent persisted matches for validation and later API work."""
+    """Return recent persisted matches grouped for the historical API layer."""
     resolved_path = initialize_historical_storage(db_path=db_path)
     where_clause = ""
     params: list[object] = []
@@ -474,7 +474,217 @@ def list_recent_historical_matches(
             """,
             params,
         ).fetchall()
-    return [dict(row) for row in rows]
+    items: list[dict[str, object]] = []
+    for row in rows:
+        items.append(
+            {
+                "server": {
+                    "slug": row["server_slug"],
+                    "name": row["server_name"],
+                },
+                "match_id": row["external_match_id"],
+                "started_at": row["started_at"],
+                "ended_at": row["ended_at"],
+                "closed_at": row["ended_at"] or row["started_at"],
+                "map": {
+                    "name": row["map_name"],
+                    "pretty_name": row["map_pretty_name"] or row["map_name"],
+                },
+                "result": {
+                    "allied_score": _coerce_int(row["allied_score"]),
+                    "axis_score": _coerce_int(row["axis_score"]),
+                    "winner": _resolve_match_winner(
+                        row["allied_score"],
+                        row["axis_score"],
+                    ),
+                },
+                "player_count": int(row["player_count"] or 0),
+            }
+        )
+    return items
+
+
+def list_historical_server_summaries(
+    *,
+    server_slug: str | None = None,
+    db_path: Path | None = None,
+) -> list[dict[str, object]]:
+    """Return aggregate historical metrics per server."""
+    resolved_path = initialize_historical_storage(db_path=db_path)
+    where_clause = ""
+    params: list[object] = []
+    if server_slug:
+        where_clause = "WHERE historical_servers.slug = ?"
+        params.append(server_slug)
+
+    with _connect(resolved_path) as connection:
+        summary_rows = connection.execute(
+            f"""
+            SELECT
+                historical_servers.slug AS server_slug,
+                historical_servers.display_name AS server_name,
+                COUNT(DISTINCT historical_matches.id) AS matches_count,
+                COUNT(DISTINCT historical_players.id) AS unique_players,
+                COALESCE(SUM(historical_player_match_stats.kills), 0) AS total_kills,
+                COUNT(DISTINCT COALESCE(historical_matches.map_pretty_name, historical_matches.map_name)) AS map_count,
+                MIN(COALESCE(historical_matches.ended_at, historical_matches.started_at, historical_matches.created_at_source)) AS first_match_at,
+                MAX(COALESCE(historical_matches.ended_at, historical_matches.started_at, historical_matches.created_at_source)) AS last_match_at
+            FROM historical_servers
+            LEFT JOIN historical_matches
+                ON historical_matches.historical_server_id = historical_servers.id
+            LEFT JOIN historical_player_match_stats
+                ON historical_player_match_stats.historical_match_id = historical_matches.id
+            LEFT JOIN historical_players
+                ON historical_players.id = historical_player_match_stats.historical_player_id
+            {where_clause}
+            GROUP BY historical_servers.id
+            ORDER BY historical_servers.server_number ASC, historical_servers.slug ASC
+            """,
+            params,
+        ).fetchall()
+
+        map_rows = connection.execute(
+            f"""
+            SELECT
+                historical_servers.slug AS server_slug,
+                COALESCE(historical_matches.map_pretty_name, historical_matches.map_name, 'Mapa no disponible') AS map_name,
+                COUNT(*) AS matches_count
+            FROM historical_matches
+            INNER JOIN historical_servers
+                ON historical_servers.id = historical_matches.historical_server_id
+            {where_clause}
+            GROUP BY historical_servers.slug, COALESCE(historical_matches.map_pretty_name, historical_matches.map_name, 'Mapa no disponible')
+            ORDER BY historical_servers.slug ASC, matches_count DESC, map_name ASC
+            """,
+            params,
+        ).fetchall()
+
+    top_maps_by_server: dict[str, list[dict[str, object]]] = {}
+    for row in map_rows:
+        server_key = str(row["server_slug"])
+        top_maps_by_server.setdefault(server_key, [])
+        if len(top_maps_by_server[server_key]) >= 3:
+            continue
+        top_maps_by_server[server_key].append(
+            {
+                "map_name": row["map_name"],
+                "matches_count": int(row["matches_count"] or 0),
+            }
+        )
+
+    items: list[dict[str, object]] = []
+    for row in summary_rows:
+        items.append(
+            {
+                "server": {
+                    "slug": row["server_slug"],
+                    "name": row["server_name"],
+                },
+                "matches_count": int(row["matches_count"] or 0),
+                "unique_players": int(row["unique_players"] or 0),
+                "total_kills": int(row["total_kills"] or 0),
+                "map_count": int(row["map_count"] or 0),
+                "top_maps": top_maps_by_server.get(str(row["server_slug"]), []),
+                "time_range": {
+                    "start": row["first_match_at"],
+                    "end": row["last_match_at"],
+                },
+            }
+        )
+    return items
+
+
+def get_historical_player_profile(
+    player_id: str,
+    *,
+    db_path: Path | None = None,
+) -> dict[str, object] | None:
+    """Return aggregate historical metrics for one player identity."""
+    resolved_player_id = player_id.strip()
+    if not resolved_player_id:
+        return None
+
+    resolved_path = initialize_historical_storage(db_path=db_path)
+    with _connect(resolved_path) as connection:
+        player_row = connection.execute(
+            """
+            SELECT
+                historical_players.id,
+                historical_players.stable_player_key,
+                historical_players.display_name,
+                historical_players.steam_id,
+                historical_players.source_player_id,
+                COUNT(DISTINCT historical_matches.id) AS matches_count,
+                COALESCE(SUM(historical_player_match_stats.kills), 0) AS total_kills,
+                MIN(COALESCE(historical_matches.ended_at, historical_matches.started_at, historical_matches.created_at_source)) AS first_match_at,
+                MAX(COALESCE(historical_matches.ended_at, historical_matches.started_at, historical_matches.created_at_source)) AS last_match_at
+            FROM historical_players
+            LEFT JOIN historical_player_match_stats
+                ON historical_player_match_stats.historical_player_id = historical_players.id
+            LEFT JOIN historical_matches
+                ON historical_matches.id = historical_player_match_stats.historical_match_id
+            WHERE historical_players.stable_player_key = ?
+               OR historical_players.steam_id = ?
+               OR historical_players.source_player_id = ?
+            GROUP BY historical_players.id
+            ORDER BY historical_players.display_name ASC
+            LIMIT 1
+            """,
+            (resolved_player_id, resolved_player_id, resolved_player_id),
+        ).fetchone()
+        if player_row is None:
+            return None
+
+        server_rows = connection.execute(
+            """
+            SELECT
+                historical_servers.slug AS server_slug,
+                historical_servers.display_name AS server_name,
+                COUNT(DISTINCT historical_matches.id) AS matches_count,
+                COALESCE(SUM(historical_player_match_stats.kills), 0) AS total_kills,
+                MIN(COALESCE(historical_matches.ended_at, historical_matches.started_at, historical_matches.created_at_source)) AS first_match_at,
+                MAX(COALESCE(historical_matches.ended_at, historical_matches.started_at, historical_matches.created_at_source)) AS last_match_at
+            FROM historical_player_match_stats
+            INNER JOIN historical_matches
+                ON historical_matches.id = historical_player_match_stats.historical_match_id
+            INNER JOIN historical_servers
+                ON historical_servers.id = historical_matches.historical_server_id
+            WHERE historical_player_match_stats.historical_player_id = ?
+            GROUP BY historical_servers.id
+            ORDER BY total_kills DESC, historical_servers.server_number ASC, historical_servers.slug ASC
+            """,
+            (player_row["id"],),
+        ).fetchall()
+
+    return {
+        "player": {
+            "stable_player_key": player_row["stable_player_key"],
+            "name": player_row["display_name"],
+            "steam_id": player_row["steam_id"],
+            "source_player_id": player_row["source_player_id"],
+        },
+        "matches_count": int(player_row["matches_count"] or 0),
+        "total_kills": int(player_row["total_kills"] or 0),
+        "time_range": {
+            "start": player_row["first_match_at"],
+            "end": player_row["last_match_at"],
+        },
+        "servers": [
+            {
+                "server": {
+                    "slug": row["server_slug"],
+                    "name": row["server_name"],
+                },
+                "matches_count": int(row["matches_count"] or 0),
+                "total_kills": int(row["total_kills"] or 0),
+                "time_range": {
+                    "start": row["first_match_at"],
+                    "end": row["last_match_at"],
+                },
+            }
+            for row in server_rows
+        ],
+    }
 
 
 def list_weekly_top_kills(
@@ -578,6 +788,18 @@ def _connect(db_path: Path) -> sqlite3.Connection:
     return connection
 
 
+def _resolve_match_winner(allied_score: object, axis_score: object) -> str | None:
+    allied = _coerce_int(allied_score)
+    axis = _coerce_int(axis_score)
+    if allied is None or axis is None:
+        return None
+    if allied > axis:
+        return "allies"
+    if axis > allied:
+        return "axis"
+    return "draw"
+
+
 def _has_legacy_historical_schema(connection: sqlite3.Connection) -> bool:
     columns = {
         str(row["name"])

backend/app/payloads.py

@@ -6,7 +6,12 @@ from datetime import datetime, timezone
 
 from .collector import collect_server_snapshots
 from .config import get_refresh_interval_seconds
-from .historical_storage import list_weekly_top_kills
+from .historical_storage import (
+    get_historical_player_profile,
+    list_historical_server_summaries,
+    list_recent_historical_matches,
+    list_weekly_top_kills,
+)
 from .normalizers import normalize_map_name
 from .server_targets import load_a2s_targets
 from .storage import list_latest_snapshots, list_server_history, list_snapshot_history
@@ -205,6 +210,60 @@ def build_weekly_top_kills_payload(
     }
 
 
+def build_recent_historical_matches_payload(
+    *,
+    limit: int = 20,
+    server_slug: str | None = None,
+) -> dict[str, object]:
+    """Return recent historical matches from persisted CRCON data."""
+    items = list_recent_historical_matches(limit=limit, server_slug=server_slug)
+    return {
+        "status": "ok",
+        "data": {
+            "title": "Partidas recientes por servidor",
+            "context": "historical-recent-matches",
+            "source": "historical-crcon-storage",
+            "limit": limit,
+            "server_slug": server_slug,
+            "items": items,
+        },
+    }
+
+
+def build_historical_server_summary_payload(
+    *,
+    server_slug: str | None = None,
+) -> dict[str, object]:
+    """Return aggregated historical metrics per server."""
+    items = list_historical_server_summaries(server_slug=server_slug)
+    return {
+        "status": "ok",
+        "data": {
+            "title": "Resumen historico por servidor",
+            "context": "historical-server-summary",
+            "source": "historical-crcon-storage",
+            "server_slug": server_slug,
+            "items": items,
+        },
+    }
+
+
+def build_historical_player_profile_payload(player_id: str) -> dict[str, object]:
+    """Return aggregate historical metrics for one player identity."""
+    profile = get_historical_player_profile(player_id)
+    return {
+        "status": "ok",
+        "data": {
+            "title": "Perfil historico de jugador",
+            "context": "historical-player-profile",
+            "source": "historical-crcon-storage",
+            "player_id": player_id,
+            "found": profile is not None,
+            "profile": profile,
+        },
+    }
+
+
 def _enrich_server_items(items: list[dict[str, object]]) -> list[dict[str, object]]:
     target_index = {
         target.external_server_id: target

backend/app/routes.py

@@ -10,6 +10,9 @@ from .payloads import (
     build_discord_payload,
     build_error_payload,
     build_health_payload,
+    build_historical_player_profile_payload,
+    build_historical_server_summary_payload,
+    build_recent_historical_matches_payload,
     build_server_detail_history_payload,
     build_server_history_payload,
     build_server_latest_payload,
@@ -47,6 +50,26 @@ def resolve_get_payload(path: str) -> tuple[HTTPStatus | None, dict[str, object]
         server_id = parse_qs(parsed.query).get("server", [None])[0]
         return HTTPStatus.OK, build_weekly_top_kills_payload(limit=limit, server_id=server_id)
 
+    if parsed.path == "/api/historical/recent-matches":
+        limit = _parse_limit(parsed.query)
+        if limit is None:
+            return HTTPStatus.BAD_REQUEST, build_error_payload("Invalid limit parameter")
+        server_slug = parse_qs(parsed.query).get("server", [None])[0]
+        return HTTPStatus.OK, build_recent_historical_matches_payload(
+            limit=limit,
+            server_slug=server_slug,
+        )
+
+    if parsed.path == "/api/historical/server-summary":
+        server_slug = parse_qs(parsed.query).get("server", [None])[0]
+        return HTTPStatus.OK, build_historical_server_summary_payload(server_slug=server_slug)
+
+    if parsed.path == "/api/historical/player-profile":
+        player_id = parse_qs(parsed.query).get("player", [None])[0]
+        if not player_id:
+            return HTTPStatus.BAD_REQUEST, build_error_payload("Player parameter is required")
+        return HTTPStatus.OK, build_historical_player_profile_payload(player_id)
+
     builder = GET_ROUTES.get(parsed.path)
     if builder is None:
         if parsed.path.startswith("/api/servers/") and parsed.path.endswith("/history"):