comunidadhll/ai/tasks/done/TASK-042-historical-snapshots-storage-and-model.md

TASK-042-historical-snapshots-storage-and-model

Goal

Diseñar e implementar una capa de almacenamiento de snapshots históricos precalculados para el proyecto, preparada para servir rápidamente resumen, rankings y partidas recientes sin recalcular agregados pesados en tiempo real.

Context

La página histórica ya funciona, pero parte de la información puede requerir agregaciones costosas si se calculan en el momento de cada carga o al cambiar de pestaña. El objetivo es introducir una capa de snapshots precalculados y persistidos que permita responder de forma rápida y estable. Esto debe incluir no solo el resumen del servidor, sino también los tops/rankings semanales.

Steps

1. Revisar la estructura histórica actual y los endpoints/API que hoy calculan resumen, rankings y partidas recientes.
2. Diseñar un modelo de snapshot persistido que soporte, como mínimo:
   • resumen de servidor
   • top kills semanales
   • top muertes semanales
   • top partidas con más de 100 kills por jugador
   • top puntos de soporte semanales
   • partidas recientes
3. Definir para cada snapshot metadatos claros, por ejemplo:
   • server_key
   • snapshot_type
   • metric
   • window
   • payload_json
   • generated_at
   • source_range_start
   • source_range_end
   • is_stale
4. Implementar el almacenamiento local de snapshots de forma coherente con la persistencia histórica actual.
5. Documentar la estructura y propósito de esta nueva capa.
6. No migrar todavía toda la UI a snapshots en esta task.
7. Al completar la implementación:
   • dejar el repositorio consistente
   • hacer commit
   • hacer push al remoto si el entorno lo permite

Files to Read First

• AGENTS.md
• backend/README.md
• backend/app/historical_models.py
• backend/app/historical_storage.py
• backend/app/payloads.py
• backend/app/routes.py
• docs/historical-domain-model.md

Expected Files to Modify

• backend/README.md
• backend/app/historical_models.py
• backend/app/historical_storage.py
• opcionalmente nuevos módulos, por ejemplo:
  • backend/app/historical_snapshots.py
  • backend/app/historical_snapshot_storage.py
• opcionalmente documentación técnica adicional

Constraints

• No basar esta capa en A2S.
• No crear todavía nueva UI en esta task.
• No hacer cambios destructivos.
• Mantener el trabajo centrado en almacenamiento y modelo de snapshots.

Validation

• Existe un modelo de snapshot persistido claro.
• El modelo cubre resumen, rankings y partidas recientes.
• La estructura está lista para ser rellenada periódicamente.
• Los cambios quedan committeados y se hace push al remoto si el entorno lo permite.

Change Budget

• Preferir menos de 6 archivos modificados o creados.
• Preferir menos de 220 líneas cambiadas.