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

id, title, status, type, team, supporting_teams, roadmap_item, priority

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-189-add-ranking-materialized-read-indexes	Add ranking materialized read indexes	pending	backend	Arquitecto de Base de Datos	Backend Senior	foundation	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

Document:

• indexes added
• why each index was chosen
• observed improvement or inability to measure it
• residual performance gaps that still require snapshot-based reads

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.