From fbb8adbf01b7b222c14096bd8d536e9826d98d8f Mon Sep 17 00:00:00 2001 From: devRaGonSa <97627393+devRaGonSa@users.noreply.github.com> Date: Sun, 7 Jun 2026 17:25:04 +0200 Subject: [PATCH] Add task for stats section functional contract --- ...efine-stats-section-functional-contract.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 ai/tasks/pending/TASK-161-define-stats-section-functional-contract.md diff --git a/ai/tasks/pending/TASK-161-define-stats-section-functional-contract.md b/ai/tasks/pending/TASK-161-define-stats-section-functional-contract.md new file mode 100644 index 0000000..ea48aad --- /dev/null +++ b/ai/tasks/pending/TASK-161-define-stats-section-functional-contract.md @@ -0,0 +1,195 @@ +--- +id: TASK-161 +title: Define Stats section functional contract +status: pending +type: documentation +team: Analista +supporting_teams: + - PM + - Backend Senior + - Frontend Senior + - Arquitecto de Base de Datos + - Experto en interfaz +roadmap_item: stats-section +priority: high +--- + +# TASK-161 - Define Stats section functional contract + +## Goal + +Define the functional and technical contract for a new `Stats` section where players can search themselves, view their personal statistics across the community servers, and understand their weekly and monthly ranking position. + +This task must also prepare the future annual ranking design, including a dedicated annual top 20 snapshot model, without implementing backend endpoints, database migrations or frontend UI yet. + +## Context + +HLL Vietnam already has an RCON-first historical architecture and materialized match/player statistics. The existing leaderboard read model in `backend/app/rcon_historical_leaderboards.py` supports weekly and monthly leaderboard payloads over RCON/AdminLog materialized tables. + +The next product step is to convert this foundation into a player-facing `Stats` section with a clear V1 scope: + +- player search +- personal player statistics +- weekly ranking position +- monthly ranking position +- annual top 20 ranking preparation + +The annual ranking should not be recalculated on every public request. The preferred direction is to design a dedicated snapshot table/model for yearly top 20 rankings, generated from materialized RCON historical data. + +Preserve the current product identity: Spanish-speaking HLL Vietnam community, military/Vietnam/tactical/sober visual direction and controlled repository evolution. + +## Steps + +1. Inspect the listed files first. +2. Review the current RCON-first historical and leaderboard assumptions. +3. Define the V1 user flow for the new `Stats` section. +4. Define the backend API contract needed by the frontend. +5. Define the minimum personal statistics payload. +6. Define how weekly and monthly ranking positions should be calculated for a selected player. +7. Define the annual top 20 snapshot direction and the database objects that a later implementation task should add. +8. Document explicit non-goals and future extensions. +9. Create or update a focused documentation file for this feature. +10. Do not implement backend endpoints, database migrations, frontend screens or scripts in this task. + +## Files to Read First + +- `AGENTS.md` +- `ai/repo-context.md` +- `ai/architecture-index.md` +- `ai/task-template.md` +- `backend/app/rcon_historical_leaderboards.py` +- `docs/frontend-data-consumption-plan.md` + +## Expected Files to Modify + +- `docs/stats-section-functional-plan.md` +- `ai/tasks/pending/TASK-161-define-stats-section-functional-contract.md` + +If `docs/frontend-data-consumption-plan.md` must be lightly cross-referenced, keep the change minimal and explain it in the outcome. Do not modify backend or frontend implementation files in this task. + +## Functional Contract To Define + +The documentation must cover at least: + +### Stats section user flow + +- User opens the `Stats` section. +- User searches by player name or player id. +- User selects a player from search results. +- UI displays personal statistics. +- UI displays the player's weekly and monthly ranking position. +- UI can later display annual top 20 ranking snapshot data. + +### Player search contract + +Propose a future endpoint similar to: + +```http +GET /api/stats/players/search?q= +``` + +Expected fields: + +- `player_id` +- `player_name` +- `matches_considered` +- `last_seen_at` +- optional `servers_seen` + +### Personal stats contract + +Propose a future endpoint similar to: + +```http +GET /api/stats/players/{player_id}?server_id=&timeframe=weekly|monthly|all +``` + +Minimum V1 fields: + +- player id +- player name +- selected server scope +- selected timeframe +- window start/end +- matches considered +- kills +- deaths +- teamkills +- K/D ratio +- kills per match +- deaths per match +- weekly ranking position by kills +- monthly ranking position by kills +- data source and freshness metadata + +### Annual ranking snapshot contract + +Define the future annual snapshot direction with a dedicated persistence model, preferably split into: + +- `rcon_annual_ranking_snapshots` +- `rcon_annual_ranking_snapshot_items` + +The documentation should describe expected columns, uniqueness rules, generation policy and read API direction, but must not create migrations yet. + +Propose a future endpoint similar to: + +```http +GET /api/stats/rankings/annual?year=&server_id=&metric=kills +``` + +### V1 non-goals + +Explicitly exclude from this first feature contract: + +- Elo/MMR reactivation +- Comunidad Hispana #03 reintroduction +- support/combat/offense/defense scoring unless already available from reliable RCON materialized data +- weapon-level breakdowns +- charts/advanced visualizations +- authentication or private player profiles +- frontend implementation +- backend endpoint implementation +- database migration implementation + +## Constraints + +- Keep the change documentation-only. +- Preserve HLL Vietnam project identity. +- Do not introduce unnecessary frameworks or dependencies. +- Do not implement backend functionality in this task. +- Do not implement frontend functionality in this task. +- Do not expand Elo/MMR, historical workers or RCON server #03 handling. +- Do not overwrite repository-specific context with generic platform template text. +- Keep future tasks small and sequenced. + +## Validation + +Before completing the task ensure: + +- `docs/stats-section-functional-plan.md` exists and is specific to HLL Vietnam. +- The document references the RCON-first materialized data direction. +- The document defines V1 scope, API contracts, payload expectations and annual snapshot direction. +- No backend implementation files were modified. +- No frontend implementation files were modified. +- `git diff --name-only` matches the expected scope. +- If no automated tests are relevant because this is documentation-only, document that explicitly in the outcome. + +## Outcome + +Document: + +- validation performed +- files changed +- notable decisions +- recommended next tasks, likely: + - add player stats search endpoint + - add player personal stats endpoint + - add annual leaderboard timeframe support + - design annual ranking snapshot schema + - add Stats frontend section + +## Change Budget + +- Prefer fewer than 3 modified files. +- Prefer changes under 250 lines. +- Split implementation details into follow-up tasks instead of expanding this task.