TASK-190 - Design weekly monthly ranking snapshots

Goal

Design a weekly/monthly ranking snapshot read model, equivalent in philosophy to the annual snapshot model, so public ranking requests do not depend on expensive runtime aggregation.

Context

Annual ranking already follows a snapshot-backed read path, but weekly/monthly public ranking still depends on runtime aggregation over materialized match stats. HLL Vietnam needs a documented snapshot model for weekly and monthly ranking windows that preserves the current RCON-first policy, keeps annual behavior intact and defines a controlled fallback strategy during transition.

Preserve the current product identity: Spanish-speaking HLL Vietnam community, military/Vietnam/tactical/sober visual direction and controlled repository evolution.

Steps

Read the listed files first.
Use the performance audit and the annual snapshot runbook as reference points.
Define the proposed tables, keys, metadata and item payload needed for weekly/monthly ranking snapshots.
Define refresh cadence and lifecycle rules for current and closed windows.
Define the public fallback policy without reintroducing heavy recomputation on every request.

Files to Read First

AGENTS.md
ai/repo-context.md
ai/architecture-index.md
docs/ranking-stats-performance-audit.md
docs/global-ranking-page-plan.md
docs/annual-ranking-snapshot-runbook.md
backend/app/rcon_historical_leaderboards.py
backend/app/rcon_annual_rankings.py

Expected Files to Modify

docs/ranking-snapshot-read-model-plan.md
ai/tasks/done/TASK-190-design-weekly-monthly-ranking-snapshots.md

Constraints

Documentación-only.
No modificar backend.
No modificar frontend.
No crear migraciones.
No implementar snapshots todavía.
No reactivar Elo/MMR.
No reintroducir Comunidad Hispana #03.
Mantener el diseño alineado con Python backend y con el snapshot anual existente.

Validation

Before completing the task ensure:

the plan defines ranking_snapshots
the plan defines ranking_snapshot_items
the model covers:
- timeframe weekly/monthly/annual
- server_id
- metric
- window_start and window_end
- generated_at
- source
- snapshot_status
- item_count
- limit_size
- ranking_position
- player_id
- player_name
- metric_value
- matches_considered
- kills
- deaths
- teamkills
- kd_ratio
- kills_per_match
the refresh policy is explicit:
- weekly current every 5-15 minutes
- monthly current every 15-30 minutes
- previous week/month closed and stable
- annual manual or daily
the fallback policy is explicit:
- serve snapshot if present
- return controlled missing or use runtime fallback only by configuration if missing
- never recalculate by default on every public request
the plan names impacted endpoints and expected response metadata
git diff --name-only stays within scope

Outcome

Snapshot design documented in docs/ranking-snapshot-read-model-plan.md.
Proposed read model uses:
- ranking_snapshots
- ranking_snapshot_items
The plan explicitly covers:
- timeframe weekly/monthly/annual
- server_id
- metric
- window_start
- window_end
- generated_at
- source
- snapshot_status
- item_count
- limit_size
- per-item ranking and player fields
Refresh policy defined:
- weekly current every 5 to 15 minutes
- monthly current every 15 to 30 minutes
- previous week/month stable once closed
- annual manual or daily
Fallback policy defined:
- serve snapshot when ready
- return controlled missing or use runtime fallback only by configuration when snapshot is absent
- never recalculate by default on every public request
Transition notes prepared for TASK-191:
- weekly/monthly snapshot-first read path
- annual remains on the existing annual snapshot implementation until a dedicated migration task consolidates storage

Change Budget

Prefer fewer than 5 modified files.
Prefer changes under 200 lines when feasible.
Split the work into follow-up tasks if limits are exceeded.

4.4 KiB Raw Blame History