diff --git a/ai/tasks/pending/TASK-188-audit-ranking-and-stats-query-performance.md b/ai/tasks/pending/TASK-188-audit-ranking-and-stats-query-performance.md new file mode 100644 index 0000000..9330b06 --- /dev/null +++ b/ai/tasks/pending/TASK-188-audit-ranking-and-stats-query-performance.md @@ -0,0 +1,99 @@ +--- +id: TASK-188-audit-ranking-and-stats-query-performance +title: Audit ranking and stats query performance +status: pending +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 + +Document: + +- measured baseline results +- environment limitations +- the most likely root cause of slow public reads +- the follow-up recommendation that should feed `TASK-189` and `TASK-190` + +## 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. diff --git a/ai/tasks/pending/TASK-189-add-ranking-materialized-read-indexes.md b/ai/tasks/pending/TASK-189-add-ranking-materialized-read-indexes.md new file mode 100644 index 0000000..da34a74 --- /dev/null +++ b/ai/tasks/pending/TASK-189-add-ranking-materialized-read-indexes.md @@ -0,0 +1,94 @@ +--- +id: TASK-189-add-ranking-materialized-read-indexes +title: Add ranking materialized read indexes +status: pending +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 + +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. diff --git a/ai/tasks/pending/TASK-190-design-weekly-monthly-ranking-snapshots.md b/ai/tasks/pending/TASK-190-design-weekly-monthly-ranking-snapshots.md new file mode 100644 index 0000000..43693ec --- /dev/null +++ b/ai/tasks/pending/TASK-190-design-weekly-monthly-ranking-snapshots.md @@ -0,0 +1,112 @@ +--- +id: TASK-190-design-weekly-monthly-ranking-snapshots +title: Design weekly monthly ranking snapshots +status: pending +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 + +Document: + +- the proposed read-model schema +- refresh policy +- fallback policy +- transition notes for implementation in `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. diff --git a/ai/tasks/pending/TASK-191-serve-ranking-from-snapshots-with-runtime-fallback.md b/ai/tasks/pending/TASK-191-serve-ranking-from-snapshots-with-runtime-fallback.md new file mode 100644 index 0000000..ec23ad4 --- /dev/null +++ b/ai/tasks/pending/TASK-191-serve-ranking-from-snapshots-with-runtime-fallback.md @@ -0,0 +1,113 @@ +--- +id: TASK-191-serve-ranking-from-snapshots-with-runtime-fallback +title: Serve ranking from snapshots with runtime fallback +status: pending +type: backend +team: Backend Senior +supporting_teams: + - Arquitecto de Base de Datos + - Arquitecto Python +roadmap_item: foundation +priority: high +--- + +# TASK-191 - Serve ranking from snapshots with runtime fallback + +## Goal + +Implement the `/api/ranking` read path so weekly and monthly ranking are served from snapshots when available, with a controlled runtime fallback only when configured and only when the snapshot is missing. + +## Context + +Public Ranking requests currently pay the cost of runtime aggregation for weekly and monthly windows, while annual ranking already reads from snapshots. After `TASK-190` defines the snapshot read model, HLL Vietnam needs the public ranking endpoint to prefer snapshot-backed reads, preserve annual snapshot behavior and expose enough metadata for frontend and operations to understand source, freshness and fallback usage. + +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. Implement weekly/monthly snapshot lookup according to `docs/ranking-snapshot-read-model-plan.md`. +3. Keep annual requests on the existing annual snapshot path. +4. Add controlled runtime fallback only for missing weekly/monthly snapshots when configuration allows it. +5. Expose response metadata needed to distinguish snapshot-ready, snapshot-missing and runtime-fallback responses. +6. Validate weekly, monthly, annual and invalid-request behavior. + +## Files to Read First + +- `AGENTS.md` +- `ai/repo-context.md` +- `ai/architecture-index.md` +- `docs/ranking-snapshot-read-model-plan.md` +- `backend/app/routes.py` +- `backend/app/payloads.py` +- `backend/app/rcon_historical_leaderboards.py` +- `backend/app/rcon_annual_rankings.py` +- `scripts/run-stats-validation.ps1` + +## Expected Files to Modify + +- `backend/app/rcon_historical_leaderboards.py` +- `backend/app/routes.py` +- `backend/app/payloads.py` +- `scripts/run-stats-validation.ps1` +- `docs/ranking-snapshot-read-model-plan.md`, solo si se documenta comportamiento final +- `ai/tasks/done/TASK-191-serve-ranking-from-snapshots-with-runtime-fallback.md` + +## Constraints + +- No cambiar frontend salvo que sea imprescindible y esté documentado. +- No crear nuevas features visuales. +- No reactivar Elo/MMR. +- No reintroducir Comunidad Hispana #03. +- No usar scoreboard público como fuente primaria. +- No recalcular rankings pesados si snapshot `ready` existe. +- Mantener fallback runtime controlado para transición. +- La task depende del diseño de `TASK-190`. + +## Validation + +Before completing the task ensure: + +- `/api/ranking` weekly/monthly: + - attempts snapshot read first + - returns snapshot when status is `ready` + - uses runtime materialized fallback only when snapshot is missing and fallback is allowed + - returns controlled missing when snapshot is missing and fallback is not allowed +- `/api/ranking` annual keeps current snapshot behavior +- response metadata includes: + - `source` + - `snapshot_status` + - `generated_at` + - `freshness` + - `fallback_used` + - `window_start` + - `window_end` +- run: + - `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1` + - `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1` +- probe: + - `/api/ranking` weekly + - `/api/ranking` monthly + - `/api/ranking` annual + - snapshot-missing behavior + - invalid `metric` + - invalid `timeframe` + - invalid `limit` +- confirm annual still works +- document if snapshots are not yet generated automatically +- `git diff --name-only` stays within scope + +## Outcome + +Document: + +- final read-path behavior +- fallback conditions +- validation results +- any remaining operational dependency for snapshot generation + +## 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.