Add ranking snapshot performance path

ai/tasks/done/TASK-190-design-weekly-monthly-ranking-snapshots.md

@@ -0,0 +1,134 @@
+---
+id: TASK-190-design-weekly-monthly-ranking-snapshots
+title: Design weekly monthly ranking snapshots
+status: done
+type: documentation
+team: Arquitecto de Base de Datos
+supporting_teams:
+  - Backend Senior
+  - PM
+roadmap_item: foundation
+priority: high
+---
+
+# 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
+
+1. Read the listed files first.
+2. Use the performance audit and the annual snapshot runbook as reference points.
+3. Define the proposed tables, keys, metadata and item payload needed for weekly/monthly ranking snapshots.
+4. Define refresh cadence and lifecycle rules for current and closed windows.
+5. 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.