Add annual ranking snapshot runbook

ai/tasks/done/TASK-173-add-annual-ranking-snapshot-runbook.md

@@ -0,0 +1,121 @@
+---
+id: TASK-173
+title: Add annual ranking snapshot runbook
+status: done
+type: documentation
+team: PM
+supporting_teams: [Backend Senior, Frontend Senior, Arquitecto de Base de Datos]
+roadmap_item: foundation
+priority: medium
+---
+
+# TASK-173 - Add annual ranking snapshot runbook
+
+## Goal
+
+Documentar la operacion del ranking anual top 20 para la seccion Stats: como generar, regenerar y validar usando snapshots precomputados para evitar recalcular anualmente en cada request.
+
+## Context
+
+TASK-173 define el proceso operativo para el bloque anual de Stats que consume:
+
+- `GET /api/stats/rankings/annual?year=<year>&server_id=<server-or-all>&metric=kills&limit=20`
+
+El documento mantiene alcance documentación-only y reitera que la fuente preferente es RCON materializado.
+
+## Steps
+
+1. Revisar archivos obligatorios indicados en la task.
+2. Crear/actualizar runbook sin tocar backend ni frontend.
+3. Documentar fuente, comandos, validaciones y casos esperados.
+
+## Files to Read First
+
+- AGENTS.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- docs/stats-section-functional-plan.md
+- backend/app/rcon_annual_rankings.py
+- backend/app/routes.py
+- frontend/assets/js/stats.js
+- ai/tasks/done/TASK-170-connect-annual-ranking-snapshot-to-stats-frontend.md
+- ai/tasks/done/TASK-171-validate-stats-section-with-backend-data.md
+- ai/tasks/done/TASK-172-polish-stats-section-empty-states-and-copy.md
+
+## Expected Files to Modify
+
+- `docs/annual-ranking-snapshot-runbook.md`
+- `ai/tasks/done/TASK-173-add-annual-ranking-snapshot-runbook.md`
+
+## Constraints
+
+- Documentacion-only.
+- No modificar backend.
+- No modificar frontend.
+- No crear migraciones.
+- No cambiar scripts salvo que exista comando explícito y se limite a documentación.
+- No tocar:
+  - `frontend/assets/js/partida-actual.js`
+  - `frontend/assets/img/clans/bxb.png`
+- Mantener restricciones funcionales:
+  - no reactivar Elo/MMR
+  - no reintroducir Comunidad Hispana #03
+
+## Validation
+
+- Confirmar que `docs/annual-ranking-snapshot-runbook.md` existe.
+- Ejecutar `git diff --name-only`.
+- Validar alcance esperado de archivos modificados.
+- Si no hay test automáticos por ser documentación-only, documentarlo en Outcome.
+
+## Outcome
+
+### Status
+
+Done
+
+### Files modified
+
+- `docs/annual-ranking-snapshot-runbook.md`
+- `ai/tasks/done/TASK-173-add-annual-ranking-snapshot-runbook.md`
+
+### Documentation created
+
+- Runbook creado en `docs/annual-ranking-snapshot-runbook.md` con:
+  - propósito del snapshot anual top 20,
+  - fuente de datos materializada RCON (`rcon_materialized_matches`, `rcon_match_player_stats`) y filtro `source_basis=admin-log-match-ended`,
+  - endpoint consumidor `GET /api/stats/rankings/annual?...`,
+  - pasos de generacion y regeneracion,
+  - validacion de existencia,
+  - validacion desde API y desde frontend Stats,
+  - casos esperados:
+    - `snapshot_status="ready"` con items,
+    - `snapshot_status="ready"` vacío,
+    - `snapshot_status="missing"`,
+    - metrica no soportada en V1.
+  - alertas:
+    - no recalcular ranking anual por request público,
+    - no usar scoreboard publico como fuente primaria si RCON disponible,
+    - no reintroducir Elo/MMR,
+    - no reintroducir Comunidad Hispana #03.
+
+### Validacion
+
+- Confirmado que `docs/annual-ranking-snapshot-runbook.md` existe.
+- `git diff --name-only` y `git status --short --untracked-files=all` revisados para validar alcance.
+- Esta tarea es documentación-only; no aplica tests automáticos.
+
+### Limitaciones conocidas
+
+- No se cambian scripts ni operaciones de mantenimiento en esta tarea.
+- No se realizan cambios de backend/frontend.
+
+### Siguiente task recomendada
+
+- Automatizar la ejecucion del generador anual (cron/manual) y capturar artefactos de operador.
+
+## Change Budget
+
+- Prefer < 5 files.
+- Prefer cambios acotados y revisables.
+- Mantener doc corta y accionable.