comunidadhll/ai/tasks/done/TASK-166-design-annual-ranking-snapshot-schema.md

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

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-166	Design annual ranking snapshot schema	done	documentation	Arquitecto de Base de Datos		foundation	medium

TASK-166 - Design annual ranking snapshot schema

Goal

Define a backend storage plan for annual top-20 ranking snapshots (kills) that avoids full recalculation on each public request.

Context

• TASK-162 implementó el endpoint de búsqueda de jugadores para Stats.
• TASK-163 implementó el endpoint de stats personales.
• TASK-165 implementó la vista frontend de Stats.

This task is documentation-only and prepares the schema needed by the next backend endpoint iteration:

• GET /api/stats/rankings/annual?year=<year>&server_id=<server-or-all>&metric=kills

Steps

1. Revisión de archivos listados en Files to Read First.
2. Diseñar propuesta de tablas para snapshots anuales y sus items.
3. Definir restricciones de unicidad, índices y política de reemplazo.
4. Documentar compatibilidad SQLite/Postgres siguiendo el patrón usado en rcon_historical_leaderboards.py.
5. Especificar API y estados esperados para lectura de snapshot.

Files to Read First

• AGENTS.md
• ai/repo-context.md
• ai/architecture-index.md
• docs/stats-section-functional-plan.md
• docs/stats-frontend-integration-plan.md
• backend/app/rcon_historical_leaderboards.py
• backend/app/rcon_historical_player_stats.py
• backend/app/rcon_admin_log_materialization.py
• backend/app/postgres_rcon_storage.py
• backend/app/postgres_display_storage.py
• backend/app/sqlite_to_postgres_migration.py

Expected Files to Modify

• ai/tasks/done/TASK-166-design-annual-ranking-snapshot-schema.md
• docs/annual-ranking-snapshot-schema-plan.md

Constraints

• No migrations in this task.
• No backend implementation code changes in this task.
• No frontend changes in this task.
• No Elo/MMR reactivation.
• No Comunidad Hispana #03 reintroduction.
• No modification of historical workers.
• No touch to:
  • frontend/assets/js/partida-actual.js
  • frontend/assets/img/clans/bxb.png

Validation

• Confirm only documentation files were created/updated.
• git diff --name-only must match expected scope.
• Document that no automated tests are applicable for documentation-only task.

Outcome

• Documento creado:
  • docs/annual-ranking-snapshot-schema-plan.md
• Archivos revisados:
  • AGENTS.md
  • ai/repo-context.md
  • ai/architecture-index.md
  • docs/stats-section-functional-plan.md
  • docs/stats-frontend-integration-plan.md
  • backend/app/rcon_historical_leaderboards.py
  • backend/app/rcon_historical_player_stats.py
  • backend/app/rcon_admin_log_materialization.py
  • backend/app/postgres_rcon_storage.py
  • backend/app/postgres_display_storage.py
  • backend/app/sqlite_to_postgres_migration.py
• Validación realizada:
  • Confirmado que la tarea quedó en alcance documental y no se introdujeron cambios de backend/frontend.
  • Se validó que los únicos archivos esperados para esta tarea estén cubiertos por su documentación.
  • No se requiere ejecutar pruebas automáticas: es una tarea de documentación.
• Limitaciones:
  • No se tocó código backend ni frontend.
  • No se ejecutaron migraciones.
• Siguiente task recomendada:
  • Crear migración y estructura de persistencia para snapshots anuales de ranking (rcon_annual_ranking_*) y su job de generación.

Change Budget

• Prefer fewer than 5 modified files.
• Keep changes concise and reviewable.