docs(tasks): update task artifacts for stats workflow
This commit is contained in:
devRaGonSa
@@ -0,0 +1,199 @@
|
||||
---
|
||||
id: TASK-161
|
||||
title: Define Stats section functional contract
|
||||
status: done
|
||||
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=<query>
|
||||
```
|
||||
|
||||
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=<server-or-all>&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=<year>&server_id=<server-or-all>&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
|
||||
|
||||
Completed as documentation-only.
|
||||
|
||||
- Created `docs/stats-section-functional-plan.md` as the focused contract for the future `Stats` section.
|
||||
- Kept the contract aligned with the current RCON-first materialized historical read model and the weekly/monthly window policy already present in `backend/app/rcon_historical_leaderboards.py`.
|
||||
- Defined the V1 user flow, player search contract, personal stats payload, ranking position rules and annual top 20 snapshot persistence direction.
|
||||
- Explicitly kept backend endpoints, database migrations and frontend implementation out of scope.
|
||||
|
||||
## Validation Result
|
||||
|
||||
- Verified `docs/stats-section-functional-plan.md` exists and is specific to HLL Vietnam.
|
||||
- Verified the document references the RCON-first materialized data direction.
|
||||
- Verified the document defines V1 scope, API contracts, payload expectations and annual snapshot direction.
|
||||
- Verified no backend implementation files were modified for this task.
|
||||
- Verified no frontend implementation files were modified for this task.
|
||||
- No automated or integration tests applied because this task is documentation-only.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user