Complete TASK-054 snapshot prewarm policy

backend/app/historical_snapshots.py

@@ -33,6 +33,13 @@ SUPPORTED_LEADERBOARD_METRICS = frozenset(
         "matches_over_100_kills",
     }
 )
+PREWARM_SNAPSHOT_SERVER_KEYS = (
+    "comunidad-hispana-01",
+    "comunidad-hispana-02",
+    "comunidad-hispana-03",
+    ALL_SERVERS_SLUG,
+)
+PREWARM_LEADERBOARD_METRICS = ("kills",)
 SNAPSHOT_LEADERBOARD_METRICS = (
     "kills",
     "deaths",
@@ -109,6 +116,42 @@ def build_historical_server_snapshots(
     return snapshots
 
 
+def build_priority_historical_snapshots(
+    *,
+    server_keys: tuple[str, ...] = PREWARM_SNAPSHOT_SERVER_KEYS,
+    generated_at: datetime | None = None,
+    leaderboard_limit: int = DEFAULT_WEEKLY_LEADERBOARD_LIMIT,
+    recent_matches_limit: int = DEFAULT_RECENT_MATCHES_LIMIT,
+    db_path: Path | None = None,
+) -> list[dict[str, object]]:
+    """Build the minimum warm snapshot set required by the historical UI."""
+    generated_at_value = _as_utc(generated_at or datetime.now(timezone.utc))
+    snapshots: list[dict[str, object]] = []
+    for server_key in server_keys:
+        snapshots.append(
+            _build_server_summary_snapshot(server_key, generated_at_value, db_path=db_path)
+        )
+        for metric in PREWARM_LEADERBOARD_METRICS:
+            snapshots.append(
+                _build_weekly_leaderboard_snapshot(
+                    server_key,
+                    metric,
+                    generated_at_value,
+                    limit=leaderboard_limit,
+                    db_path=db_path,
+                )
+            )
+        snapshots.append(
+            _build_recent_matches_snapshot(
+                server_key,
+                generated_at_value,
+                limit=recent_matches_limit,
+                db_path=db_path,
+            )
+        )
+    return snapshots
+
+
 def build_all_historical_snapshots(
     *,
     server_key: str | None = None,
@@ -129,7 +172,7 @@ def build_all_historical_snapshots(
                 recent_matches_limit=recent_matches_limit,
                 db_path=db_path,
             )
-    )
+        )
     return snapshots
 
 
@@ -161,6 +204,42 @@ def generate_and_persist_historical_snapshots(
     return {
         "generated_at": _to_iso(generated_at_value),
         "server_slug": server_key,
+        "snapshot_policy": "full-matrix",
+        "snapshot_count": len(persisted_records),
+        "servers_processed": len(snapshots_by_server),
+        "snapshots_by_server": snapshots_by_server,
+    }
+
+
+def generate_and_persist_priority_historical_snapshots(
+    *,
+    generated_at: datetime | None = None,
+    leaderboard_limit: int = DEFAULT_WEEKLY_LEADERBOARD_LIMIT,
+    recent_matches_limit: int = DEFAULT_RECENT_MATCHES_LIMIT,
+    db_path: Path | None = None,
+) -> dict[str, object]:
+    """Build and persist the priority snapshot set used for prewarm."""
+    from .historical_snapshot_storage import persist_historical_snapshot_batch
+
+    generated_at_value = _as_utc(generated_at or datetime.now(timezone.utc))
+    snapshots = build_priority_historical_snapshots(
+        generated_at=generated_at_value,
+        leaderboard_limit=leaderboard_limit,
+        recent_matches_limit=recent_matches_limit,
+        db_path=db_path,
+    )
+    persisted_records = persist_historical_snapshot_batch(snapshots, db_path=db_path)
+    snapshots_by_server: dict[str, int] = {}
+    for record in persisted_records:
+        snapshots_by_server.setdefault(record.server_key, 0)
+        snapshots_by_server[record.server_key] += 1
+
+    return {
+        "generated_at": _to_iso(generated_at_value),
+        "server_slug": None,
+        "snapshot_policy": "priority-prewarm",
+        "prewarm_server_keys": list(PREWARM_SNAPSHOT_SERVER_KEYS),
+        "prewarm_metrics": list(PREWARM_LEADERBOARD_METRICS),
         "snapshot_count": len(persisted_records),
         "servers_processed": len(snapshots_by_server),
         "snapshots_by_server": snapshots_by_server,