Add global ranking page task plan
This commit is contained in:
devRaGonSa
110
ai/tasks/pending/TASK-180-define-global-ranking-page-contract.md
Normal file
110
ai/tasks/pending/TASK-180-define-global-ranking-page-contract.md
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
id: TASK-180-define-global-ranking-page-contract
|
||||
title: Define global ranking page contract
|
||||
status: pending
|
||||
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 will expose 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 (purpose, data sources, filters, payload, and states).
|
||||
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 (no Elo/MMR, no Comunidad Hispana #03, no public scoreboard as primary source when RCON exists).
|
||||
6. Capture follow-up items and leave 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.
|
||||
|
||||
## Outcome
|
||||
|
||||
- Documented Ranking goal and how it differs from Stats.
|
||||
- Documented user flow:
|
||||
- open Ranking page
|
||||
- choose timeframe
|
||||
- choose server
|
||||
- choose metric
|
||||
- view top players
|
||||
- change filters without manual reload where feasible
|
||||
- Documented expected API contract:
|
||||
- weekly/monthly from RCON materialized leaderboard model
|
||||
- annual from existing annual snapshot model
|
||||
- Documented payload contract including:
|
||||
- `ranking_position`
|
||||
- `player_id`
|
||||
- `player_name`
|
||||
- `metric_value`
|
||||
- `matches_considered`
|
||||
- `kills`
|
||||
- `deaths`
|
||||
- `teamkills`
|
||||
- `kd_ratio`
|
||||
- `window_start`
|
||||
- `window_end`
|
||||
- `snapshot_status` where applicable
|
||||
- Documented UI states:
|
||||
- loading
|
||||
- backend offline
|
||||
- no data
|
||||
- annual snapshot missing
|
||||
- unsupported metric
|
||||
- controlled error
|
||||
- Documented non-goals:
|
||||
- Elo/MMR
|
||||
- authentication
|
||||
- private profile expansion
|
||||
- advanced charts
|
||||
- large database changes
|
||||
- reintroducing Comunidad Hispana #03
|
||||
|
||||
## Validation
|
||||
|
||||
- Confirm `docs/global-ranking-page-plan.md` exists.
|
||||
- Confirm no backend/frontend files were modified.
|
||||
- Run `git diff --name-only` within task scope.
|
||||
- If no automated tests apply, document that explicitly in Outcome.
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
id: TASK-181-add-global-ranking-backend-support
|
||||
title: Add global ranking backend support
|
||||
status: pending
|
||||
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 should expose a dedicated global ranking endpoint that supports weekly/monthly and annual modes, with initial metric support set to `kills` and clear behavior for unsupported inputs and limits.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Read the listed files first.
|
||||
2. Reuse leaderboard query modules for weekly/monthly ranking reads.
|
||||
3. Reuse annual snapshot reader for annual ranking reads, with no recalculation per request.
|
||||
4. Add route-level validation for timeframe/metric/limit/year behavior.
|
||||
5. Keep payload shapes compatible with future frontend rendering and existing frontend patterns.
|
||||
6. Document any optional follow-up if additional metrics are delayed beyond V1.
|
||||
|
||||
## 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, if required for response normalization
|
||||
- backend/app/rcon_historical_leaderboards.py, only if small reusable exposure is needed
|
||||
- backend/app/rcon_annual_rankings.py, only if response shape/read behavior adaptation is needed without changing core logic
|
||||
- scripts/run-stats-validation.ps1 or a new script to cover global ranking
|
||||
- ai/tasks/done/TASK-181-add-global-ranking-backend-support.md
|
||||
|
||||
## Constraints
|
||||
|
||||
- Do not create new architecture.
|
||||
- Do not add large migrations.
|
||||
- Do not recalculate annual ranking on each public request.
|
||||
- Do not re-enable Elo/MMR.
|
||||
- Do not reintroduce Comunidad Hispana #03.
|
||||
- Do not use public scoreboard as primary source while RCON coverage exists.
|
||||
- Preserve existing Stats endpoint compatibility.
|
||||
- Avoid frontend changes unless strictly required for backend documentation-only validation.
|
||||
- Keep changes scoped and verifiable.
|
||||
|
||||
## Outcome
|
||||
|
||||
- Endpoint created and documented.
|
||||
- Final payload contract captured and aligned with Ranking page requirements.
|
||||
- Source flow documented by timeframe:
|
||||
- weekly/monthly from RCON materialized data
|
||||
- annual from annual snapshot records
|
||||
- Validation outputs and known limits recorded.
|
||||
- Follow-up recommendation for next task: frontend page implementation.
|
||||
|
||||
## Validation
|
||||
|
||||
- Run `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`.
|
||||
- If endpoint-specific checks are added, run them in this task.
|
||||
- Validate endpoint cases:
|
||||
- weekly, `metric=kills`, `limit=20`
|
||||
- monthly, `metric=kills`, `limit=20`
|
||||
- annual, `metric=kills`, `limit=20`
|
||||
- annual path with year if the implementation requires it
|
||||
- low limit, for example `3`
|
||||
- high invalid limit
|
||||
- unsupported metric
|
||||
- unsupported timeframe
|
||||
- Run `git diff --name-only` within the scoped files.
|
||||
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
id: TASK-182-add-global-ranking-frontend-page
|
||||
title: Add global ranking frontend page
|
||||
status: pending
|
||||
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/section that displays global top lists by timeframe, server, metric, and limit, consuming the backend support built in TASK-181.
|
||||
|
||||
## Context
|
||||
|
||||
This page must be separated from Stats and focused on list-level ranking discovery (global leaders), while clearly linking to Stats for individual player lookup.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Read the listed files first.
|
||||
2. Add `frontend/ranking.html` with controls for timeframe, server, metric, and limit.
|
||||
3. Implement `frontend/assets/js/ranking.js` to call the global ranking endpoint and render rows.
|
||||
4. Update shared styles in `frontend/assets/css/styles.css` as needed, preserving the project visual direction.
|
||||
5. Wire ranking access from existing navigation (`frontend/index.html`) only if needed.
|
||||
6. Add a minimal cross-link to Stats if useful and safe.
|
||||
7. Document covered UI states and fallback behavior when backend is unavailable.
|
||||
|
||||
## 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 to Modify
|
||||
|
||||
- frontend/ranking.html
|
||||
- frontend/assets/js/ranking.js
|
||||
- frontend/assets/css/styles.css
|
||||
- frontend/index.html, only if navigation needs update
|
||||
- frontend/stats.html, only if minimal cross-link is required
|
||||
- scripts/run-stats-validation.ps1 or new ranking validation script
|
||||
- ai/tasks/done/TASK-182-add-global-ranking-frontend-page.md
|
||||
|
||||
## Constraints
|
||||
|
||||
- No backend modifications.
|
||||
- No new endpoints.
|
||||
- No database migrations.
|
||||
- No Elo/MMR reactivation.
|
||||
- No reintroduction of Comunidad Hispana #03.
|
||||
- No frameworks; continue with vanilla HTML/CSS/JS.
|
||||
- Preserve military/Vietnam/tactical/sober visual identity.
|
||||
- Do not regress Stats behavior.
|
||||
- Avoid duplicating complex Stats logic; reuse patterns where practical.
|
||||
|
||||
## Outcome
|
||||
|
||||
- Global ranking page created and consumable.
|
||||
- Endpoint consumed and documented.
|
||||
- Validation of UI states:
|
||||
- loading
|
||||
- backend offline
|
||||
- no data
|
||||
- annual snapshot missing
|
||||
- unsupported metric
|
||||
- controlled error
|
||||
- Validation list and known limitations recorded.
|
||||
- Recommended follow-up tasks (if any).
|
||||
|
||||
## Validation
|
||||
|
||||
- Run `node --check frontend/assets/js/ranking.js`.
|
||||
- Run `node --check frontend/assets/js/stats.js`.
|
||||
- Run `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`.
|
||||
- Serve frontend with `python -m http.server` and verify HTTP 200 for:
|
||||
- `ranking.html`
|
||||
- `assets/js/ranking.js`
|
||||
- `stats.html`
|
||||
- If backend is available, validate ranking calls against live endpoint.
|
||||
- If backend is unavailable, validate UI offline state.
|
||||
- Run `git diff --name-only` and verify scoped changes.
|
||||
|
||||
Reference in New Issue
Block a user