Add hourly historical refresh runner workflow

backend/README.md

@@ -756,10 +756,27 @@ 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 de los tres servidores del
+proyecto en local, el comando recomendado es:
+
+```powershell
+python -m app.historical_runner --hourly
+```
+
+Sin `--server`, ese runner refresca:
+
+- `comunidad-hispana-01`
+- `comunidad-hispana-02`
+- `comunidad-hispana-03`
+
+Despues de cada refresh correcto, recompone snapshots para los servidores
+afectados y vuelve a alinear el agregado `all-servers`.
+
 Para regenerar snapshots de forma puntual dentro del contenedor sin dejar un
 bucle permanente, la validacion operativa minima es:
 
@@ -767,6 +784,36 @@ 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-03/weekly-kills.json`
+   - `backend/data/snapshots/all-servers/monthly-kills.json`
+
+Operativa minima con Docker Compose:
+
+```powershell
+docker compose 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.
+
+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`
+
 Variables utiles del runner:
 
 - `HLL_HISTORICAL_SNAPSHOT_REFRESH_INTERVAL_SECONDS`

backend/app/historical_runner.py

@@ -20,6 +20,13 @@ from .historical_snapshots import (
     generate_and_persist_priority_historical_snapshots,
 )
 
+HOURLY_INTERVAL_SECONDS = 3600
+DEFAULT_HISTORICAL_SERVER_SCOPE = (
+    "comunidad-hispana-01",
+    "comunidad-hispana-02",
+    "comunidad-hispana-03",
+)
+
 
 def run_periodic_historical_refresh(
     *,
@@ -34,8 +41,17 @@ def run_periodic_historical_refresh(
     """Run periodic historical refreshes and rebuild persisted snapshots."""
     completed_runs = 0
     print(
-        "Starting historical refresh loop "
-        f"(interval={interval_seconds}s, retries={max_retries}, server={server_slug or 'all'})."
+        json.dumps(
+            {
+                "event": "historical-refresh-loop-started",
+                "interval_seconds": interval_seconds,
+                "max_retries": max_retries,
+                "retry_delay_seconds": retry_delay_seconds,
+                "server_scope": _describe_refresh_scope(server_slug),
+                "snapshot_scope": _describe_snapshot_scope(server_slug),
+            },
+            indent=2,
+        )
     )
     print("Press Ctrl+C to stop.")
 
@@ -129,6 +145,18 @@ def generate_historical_snapshots(
     }
 
 
+def _describe_refresh_scope(server_slug: str | None) -> list[str]:
+    if server_slug:
+        return [server_slug]
+    return list(DEFAULT_HISTORICAL_SERVER_SCOPE)
+
+
+def _describe_snapshot_scope(server_slug: str | None) -> list[str]:
+    if server_slug:
+        return [server_slug, "all-servers"]
+    return [*DEFAULT_HISTORICAL_SERVER_SCOPE, "all-servers"]
+
+
 def main() -> None:
     """Allow local scheduled historical refresh execution without external infra."""
     parser = argparse.ArgumentParser(
@@ -140,6 +168,11 @@ def main() -> None:
         default=get_historical_refresh_interval_seconds(),
         help="Seconds to wait between refresh-plus-snapshot runs.",
     )
+    parser.add_argument(
+        "--hourly",
+        action="store_true",
+        help="Shortcut for running the refresh loop every 3600 seconds.",
+    )
     parser.add_argument(
         "--retries",
         type=int,
@@ -177,6 +210,9 @@ def main() -> None:
     )
     args = parser.parse_args()
 
+    if args.hourly:
+        args.interval = HOURLY_INTERVAL_SECONDS
+
     if args.interval <= 0:
         raise ValueError("--interval must be a positive integer.")
     if args.retries < 0: