70 lines
2.7 KiB
Markdown
70 lines
2.7 KiB
Markdown
# TASK-068-monthly-mvp-snapshots-and-api
|
|
|
|
## Goal
|
|
Exponer el ranking mensual MVP V1 mediante snapshots JSON y API propia del backend, siguiendo la misma filosofía rápida y estable ya usada por la capa histórica.
|
|
|
|
## Context
|
|
Una vez implementado el cálculo backend del monthly MVP, hace falta integrarlo en la capa de snapshots del proyecto para que:
|
|
- no dependa de cálculos pesados on-demand
|
|
- pueda servirse rápido a la UI
|
|
- sea consistente con el resto de la arquitectura histórica
|
|
|
|
## Steps
|
|
1. Revisar la implementación del cálculo mensual MVP y la arquitectura actual de snapshots JSON.
|
|
2. Diseñar la forma de snapshot para el ranking mensual MVP, tanto por servidor como para all-servers.
|
|
3. Generar snapshots JSON apropiados, por ejemplo:
|
|
- server monthly mvp
|
|
- all-servers monthly mvp
|
|
4. Incluir metadatos claros, como mínimo:
|
|
- generated_at
|
|
- source_range_start
|
|
- source_range_end
|
|
- freshness / is_stale si aplica
|
|
- month_key o periodo real usado
|
|
5. Exponer endpoints claros y consistentes para leer esos snapshots.
|
|
6. Mantener compatibilidad y coherencia con la API histórica existente.
|
|
7. Integrar el monthly MVP en el runner/generación periódica de snapshots si corresponde.
|
|
8. No crear todavía la UI final en esta task.
|
|
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/routes.py
|
|
- backend/app/payloads.py
|
|
- backend/app/historical_snapshots.py
|
|
- backend/app/historical_snapshot_storage.py
|
|
- backend/app/historical_runner.py
|
|
- backend/app/config.py
|
|
- docs/monthly-mvp-ranking-scoring-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/app/historical_runner.py
|
|
- backend/README.md
|
|
- opcionalmente nuevos módulos auxiliares si mejoran claridad
|
|
|
|
## Constraints
|
|
- No recalcular el ranking pesado en cada request de usuario.
|
|
- No romper snapshots históricos existentes.
|
|
- No crear todavía UI nueva en esta task.
|
|
- No hacer cambios destructivos.
|
|
- Mantener el trabajo centrado en snapshots y API del monthly MVP.
|
|
|
|
## Validation
|
|
- Existen snapshots JSON del monthly MVP para servidor y/o all-servers según diseño.
|
|
- Existen endpoints para leer esos snapshots.
|
|
- El monthly MVP se integra con la operativa de snapshots del proyecto.
|
|
- La respuesta es rápida y coherente con el resto de la API histórica.
|
|
- 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.
|