Add ranking snapshot performance path

ai/tasks/done/TASK-189-add-ranking-materialized-read-indexes.md

@@ -0,0 +1,106 @@
+---
+id: TASK-189-add-ranking-materialized-read-indexes
+title: Add ranking materialized read indexes
+status: done
+type: backend
+team: Arquitecto de Base de Datos
+supporting_teams:
+  - Backend Senior
+roadmap_item: foundation
+priority: high
+---
+
+# TASK-189 - Add ranking materialized read indexes
+
+## Goal
+
+Add safe indexes on the materialized tables used by Ranking and Stats to reduce scans and improve join performance.
+
+## Context
+
+The current Ranking and Stats runtime reads depend on `rcon_materialized_matches`, `rcon_match_player_stats` and annual snapshot tables. After `TASK-188` documents the real bottlenecks, HLL Vietnam needs a narrow indexing pass that improves read performance without changing API contracts, recalculating rankings or introducing a second architecture.
+
+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 `docs/ranking-stats-performance-audit.md` as the primary justification source.
+3. Add only the indexes supported by the audit findings and the existing storage initialization/migration pattern.
+4. Keep SQLite/Postgres compatibility if both storage modes are supported in the current backend.
+5. Re-run the validation scripts and, if possible, compare before/after timing for one or two representative endpoints.
+
+## Files to Read First
+
+- `AGENTS.md`
+- `ai/repo-context.md`
+- `ai/architecture-index.md`
+- `docs/ranking-stats-performance-audit.md`
+- `backend/app/rcon_admin_log_materialization.py`
+- `backend/app/rcon_historical_leaderboards.py`
+- `backend/app/rcon_historical_player_stats.py`
+- `backend/app/rcon_annual_rankings.py`
+- `backend/app/postgres_rcon_storage.py`
+- `backend/app/sqlite_utils.py`
+
+## Expected Files to Modify
+
+- `backend` storage/migration/init module correspondiente, según patrón existente
+- `docs/ranking-stats-performance-audit.md`, solo si se documenta índice aplicado
+- `ai/tasks/done/TASK-189-add-ranking-materialized-read-indexes.md`
+
+## Constraints
+
+- No cambiar contratos API.
+- No cambiar frontend.
+- No recalcular rankings.
+- No crear snapshots en esta task.
+- No reactivar Elo/MMR.
+- No reintroducir Comunidad Hispana #03.
+- Mantener compatibilidad SQLite/Postgres si el proyecto usa ambos.
+- Basar los índices en evidencia documentada por `TASK-188`, no en suposiciones.
+
+## Validation
+
+Before completing the task ensure:
+
+- the chosen indexes are justified by `TASK-188`
+- candidate coverage explicitly considers:
+  - `target_key + match_key`
+  - `source_basis + ended_at/started_at`
+  - `target_key + ended_at/started_at`
+  - `player_id`
+  - `player_name` if search benefits from it
+  - `snapshot_id + ranking_position` in snapshot tables if applicable
+- `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
+- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
+- if possible, before/after timing is captured for one or two endpoints
+- any measurement limitations are documented
+- `git diff --name-only` stays within scope
+
+## Outcome
+
+- Added SQLite/PostgreSQL-compatible indexes in the materialized storage initialization path:
+  - `idx_rcon_materialized_matches_source_window_text`
+  - `idx_rcon_materialized_matches_target_source_window_text`
+  - `idx_rcon_materialized_matches_external_source_window_text`
+  - `idx_rcon_match_player_stats_player_id_match`
+- Kept existing annual snapshot indexes unchanged because the annual read path was already using matching indexes.
+- Did not add a plain `player_name` B-tree because the current search query uses `LOWER(player_name) LIKE '%term%'` with a leading wildcard, so the audit did not justify it as a useful narrow index.
+- Post-index validation confirmed plan improvement:
+  - weekly count queries now use the new `source_basis + window` covering index
+  - the stats player-detail aggregate now narrows through the match window index and then probes stats by `(target_key, match_key, player_id)`
+- Before/after timing was captured for representative endpoints:
+  - `/api/stats/players/{player_id}` weekly improved from `8.924 ms / 4.494 ms SQL` to `4.300 ms / 1.043 ms SQL`
+  - `/api/ranking` weekly `kills` showed no meaningful change in this dataset because the active weekly window on `2026-06-09` is empty
+- Validation scripts executed successfully:
+  - `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
+  - `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
+- Remaining gap:
+  - weekly/monthly public ranking still does repeated runtime counting and grouped aggregation per request, so snapshot-backed reads remain necessary in `TASK-190` and `TASK-191`
+
+## 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.