Add ranking snapshot performance path

ai/tasks/done/TASK-188-audit-ranking-and-stats-query-performance.md

@@ -0,0 +1,108 @@
+---
+id: TASK-188-audit-ranking-and-stats-query-performance
+title: Audit ranking and stats query performance
+status: done
+type: research
+team: Arquitecto de Base de Datos
+supporting_teams:
+  - Backend Senior
+  - Arquitecto Python
+roadmap_item: foundation
+priority: high
+---
+
+# TASK-188 - Audit ranking and stats query performance
+
+## Goal
+
+Measure and document the real performance of the public Ranking and Stats endpoints before applying any optimization.
+
+## Context
+
+`/api/ranking` weekly/monthly currently reads runtime aggregates over materialized RCON/AdminLog tables, while annual ranking already uses snapshots. `Stats` search and player detail also depend on runtime reads over the same materialized domain. HLL Vietnam needs a concrete baseline for latency, query shape, table size and execution plan so follow-up work can target the real bottlenecks instead of guessing.
+
+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. Identify the exact queries and tables used by the target endpoints.
+3. Measure request time and, if possible, approximate SQL time for each target endpoint.
+4. Inspect relevant row counts, current indexes and execution plans when the engine allows it.
+5. Document the slowest endpoint and provide a concrete index/snapshot recommendation without changing runtime code.
+
+## Files to Read First
+
+- `AGENTS.md`
+- `ai/repo-context.md`
+- `ai/architecture-index.md`
+- `backend/app/routes.py`
+- `backend/app/rcon_historical_leaderboards.py`
+- `backend/app/rcon_historical_player_stats.py`
+- `backend/app/rcon_annual_rankings.py`
+- `docs/global-ranking-page-plan.md`
+- `scripts/run-stats-validation.ps1`
+
+## Expected Files to Modify
+
+- `docs/ranking-stats-performance-audit.md`
+- `ai/tasks/done/TASK-188-audit-ranking-and-stats-query-performance.md`
+
+## Constraints
+
+- No modificar lógica de backend.
+- No modificar frontend.
+- No crear migraciones.
+- No crear índices todavía.
+- No cambiar APIs.
+- No reactivar Elo/MMR.
+- No reintroducir Comunidad Hispana #03.
+- Mantener el trabajo limitado a medición y documentación.
+
+## Validation
+
+Before completing the task ensure:
+
+- the audit covers:
+  - `/api/ranking` weekly `kills`
+  - `/api/ranking` weekly `kd_ratio`
+  - `/api/ranking` monthly `kills_per_match`
+  - `/api/ranking` annual `kills`
+  - `/api/stats/players/search`
+  - `/api/stats/players/{player_id}`
+- the document records:
+  - total request time
+  - approximate SQL time if measurable
+  - row counts for relevant tables
+  - existing indexes
+  - current query shapes
+  - execution plan if available
+  - slowest endpoint
+  - concrete recommendation for indexes and/or snapshots
+- executed commands are documented
+- inability to obtain `EXPLAIN` is documented if the environment blocks it
+- `git diff --name-only` stays within scope
+
+## Outcome
+
+- Audit completed in `docs/ranking-stats-performance-audit.md`.
+- Measured baseline captured for the six required endpoint probes.
+- Environment limitation documented: backend HTTP server was not running locally, so request timing used in-process route resolution and SQL tracing over SQLite.
+- Current runtime weekly/monthly ranking windows on `2026-06-09` are empty because the latest materialized `admin-log-match-ended` data ends on `2026-05-20T23:21:45.816Z`.
+- Slowest measured endpoint is `/api/stats/players/{player_id}` because it issues 16 SQL statements, including repeated window counts and two ranking-position subqueries.
+- Primary future performance risks identified:
+  - full scans on `rcon_materialized_matches` for `source_basis + time-window` filters
+  - a full scan on `rcon_match_player_stats` for player-detail-by-`player_id`
+  - temp B-trees for grouping, `COUNT(DISTINCT)` and ordering in leaderboard/search queries
+- Follow-up recommendation for `TASK-189`:
+  - add time-window indexes on `rcon_materialized_matches`
+  - add a direct `player_id` index on `rcon_match_player_stats`
+  - keep annual snapshot indexes as-is
+- Follow-up recommendation for `TASK-190`:
+  - move weekly/monthly public ranking to snapshot-backed reads with controlled runtime fallback
+
+## 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.