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

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

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-173	Add annual ranking snapshot runbook	done	documentation	PM	Backend Senior Frontend Senior Arquitecto de Base de Datos	foundation	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.