docs(tasks): update task artifacts for stats workflow
This commit is contained in:
devRaGonSa
311
docs/stats-section-functional-plan.md
Normal file
311
docs/stats-section-functional-plan.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# Stats Section Functional Plan
|
||||
|
||||
## Objective
|
||||
|
||||
Define the V1 functional contract for a future `Stats` section where a player can search their profile, review personal historical performance across HLL Vietnam community servers, and understand their weekly and monthly ranking position without implementing backend or frontend yet.
|
||||
|
||||
## Current Foundation
|
||||
|
||||
- HLL Vietnam historical read paths are RCON-first.
|
||||
- `backend/app/rcon_historical_leaderboards.py` already defines weekly and monthly leaderboard windows over materialized RCON/AdminLog match stats.
|
||||
- Current reliable materialized counters for public player-facing V1 are kills, deaths, teamkills and matches considered.
|
||||
- Public scoreboard data remains fallback or enrichment only; it must not become the normal primary source for this section while RCON coverage exists.
|
||||
|
||||
## V1 Scope
|
||||
|
||||
The first `Stats` contract covers:
|
||||
|
||||
- player search by name or player id
|
||||
- player detail view for one selected player
|
||||
- personal totals for a selected timeframe and server scope
|
||||
- weekly ranking position by kills
|
||||
- monthly ranking position by kills
|
||||
- data freshness and source metadata
|
||||
- annual top 20 preparation through a dedicated snapshot model
|
||||
|
||||
V1 should support two server scopes:
|
||||
|
||||
- one specific server id
|
||||
- `all` aggregated across active supported servers
|
||||
|
||||
## User Flow
|
||||
|
||||
1. User opens the future `Stats` section.
|
||||
2. User searches by partial player name or exact player id.
|
||||
3. Backend returns compact search matches ordered by best textual match and recent activity.
|
||||
4. User selects one player result.
|
||||
5. Frontend requests the player detail payload for a chosen server scope and timeframe.
|
||||
6. UI shows core totals, calculated ratios, weekly rank position and monthly rank position.
|
||||
7. UI may later request annual ranking snapshot data for the selected year without recalculating it on each public request.
|
||||
|
||||
## API Contract Direction
|
||||
|
||||
### 1. Player search
|
||||
|
||||
```http
|
||||
GET /api/stats/players/search?q=<query>&server_id=<server-or-all>&limit=10
|
||||
```
|
||||
|
||||
Purpose:
|
||||
|
||||
- resolve a user-entered name fragment or player id into selectable player records backed by materialized historical data
|
||||
|
||||
Query rules:
|
||||
|
||||
- `q` is required
|
||||
- `server_id` is optional and defaults to `all`
|
||||
- `limit` is optional and defaults to `10`, with a hard cap such as `20`
|
||||
|
||||
Response shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"query": "rambo",
|
||||
"server_id": "all",
|
||||
"items": [
|
||||
{
|
||||
"player_id": "76561198000000000",
|
||||
"player_name": "Rambo",
|
||||
"matches_considered": 42,
|
||||
"last_seen_at": "2026-06-06T21:40:00Z",
|
||||
"servers_seen": ["comunidad-hispana-01", "comunidad-hispana-02"]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Search result notes:
|
||||
|
||||
- `player_id` is the canonical selection key for later requests
|
||||
- `player_name` is the latest display name known from materialized stats
|
||||
- `matches_considered` is the aggregated closed-match count in the selected scope
|
||||
- `servers_seen` is optional and may be omitted when `server_id` is not `all`
|
||||
|
||||
### 2. Personal player stats
|
||||
|
||||
```http
|
||||
GET /api/stats/players/{player_id}?server_id=<server-or-all>&timeframe=weekly|monthly|all
|
||||
```
|
||||
|
||||
Purpose:
|
||||
|
||||
- return the selected player summary for the chosen scope and timeframe plus ranking position context
|
||||
|
||||
Response shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"player_id": "76561198000000000",
|
||||
"player_name": "Rambo",
|
||||
"server_id": "all",
|
||||
"timeframe": "monthly",
|
||||
"window_start": "2026-06-01T00:00:00Z",
|
||||
"window_end": "2026-06-07T18:00:00Z",
|
||||
"matches_considered": 12,
|
||||
"kills": 356,
|
||||
"deaths": 241,
|
||||
"teamkills": 4,
|
||||
"kd_ratio": 1.48,
|
||||
"kills_per_match": 29.67,
|
||||
"deaths_per_match": 20.08,
|
||||
"weekly_ranking": {
|
||||
"metric": "kills",
|
||||
"ranking_position": 8,
|
||||
"window_kind": "current-week",
|
||||
"window_start": "2026-06-02T00:00:00Z",
|
||||
"window_end": "2026-06-07T18:00:00Z"
|
||||
},
|
||||
"monthly_ranking": {
|
||||
"metric": "kills",
|
||||
"ranking_position": 5,
|
||||
"window_kind": "current-month",
|
||||
"window_start": "2026-06-01T00:00:00Z",
|
||||
"window_end": "2026-06-07T18:00:00Z"
|
||||
},
|
||||
"source": {
|
||||
"primary_source": "rcon",
|
||||
"read_model": "rcon-materialized-admin-log-player-stats",
|
||||
"generated_at": "2026-06-07T18:02:00Z",
|
||||
"source_range_start": "2026-06-01T00:14:00Z",
|
||||
"source_range_end": "2026-06-07T17:51:00Z",
|
||||
"freshness": "runtime"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Field rules:
|
||||
|
||||
- `timeframe=weekly` returns the player totals within the same weekly window policy used by leaderboard reads
|
||||
- `timeframe=monthly` returns the player totals within the same monthly window policy used by leaderboard reads
|
||||
- `timeframe=all` returns all-time totals for the selected scope, but still includes weekly and monthly ranking blocks as separate comparative context
|
||||
- `kd_ratio`, `kills_per_match` and `deaths_per_match` should be rounded for display-safe payloads
|
||||
|
||||
### 3. Annual ranking snapshot
|
||||
|
||||
```http
|
||||
GET /api/stats/rankings/annual?year=<year>&server_id=<server-or-all>&metric=kills
|
||||
```
|
||||
|
||||
Purpose:
|
||||
|
||||
- return a precomputed annual top 20 leaderboard snapshot without recalculating the full year on each public request
|
||||
|
||||
Response shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"year": 2026,
|
||||
"server_id": "all",
|
||||
"metric": "kills",
|
||||
"generated_at": "2027-01-01T01:30:00Z",
|
||||
"snapshot_status": "ready",
|
||||
"items": [
|
||||
{
|
||||
"ranking_position": 1,
|
||||
"player_id": "76561198000000000",
|
||||
"player_name": "Rambo",
|
||||
"metric_value": 4210,
|
||||
"matches_considered": 148,
|
||||
"kills": 4210,
|
||||
"deaths": 2950,
|
||||
"teamkills": 18,
|
||||
"kd_ratio": 1.43
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
V1 annual endpoint notes:
|
||||
|
||||
- only `metric=kills` needs to be committed in the first annual design pass
|
||||
- annual read path should be snapshot-backed, not runtime full-range aggregation
|
||||
- if a requested year is not generated yet, respond with a controlled empty or pending state, not a slow public recalculation
|
||||
|
||||
## Ranking Calculation Rules
|
||||
|
||||
### Weekly position
|
||||
|
||||
- Use the same weekly window selected by `select_leaderboard_window(... timeframe="weekly")`
|
||||
- Respect the existing sufficient-sample policy:
|
||||
- use current week when the closed-match threshold is met
|
||||
- fall back to previous week when the current week sample is insufficient
|
||||
- Rank by total kills descending
|
||||
- Break ties by:
|
||||
- `matches_considered` descending
|
||||
- `player_name` ascending
|
||||
- Player position should be derived from the same aggregate query family as the public leaderboard to avoid contradictory ordering
|
||||
|
||||
### Monthly position
|
||||
|
||||
- Use the same monthly window selected by `select_leaderboard_window(... timeframe="monthly")`
|
||||
- Respect the current rule already present in the read model:
|
||||
- from day 1 to day 7, use previous month
|
||||
- from day 8 onward, use current month
|
||||
- Rank by total kills descending with the same tie-break rules used in weekly ranking
|
||||
|
||||
### Personal totals
|
||||
|
||||
- Use the same RCON materialized match/player stats source as leaderboard calculations
|
||||
- Only closed matches within the selected scope and selected timeframe window should count
|
||||
- Do not add support, offense, defense or weapon breakdown fields until they are proven reliable in the RCON materialized model
|
||||
|
||||
## Annual Snapshot Persistence Direction
|
||||
|
||||
Future implementation should add a dedicated persistence model instead of recomputing annual top 20 on every request.
|
||||
|
||||
### Table: `rcon_annual_ranking_snapshots`
|
||||
|
||||
Expected columns:
|
||||
|
||||
- `id`
|
||||
- `server_id`
|
||||
- `year`
|
||||
- `metric`
|
||||
- `generated_at`
|
||||
- `source_range_start`
|
||||
- `source_range_end`
|
||||
- `snapshot_status`
|
||||
- `item_count`
|
||||
- `generation_policy`
|
||||
- `notes` nullable
|
||||
|
||||
Expected uniqueness:
|
||||
|
||||
- unique on `(server_id, year, metric)`
|
||||
|
||||
Expected behavior:
|
||||
|
||||
- one authoritative snapshot row per year, scope and metric
|
||||
- regenerated only by an explicit batch job, scheduled maintenance command or year-close workflow
|
||||
|
||||
### Table: `rcon_annual_ranking_snapshot_items`
|
||||
|
||||
Expected columns:
|
||||
|
||||
- `id`
|
||||
- `snapshot_id`
|
||||
- `ranking_position`
|
||||
- `player_id`
|
||||
- `player_name`
|
||||
- `metric_value`
|
||||
- `matches_considered`
|
||||
- `kills`
|
||||
- `deaths`
|
||||
- `teamkills`
|
||||
- `kd_ratio`
|
||||
|
||||
Expected uniqueness:
|
||||
|
||||
- unique on `(snapshot_id, ranking_position)`
|
||||
- unique on `(snapshot_id, player_id)`
|
||||
|
||||
Expected behavior:
|
||||
|
||||
- store only the top 20 rows for the selected annual snapshot
|
||||
- preserve display-ready values used by the frontend
|
||||
- keep enough totals to show a concise annual card without joining additional tables at read time
|
||||
|
||||
### Generation policy
|
||||
|
||||
- Run after year close or through an explicit maintenance workflow
|
||||
- Read from materialized RCON historical data, not live RCON calls
|
||||
- Default scope should support both `all` and individual active servers
|
||||
- Prefer idempotent replace or upsert semantics for a given `(server_id, year, metric)`
|
||||
- Store `generated_at` and source range metadata for traceability
|
||||
|
||||
## V1 Non-goals
|
||||
|
||||
- Elo or MMR reactivation
|
||||
- Comunidad Hispana #03 reintroduction
|
||||
- support, combat, offense or defense ranking when not already reliable in materialized RCON stats
|
||||
- weapon-level breakdowns
|
||||
- charts, heatmaps or advanced visualizations
|
||||
- authenticated or private player profiles
|
||||
- backend endpoint implementation
|
||||
- database migrations
|
||||
- frontend page, components or scripts
|
||||
|
||||
## Future Extensions After V1
|
||||
|
||||
- map-by-map player breakdowns
|
||||
- server comparison cards per player
|
||||
- annual ranking filters beyond kills
|
||||
- profile history charts when a stable event or snapshot series exists
|
||||
- external links to trusted scoreboard detail when correlation is already validated
|
||||
|
||||
## Recommended Follow-up Tasks
|
||||
|
||||
- add player search endpoint over materialized RCON player stats
|
||||
- add personal player stats endpoint with weekly and monthly ranking context
|
||||
- design and implement annual ranking snapshot schema and generation command
|
||||
- extend frontend data consumption plan with the `Stats` section integration sequence
|
||||
- implement the `Stats` frontend section with static-safe fallback behavior
|
||||
Reference in New Issue
Block a user