Add weekly monthly ranking snapshot generator

ai/tasks/done/TASK-194-add-weekly-monthly-ranking-snapshot-generator.md

@@ -0,0 +1,149 @@
+---
+id: TASK-194-add-weekly-monthly-ranking-snapshot-generator
+title: Add weekly monthly ranking snapshot generator
+status: done
+type: backend
+team: Backend Senior
+supporting_teams:
+  - Arquitecto de Base de Datos
+  - Arquitecto Python
+roadmap_item: foundation
+priority: high
+---
+
+# TASK-194 - Add weekly monthly ranking snapshot generator
+
+## Goal
+
+Implement a manual weekly/monthly ranking snapshot generator plus CLI so PostgreSQL-backed `/api/ranking` can serve persisted global ranking snapshots instead of runtime fallback when operators generate the required combinations.
+
+## Context
+
+`TASK-191` introduced the snapshot-first read path for weekly/monthly global ranking, and `TASK-192` / `TASK-193` stabilized the PostgreSQL path and runtime fallback metrics. The missing piece is still out-of-band generation for `ranking_snapshots` and `ranking_snapshot_items`, so production ranking requests continue to return `snapshot_status=missing`, `freshness=runtime` and `fallback_used=true`.
+
+Preserve the current product identity: Spanish-speaking HLL Vietnam community, military/Vietnam/tactical/sober visual direction and controlled repository evolution.
+
+## Steps
+
+1. Read the listed files first.
+2. Add a manual generator for weekly/monthly ranking snapshots using the existing materialized RCON leaderboard logic and snapshot tables.
+3. Expose a CLI command for one explicit combination; only add matrix generation if it remains small and justified.
+4. Validate generated snapshot reads, preserved runtime fallback behavior and production-oriented run commands.
+5. Document the manual generation workflow and recommended combinations.
+
+## Files to Read First
+
+- `AGENTS.md`
+- `ai/repo-context.md`
+- `ai/architecture-index.md`
+- `backend/app/rcon_historical_leaderboards.py`
+- `backend/app/rcon_annual_rankings.py`
+- `backend/app/routes.py`
+- `backend/app/payloads.py`
+- `backend/app/postgres_rcon_storage.py`
+- `scripts/run-stats-validation.ps1`
+- `docs/ranking-snapshot-read-model-plan.md`
+- `docs/ranking-stats-performance-audit.md`
+- `ai/tasks/done/TASK-191-serve-ranking-from-snapshots-with-runtime-fallback.md`
+- `ai/tasks/done/TASK-192-fix-postgres-ranking-snapshot-schema.md`
+- `ai/tasks/done/TASK-193-fix-postgres-ranking-derived-metrics.md`
+
+## Expected Files to Modify
+
+- `backend/app/rcon_historical_leaderboards.py`
+- `scripts/run-stats-validation.ps1`
+- `docs/ranking-snapshot-read-model-plan.md`
+- `ai/tasks/done/TASK-194-add-weekly-monthly-ranking-snapshot-generator.md`
+
+## Constraints
+
+- Keep the change minimal.
+- Do not modify frontend, assets or design.
+- Do not reactivate Elo/MMR.
+- Do not reintroduce Comunidad Hispana #03.
+- Keep annual ranking behavior unchanged unless a helper can be safely shared without changing annual contracts.
+- Prefer the existing module pattern already used by `backend/app/rcon_annual_rankings.py`.
+- Do not change `/api/ranking` unless strictly necessary for validation-safe compatibility.
+- Keep PostgreSQL as the operational target and preserve SQLite compatibility already present in the shared backend path.
+
+## Validation
+
+Before completing the task ensure:
+
+- `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
+- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
+- local import validation proves:
+  - `generate_ranking_snapshot(timeframe="weekly", server_key="all", metric="kills", limit=20)` creates a snapshot
+  - `get_latest_ranking_snapshot(...)` can read that snapshot
+  - `/api/ranking?timeframe=weekly&server_id=all&metric=kills&limit=20` returns `snapshot_status=ready`
+  - the same response returns `fallback_used=false`
+  - requesting a combination without a snapshot still preserves runtime fallback when enabled
+- document the manual CLI command for local and Docker execution
+- `git diff --name-only` matches the expected scope
+
+## Outcome
+
+Implemented:
+
+- `backend/app/rcon_historical_leaderboards.py`
+  - `generate_ranking_snapshot(...)`
+  - persistence helpers for `ranking_snapshots` and `ranking_snapshot_items`
+  - manual CLI entrypoint:
+    - `python -m app.rcon_historical_leaderboards generate-ranking-snapshot --timeframe weekly --server-key all --metric kills --limit 20`
+- `scripts/run-stats-validation.ps1`
+  - now validates a real generated weekly snapshot through:
+    - direct function import
+    - `get_latest_ranking_snapshot(...)`
+    - `/api/ranking`
+  - confirms generated snapshot reads return:
+    - `snapshot_status=ready`
+    - `fallback_used=false`
+  - confirms runtime fallback still works for a missing combination
+- `docs/ranking-snapshot-read-model-plan.md`
+  - documents the manual command
+  - documents the recommended weekly/monthly/server/metric matrix
+  - documents suggested refresh cadence
+  - documents the expected `ready` vs fallback response states
+
+Supported generation scope:
+
+- `timeframe`
+  - `weekly`
+  - `monthly`
+- `server-key`
+  - `all`
+  - `all-servers`
+  - `comunidad-hispana-01`
+  - `comunidad-hispana-02`
+- `metric`
+  - `kills`
+  - `deaths`
+  - `teamkills`
+  - `matches_considered`
+  - `kd_ratio`
+  - `kills_per_match`
+
+Validations executed:
+
+- `python -m compileall backend/app/rcon_historical_leaderboards.py backend/app/payloads.py backend/app/routes.py backend/app/postgres_rcon_storage.py`
+- direct local import probe for `generate_ranking_snapshot(...)`
+- `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
+- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
+- local CLI probe:
+  - `python -m app.rcon_historical_leaderboards generate-ranking-snapshot --timeframe weekly --server-key all --metric kills --limit 20`
+
+Validation notes:
+
+- Live backend HTTP at `http://127.0.0.1:8000` was not available, so route validation completed through local imports and repository scripts.
+- The manual CLI is unitary per `(timeframe, server-key, metric)` combination.
+- A broader matrix helper was intentionally left out to keep the task small and verifiable.
+
+Recommended Docker command for production:
+
+- `docker compose exec backend python -m app.rcon_historical_leaderboards generate-ranking-snapshot --timeframe weekly --server-key all --metric kills --limit 20`
+
+## Change Budget
+
+- Prefer fewer than 5 modified files.
+- Prefer changes under 200 lines when feasible.
+- Split the work into follow-up tasks if limits are exceeded.