# TASK-044-historical-snapshots-api

## Goal
Exponer una API de snapshots históricos precalculados para que el frontend pueda consumir resumen, tops y partidas recientes sin disparar agregaciones costosas en tiempo real.

## Context
Con snapshots ya persistidos y generados periódicamente, el siguiente paso es exponer endpoints ligeros para que la UI histórica lea directamente datos preparados.

## Steps
1. Revisar la capa de snapshots ya creada y el runner de generación.
2. Diseñar endpoints claros para leer snapshots por servidor, tipo y métrica.
3. Cubrir como mínimo:
   - resumen de servidor
   - tops semanales por métrica
   - partidas recientes
4. Asegurar que los endpoints devuelven también información útil de actualización:
   - generated_at
   - rango fuente
   - stale/fresh si aplica
5. Mantener compatibilidad razonable con la UI histórica ya existente o dejar clara la migración.
6. Documentar los endpoints en backend.
7. No cambiar todavía toda la UI en esta task.
8. 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/routes.py
- backend/app/payloads.py
- backend/app/historical_snapshot_storage.py
- backend/app/historical_snapshots.py

## Expected Files to Modify
- backend/app/routes.py
- backend/app/payloads.py
- backend/README.md
- opcionalmente nuevos módulos de payload/query de snapshots

## Constraints
- No usar A2S para esta capa.
- No hacer cálculos pesados on-demand si ya existe snapshot válido.
- No crear UI nueva en esta task.
- No hacer cambios destructivos.
- Mantener el trabajo centrado en una API ligera de snapshots.

## Validation
- Existen endpoints de snapshots para resumen, tops y partidas recientes.
- Los payloads incluyen metadatos de actualización útiles.
- La capa está lista para que la UI deje de depender de agregados pesados en tiempo real.
- Los cambios quedan committeados y se hace push al remoto si el entorno lo permite.

## Change Budget
- Preferir menos de 5 archivos modificados o creados.
- Preferir menos de 220 líneas cambiadas.