comunidadhll/ai/tasks/done/TASK-081-player-event-snapshots-and-api.md

TASK-081-player-event-snapshots-and-api

Goal

Exponer por snapshots JSON y API propia del backend las nuevas métricas derivadas V2 de eventos de jugador, manteniendo la filosofía de lectura rápida y desacoplada del request path pesado.

Context

La base V2 ya existe:

• source adapter
• raw ledger
• incremental worker
• derived aggregates

Ahora hace falta convertir esas métricas derivadas en una capa consumible por producto y por futuras fórmulas de MVP V2 sin depender de consultas pesadas on-demand.

Las primeras métricas que deben quedar listas para lectura rápida son:

• most_killed
• death_by
• duel summaries
• weapon kills
• teamkills derivados

Steps

1. Revisar los agregados V2 ya implementados.
2. Diseñar snapshots JSON adecuados para estas métricas avanzadas por:
   • servidor
   • all-servers cuando aplique
   • periodo mensual si corresponde
3. Exponer endpoints claros y consistentes para leer esas métricas.
4. Mantener la misma filosofía que el histórico actual:
   • lectura rápida
   • sin cálculos pesados en el request path
5. Incluir metadatos claros en los snapshots cuando aplique:
   • generated_at
   • period/month_key
   • source_range_start
   • source_range_end
   • found / is_stale si aplica
6. Integrar la generación de estos snapshots con la operativa existente o con una vía equivalente razonable.
7. No implementar todavía la UI V2 final.
8. No romper el MVP V1 ni los snapshots actuales.
9. 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_snapshots.py
• backend/app/historical_snapshot_storage.py
• backend/app/routes.py
• backend/app/payloads.py
• backend/app/player_event_aggregates.py
• backend/app/player_event_storage.py
• docs/player-event-pipeline-v2-design.md

Expected Files to Modify

• backend/app/routes.py
• backend/app/payloads.py
• backend/app/historical_snapshots.py
• backend/app/historical_snapshot_storage.py
• backend/README.md
• opcionalmente nuevos módulos auxiliares si mejoran claridad

Constraints

• No recalcular estas métricas pesadas en cada request.
• No romper la API histórica existente.
• No tocar todavía la UI final del MVP V2.
• No hacer cambios destructivos.
• Mantener el trabajo centrado en snapshots/API V2.

Validation

• Existen snapshots JSON de métricas V2.
• Existen endpoints backend para leerlas.
• La lectura es rápida y coherente con la arquitectura actual.
• No se rompe el MVP V1 ni el histórico actual.
• Los cambios quedan committeados y se hace push si el entorno lo permite.

Change Budget

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