Add weekly monthly ranking snapshot generator
This commit is contained in:
devRaGonSa
@@ -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.
|
||||
Reference in New Issue
Block a user