Add annual ranking snapshot API

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

@@ -1,7 +1,7 @@
----
+---
 id: TASK-169-add-annual-ranking-snapshot-api
 title: Add annual ranking snapshot API
-status: pending
+status: done
 type: backend
 team: Backend Senior
 supporting_teams:
@@ -15,20 +15,20 @@ priority: medium
 
 ## Goal
 
-Exponer una API de lectura pública para el ranking anual top 20 precomputado desde snapshots almacenadas.
+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 módulo de generación (TASK-168) y las tablas añadidas por TASK-167.
+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 patrón de conexión compartido.
+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. Añadir payload y registro de ruta siguiendo patrones existentes.
-4. Validar comportamientos esperados (snapshot existente, faltante, métrica no soportada).
+3. Anadir payload y registro de ruta siguiendo patrones existentes.
+4. Validar comportamientos esperados (snapshot existente, faltante, metrica no soportada).
 
 ## Files to Read First
 
@@ -47,7 +47,6 @@ Mantiene compatibilidad entre SQLite y Postgres usando el patr
 
 ## Expected Files to Modify
 
-- `ai/tasks/pending/TASK-169-add-annual-ranking-snapshot-api.md` (al crear la tarea)
 - `backend/app/rcon_annual_rankings.py`
 - `backend/app/payloads.py`
 - `backend/app/routes.py`
@@ -65,17 +64,47 @@ Mantiene compatibilidad entre SQLite y Postgres usando el patr
 - 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 históricos salvo justificación imprescindible.
+- No modificar workers historicos salvo justificacion imprescindible.
 
 ## Validation
 
 - `python -m compileall backend/app`
 - `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
-- Validación manual del contrato con backend local o método equivalente.
+- Validacion manual del contrato con backend local o metodo equivalente.
 
 ## Outcome
 
-- registrar archivos modificados
-- validar comportamiento con y sin snapshot
-- indicar limitaciones conocidas
-- proponer siguiente tarea
+### 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.