comunidadhll/ai/tasks/done/TASK-044-historical-snapshots-api.md

TASK-044-historical-snapshots-api

Goal

Exponer una API de snapshots historicos 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 periodicamente, el siguiente paso es exponer endpoints ligeros para que la UI historica lea directamente datos preparados.

Steps

1. Revisar la capa de snapshots ya creada y el runner de generacion.
2. Disenar endpoints claros para leer snapshots por servidor, tipo y metrica.
3. Cubrir como minimo:
   • resumen de servidor
   • tops semanales por metrica
   • partidas recientes
4. Asegurar que los endpoints devuelven tambien informacion util de actualizacion:
   • generated_at
   • rango fuente
   • stale/fresh si aplica
5. Mantener compatibilidad razonable con la UI historica ya existente o dejar clara la migracion.
6. Documentar los endpoints en backend.
7. No cambiar todavia toda la UI en esta task.
8. Al completar la implementacion:
   • 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 modulos de payload/query de snapshots

Constraints

• No usar A2S para esta capa.
• No hacer calculos pesados on-demand si ya existe snapshot valido.
• 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 actualizacion utiles.
• La capa esta 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 lineas cambiadas.

Outcome

• backend/app/routes.py expone endpoints ligeros de lectura para server-summary, weekly-leaderboard y recent-matches bajo /api/historical/snapshots/*.
• backend/app/payloads.py lee directamente historical_precomputed_snapshots con get_historical_snapshot(...) y devuelve payloads compatibles con frontend sin recalcular agregados historicos pesados.
• La metadata comun de snapshot incluye generated_at, source_range_start, source_range_end, is_stale, freshness y found.
• backend/README.md documenta los endpoints de snapshots y la metadata operativa disponible para frontend.

Validation Result

• Validado con python -m py_compile backend/app/routes.py backend/app/payloads.py backend/app/historical_snapshot_storage.py backend/app/historical_snapshots.py.
• Validado con resolve_get_payload(...) para:
  • /api/historical/snapshots/server-summary
  • /api/historical/snapshots/weekly-leaderboard
  • /api/historical/snapshots/recent-matches
• Validado con builders de payload en Python: los tres endpoints exponen freshness y responden de forma estable incluso cuando todavia no existe snapshot persistido, devolviendo found: False y estados vacios compatibles.
• Durante una validacion paralela aparecio un sqlite3.OperationalError: database is locked por inicializaciones concurrentes sobre la misma SQLite local; la validacion secuencial posterior paso correctamente sin requerir cambios de implementacion para esta task.
• Revisado en diff: la task queda limitada a backend/app/routes.py, backend/app/payloads.py, backend/README.md y este archivo de task.

Decision Notes

• Se mantuvieron intactos los endpoints historicos legacy (/api/historical/server-summary, /api/historical/weekly-leaderboard, /api/historical/recent-matches) para no romper consumidores existentes mientras la migracion a snapshots ocurre por separado.
• La capa de snapshots se resolvio como lectura directa de persistencia con recorte por limit sobre payload ya precalculado, evitando introducir nuevos calculos on-demand.