Document annual ranking snapshot schema plan

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

@@ -0,0 +1,104 @@
+---
+id: TASK-166
+title: Design annual ranking snapshot schema
+status: done
+type: documentation
+team: Arquitecto de Base de Datos
+supporting_teams: []
+roadmap_item: foundation
+priority: 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.