111 lines
3.1 KiB
Markdown
111 lines
3.1 KiB
Markdown
---
|
|
id: TASK-181-add-global-ranking-backend-support
|
|
title: Add global ranking backend support
|
|
status: done
|
|
type: backend
|
|
team: Backend Senior
|
|
supporting_teams:
|
|
- Arquitecto Python
|
|
- Arquitecto de Base de Datos
|
|
roadmap_item: foundation
|
|
priority: 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`
|