73 lines
3.6 KiB
Markdown
73 lines
3.6 KiB
Markdown
# TASK-038-server-history-summary-cards
|
||
|
||
## Goal
|
||
Añadir al backend y al frontend una primera capa de métricas históricas resumidas para los servidores reales, de forma que el panel muestre información más útil que el simple último snapshot.
|
||
|
||
## Context
|
||
La web ya muestra snapshots reales A2S y dispone de histórico persistido. Sin embargo, el valor actual del panel sigue siendo limitado si solo enseña la última captura y una tendencia básica. El siguiente paso lógico es construir resúmenes históricos ligeros a partir de lo ya almacenado, sin convertir aún la landing en un dashboard complejo.
|
||
|
||
## Steps
|
||
1. Revisar los endpoints históricos actuales y el panel de servidores existente.
|
||
2. Identificar qué métricas históricas resumidas son viables con los snapshots ya persistidos, por ejemplo:
|
||
- última vez visto online
|
||
- número de capturas recientes
|
||
- promedio reciente de jugadores
|
||
- valor máximo reciente de población
|
||
- tiempo desde la última captura
|
||
3. Añadir la capa mínima necesaria en backend para exponer estas métricas de forma clara.
|
||
4. Integrar esas métricas en las tarjetas de servidores reales del frontend.
|
||
5. Mantener la mejora ligera y coherente con el diseño actual.
|
||
6. No introducir cálculos pesados ni analítica compleja.
|
||
7. Preservar el comportamiento correcto si aún hay pocos snapshots disponibles.
|
||
|
||
## Files to Read First
|
||
- AGENTS.md
|
||
- ai/repo-context.md
|
||
- backend/README.md
|
||
- backend/app/routes.py
|
||
- backend/app/payloads.py
|
||
- backend/app/storage.py
|
||
- frontend/index.html
|
||
- frontend/assets/js/main.js
|
||
- frontend/assets/css/styles.css
|
||
|
||
## Expected Files to Modify
|
||
- backend/app/routes.py
|
||
- backend/app/payloads.py
|
||
- backend/app/storage.py
|
||
- frontend/index.html
|
||
- frontend/assets/js/main.js
|
||
- frontend/assets/css/styles.css
|
||
|
||
## Constraints
|
||
- No rediseñar toda la landing.
|
||
- No añadir gráficas complejas.
|
||
- No introducir librerías nuevas.
|
||
- No romper el fallback actual.
|
||
- No hacer cambios destructivos.
|
||
- Mantener la mejora centrada en valor histórico resumido.
|
||
|
||
## Validation
|
||
- El backend expone métricas históricas resumidas útiles para servidores reales.
|
||
- El frontend las muestra de forma clara y legible.
|
||
- La UI sigue funcionando aunque el histórico disponible sea limitado.
|
||
- El panel gana valor funcional sin perder claridad.
|
||
|
||
## Change Budget
|
||
- Preferir menos de 6 archivos modificados.
|
||
- Preferir menos de 220 líneas cambiadas.
|
||
## Outcome
|
||
- `backend/app/storage.py` adjunta a cada snapshot más reciente un `history_summary` ligero con capturas recientes, promedio de jugadores, pico, última vez visto online y minutos desde la última captura.
|
||
- `backend/app/payloads.py` expone esas métricas en `GET /api/servers/latest` sin abrir un endpoint nuevo.
|
||
- `frontend/assets/js/main.js` integra las métricas resumidas en las tarjetas reales e históricas ya renderizadas por la landing.
|
||
- `frontend/assets/css/styles.css` añade el bloque visual compacto para mostrar esos resúmenes sin convertir la landing en un dashboard pesado.
|
||
|
||
## Validation Result
|
||
- Ejecutado: import directo de `build_server_latest_payload()` desde `backend/`.
|
||
- Resultado: el payload devuelve `history_summary` por servidor con valores coherentes incluso cuando hay pocas capturas disponibles.
|
||
- Ejecutado: `node --check frontend/assets/js/main.js`.
|
||
- Resultado: sintaxis JavaScript válida tras integrar el bloque de métricas resumidas.
|
||
|
||
## Decision Notes
|
||
- Las métricas históricas resumidas se calculan sobre una ventana corta de snapshots recientes y se entregan junto al payload de último estado para mantener el backend simple y evitar analÃtica o endpoints adicionales en esta fase.
|