114 lines
4.0 KiB
Markdown
114 lines
4.0 KiB
Markdown
---
|
|
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.
|