comunidadhll/ai/tasks/pending/TASK-191-serve-ranking-from-snapshots-with-runtime-fallback.md

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

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-191-serve-ranking-from-snapshots-with-runtime-fallback	Serve ranking from snapshots with runtime fallback	pending	backend	Backend Senior	Arquitecto de Base de Datos Arquitecto Python	foundation	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.