comunidadhll/ai/tasks/done/TASK-181-add-global-ranking-backend-support.md

id, title, status, type, team, supporting_teams, roadmap_item, priority

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-181-add-global-ranking-backend-support	Add global ranking backend support	done	backend	Backend Senior	Arquitecto Python Arquitecto de Base de Datos	foundation	high

TASK-181-add-global-ranking-backend-support - Add global ranking backend support

Goal

Implement backend API support for the new global ranking page using existing RCON historical leaderboard logic and annual snapshot readers, without changing public Stats endpoints.

Context

The backend now exposes a dedicated global ranking route that supports weekly, monthly and annual modes with V1 metric scope limited to kills.

Files to Read First

• AGENTS.md
• ai/repo-context.md
• ai/architecture-index.md
• docs/global-ranking-page-plan.md
• docs/stats-section-functional-plan.md
• docs/annual-ranking-snapshot-runbook.md
• backend/app/routes.py
• backend/app/payloads.py
• backend/app/rcon_historical_leaderboards.py
• backend/app/rcon_annual_rankings.py
• scripts/run-stats-validation.ps1
• scripts/run-integration-tests.ps1

Expected Files to Modify

• backend/app/routes.py
• backend/app/payloads.py
• scripts/run-stats-validation.ps1
• ai/tasks/done/TASK-181-add-global-ranking-backend-support.md

Constraints Verified

• No new architecture was introduced.
• No migrations were added.
• Annual ranking remains snapshot-backed and is not recalculated per request.
• Stats endpoints were left compatible.
• Comunidad Hispana #03 was not exposed through the new route.
• Public scoreboard was not introduced as a primary ranking source.

Outcome

• Added GET /api/ranking.
• Added route validation for:
  • timeframe
  • metric
  • limit
  • server_id
  • required year when timeframe=annual
• Reused existing readers:
  • weekly/monthly from materialized RCON leaderboard reads
  • annual from annual snapshot storage
• Normalized the dedicated ranking response with:
  • page_kind
  • timeframe
  • server_id
  • metric
  • limit
  • requested_limit
  • effective_limit
  • window_start
  • window_end
  • snapshot_status
  • source
  • items
• Updated regression validation to cover the new route and its invalid-input cases.

Validation

Executed:

• powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1
• powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1
• Direct local route checks through resolve_get_payload(...) for:
  • weekly metric=kills
  • monthly metric=kills
  • annual metric=kills
  • annual missing year

Observed:

• Weekly route returned 200.
• Monthly route returned 200.
• Annual route returned 200.
• Annual route without year returned 400.
• Unsupported metric returned 400.
• Unsupported timeframe returned 400.
• High invalid limit returned 400.

Known limitation:

• Live HTTP verification against a running backend at http://127.0.0.1:8000 was not available during validation; route-contract checks passed through local Python imports and the integration script reported that explicitly.

Recommended Next Task

• TASK-182-add-global-ranking-frontend-page