comunidadhll/ai/tasks/done/TASK-169-add-annual-ranking-snapshot-api.md

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

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-169-add-annual-ranking-snapshot-api	Add annual ranking snapshot API	done	backend	Backend Senior	Arquitecto Python Arquitecto de Base de Datos	foundation	medium

TASK-169-add-annual-ranking-snapshot-api

Goal

Exponer una API de lectura publica para el ranking anual top 20 precomputado desde snapshots almacenadas.

Context

La API debe consumir rcon_annual_ranking_snapshots y rcon_annual_ranking_snapshot_items generados por el modulo de generacion (TASK-168) y las tablas añadidas por TASK-167.

Mantiene compatibilidad entre SQLite y Postgres usando el patron de conexion compartido.

Steps

1. Leer los archivos indicados en "Files to Read First".
2. Implementar el endpoint GET /api/stats/rankings/annual en backend sin recalcular ranking.
3. Anadir payload y registro de ruta siguiendo patrones existentes.
4. Validar comportamientos esperados (snapshot existente, faltante, metrica no soportada).

Files to Read First

• AGENTS.md
• ai/repo-context.md
• ai/architecture-index.md
• docs/annual-ranking-snapshot-schema-plan.md
• docs/stats-section-functional-plan.md
• backend/app/rcon_annual_rankings.py
• backend/app/rcon_historical_leaderboards.py
• backend/app/rcon_historical_player_stats.py
• backend/app/routes.py
• backend/app/payloads.py
• backend/app/rcon_admin_log_materialization.py
• backend/app/postgres_rcon_storage.py

Expected Files to Modify

• backend/app/rcon_annual_rankings.py
• backend/app/payloads.py
• backend/app/routes.py

Constraints

• Endpoint: GET /api/stats/rankings/annual?year=<year>&server_id=<server-or-all>&metric=kills&limit=<n>
• server_id opcional, all por defecto.
• metric por ahora solo kills.
• limit opcional, por defecto 20, validado razonablemente.
• Si no existe snapshot debe responder snapshot_status="missing" con items=[] y estado HTTP 200.
• No generar snapshot en el endpoint.
• Mantener compatibilidad SQLite/Postgres.
• No tocar frontend.
• No tocar frontend/assets/js/partida-actual.js ni frontend/assets/img/clans/bxb.png.
• No reactivar Elo/MMR.
• No incluir Comunidad Hispana #03.
• No modificar workers historicos salvo justificacion imprescindible.

Validation

• python -m compileall backend/app
• powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1
• Validacion manual del contrato con backend local o metodo equivalente.

Outcome

Files modified

• backend/app/rcon_annual_rankings.py
• backend/app/payloads.py
• backend/app/routes.py

Endpoint created

• GET /api/stats/rankings/annual?year=<year>&server_id=<server-or-all>&metric=kills&limit=<n>
• Respuestas:
  • snapshot_status=ready cuando existe snapshot.
  • snapshot_status=missing cuando no existe snapshot, y devuelve items=[].
• Soporta metric=kills y devuelve 400 para metricas no soportadas.

Validations performed

• python -m compileall backend/app ✅
• powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1 ✅
• Validacion manual usando app.routes.resolve_get_payload:
  • /api/stats/rankings/annual (HTTP 200, respuesta OK)
  • /api/stats/rankings/annual?year=1990 (HTTP 200)
  • /api/stats/rankings/annual?year=1990&metric=kills&limit=3 (HTTP 200)
  • /api/stats/rankings/annual?metric=deaths (HTTP 400, metrica invalida)
  • /api/stats/rankings/annual?year=1900 (HTTP 200, snapshot_status missing, items=[])

Limitations

• Soporta solo metric=kills en esta fase.
• Endpoint no genera snapshots (no recalculo); requiere que TASK-168 haya generado datos.
• No se toco frontend en este alcance.

Next task recommendation

Conectar ranking anual top 20 desde frontend Stats.