rgonsal/comunidadhll
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add global ranking page

Browse Source
This commit is contained in:
devRaGonSa
2026-06-08 19:14:29 +02:00
parent 05d9939a23
commit dbfa28f8a4
13 changed files with 1441 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
ai/tasks/done/TASK-180-define-global-ranking-page-contract.md Normal file
View File

@@ -0,0 +1,111 @@
---
id: TASK-180-define-global-ranking-page-contract
title: Define global ranking page contract
status: done
type: documentation
team: Analista
supporting_teams:
- PM
- Backend Senior
- Frontend Senior
- Experto en interfaz
roadmap_item: foundation
priority: high
---
# TASK-180-define-global-ranking-page-contract - Define global ranking page contract
## Goal
Define a separate, explicit global ranking page contract that is clearly distinct from Stats, so product and engineering can execute backend and frontend ranking work independently.
## Context
Stats focuses on one player workflow (search and personal performance), while Ranking exposes public top lists. This task formalizes the Ranking contract, filters, payload shape and UI states needed for an incremental, RCON-first implementation.
## Steps
1. Read the listed files first.
2. Draft a concise, implementation-ready contract for Ranking.
3. Document how Ranking and Stats are separated and where they can share frontend patterns safely.
4. Define API expectations for weekly/monthly vs annual reads, including missing/ready/error behavior.
5. Keep constraints explicit.
6. Capture follow-up items and a clear next-task suggestion.
## Files to Read First
- `AGENTS.md`
- `ai/repo-context.md`
- `ai/architecture-index.md`
- `docs/stats-section-functional-plan.md`
- `docs/annual-ranking-snapshot-runbook.md`
- `backend/app/rcon_historical_leaderboards.py`
- `backend/app/rcon_annual_rankings.py`
- `frontend/stats.html`
- `frontend/assets/js/stats.js`
## Expected Files to Modify
- `docs/global-ranking-page-plan.md`
- `ai/tasks/done/TASK-180-define-global-ranking-page-contract.md`
## Constraints
- Documentation-only task.
- No backend implementation changes.
- No frontend implementation changes.
- No migrations or schema modifications.
- Keep the contract aligned with RCON-first architecture.
- No Elo/MMR reactivation.
- No reintroduction of Comunidad Hispana #03.
- No public-scoreboard as primary source when RCON coverage is available.
## Validation
- Confirm `docs/global-ranking-page-plan.md` exists.
- Confirm no backend/frontend files were modified.
- Run `git diff --name-only` within task scope.
- Document explicitly that no automated tests apply.
## Outcome
- Created `docs/global-ranking-page-plan.md`.
- Documented a dedicated `Ranking` page contract separate from `Stats`.
- Defined dedicated endpoint direction as `GET /api/ranking`.
- Documented timeframe behavior:
- weekly/monthly from RCON materialized leaderboard reads
- annual from persisted annual snapshots
- Documented required payload fields:
- `ranking_position`
- `player_id`
- `player_name`
- `metric_value`
- `matches_considered`
- `kills`
- `deaths`
- `teamkills`
- `kd_ratio`
- `window_start`
- `window_end`
- `snapshot_status`
- Documented required UI states:
- loading
- backend offline
- no data
- annual snapshot missing
- unsupported metric
- controlled error
- Explicitly preserved constraints:
- no Elo/MMR
- no Comunidad Hispana #03
- no public-scoreboard primary path while RCON exists
Validation performed:
- Confirmed documentation file creation.
- Kept changes out of `backend/` and `frontend/`.
- Automated tests do not apply to this documentation-only task.
Recommended next task:
- `TASK-181-add-global-ranking-backend-support`

110
ai/tasks/done/TASK-181-add-global-ranking-backend-support.md Normal file
View File

@@ -0,0 +1,110 @@
---
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`

99
ai/tasks/done/TASK-182-add-global-ranking-frontend-page.md Normal file
View File

@@ -0,0 +1,99 @@
---
id: TASK-182-add-global-ranking-frontend-page
title: Add global ranking frontend page
status: done
type: frontend
team: Frontend Senior
supporting_teams:
- Experto en interfaz
- Disenador grafico
- Backend Senior
roadmap_item: foundation
priority: high
---
# TASK-182-add-global-ranking-frontend-page - Add global ranking frontend page
## Goal
Create a dedicated Ranking page that displays public top lists by timeframe, server, metric and limit, consuming the backend support built in TASK-181.
## Context
Ranking is now separated from Stats in both navigation and interaction model. Stats remains player-centric; Ranking is list-centric and links back to Stats only when a user wants individual lookup.
## Files to Read First
- `AGENTS.md`
- `ai/repo-context.md`
- `ai/architecture-index.md`
- `docs/global-ranking-page-plan.md`
- `frontend/index.html`
- `frontend/historico.html`
- `frontend/stats.html`
- `frontend/assets/js/stats.js`
- `frontend/assets/css/styles.css`
- `backend/app/routes.py`
- `ai/tasks/done/TASK-181-add-global-ranking-backend-support.md`
## Expected Files Modified
- `frontend/ranking.html`
- `frontend/assets/js/ranking.js`
- `frontend/assets/css/styles.css`
- `frontend/index.html`
- `ai/tasks/done/TASK-182-add-global-ranking-frontend-page.md`
## Constraints Verified
- No backend files were changed in this task.
- No new endpoints were added.
- No database changes were made.
- No Elo/MMR reactivation.
- No Comunidad Hispana #03 reintroduction.
- Stats behavior was left intact.
- Implementation stayed in vanilla HTML/CSS/JS.
## Outcome
- Added `frontend/ranking.html` as a dedicated Ranking page.
- Added `frontend/assets/js/ranking.js` to:
- check backend health
- request `/api/ranking`
- switch between weekly, monthly and annual flows
- render loading, offline, no-data, annual-missing and controlled-error states
- Extended shared styling in `frontend/assets/css/styles.css` for:
- ranking filter layout
- ranking metadata cards
- ranking table
- ranking empty state
- Added a minimal `Ranking` entry point in `frontend/index.html`.
- Kept cross-linking minimal by linking from Ranking to Stats without modifying `stats.html`.
## Validation
Executed:
- `node --check frontend/assets/js/ranking.js`
- `node --check frontend/assets/js/stats.js`
- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
- Local static serving with `python -m http.server`
HTTP checks:
- `ranking.html` -> `200`
- `assets/js/ranking.js` -> `200`
- `stats.html` -> `200`
Offline-state check:
- Backend was unavailable at `http://127.0.0.1:8000`.
- A headless Edge DOM capture of `ranking.html` showed `#ranking-backend-state` rendered as `Backend no disponible`, confirming the intended offline fallback path.
Known limitation:
- Live successful ranking calls could not be verified through a running backend during this task because the backend was not available over HTTP in the environment.
## Recommended Follow-up
- Add a dedicated ranking frontend regression script so `ranking.html` state coverage is validated alongside existing historical and stats checks.