comunidadhll/ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md

TASK-021-server-status-periodic-query-and-display

Goal

Implementar una base funcional para consultar periódicamente el estado de los servidores y mostrar esos datos en la página, realizando snapshots de datos cada 2 minutos, sin usar capturas de imagen ni elementos manuales equivalentes.

Context

Queda descartada cualquier idea de “captura manual” o de imagen estática para representar el estado de los servidores. Lo que se necesita es mostrar en la web la situación actual de los servidores mediante consultas de datos reales o semirrealistas desde backend. En esta fase, la web debe evolucionar hacia un modelo donde el backend consulta periódicamente la información de servidores, conserva el último snapshot útil y el frontend lo muestra de forma clara.

Steps

1. Revisar el endpoint actual GET /api/servers y su implementación placeholder.
2. Revisar cómo se muestra actualmente el bloque de servidores en la landing.
3. Diseñar e implementar una base de consulta periódica de datos de servidores con una frecuencia objetivo de 2 minutos.
4. Hacer que el backend obtenga y conserve snapshots de datos con los campos necesarios para la UI. Incluir al menos:
   • nombre del servidor
   • estado online/offline
   • jugadores actuales
   • capacidad máxima
   • mapa actual si está disponible
   • región o etiqueta útil si existe
   • timestamp real del último snapshot de datos
5. Dejar claro en la implementación y en la UI que se trata de datos de estado de servidores, no de capturas de imagen.
6. Hacer que GET /api/servers devuelva el último snapshot útil con una estructura estable y preparada para frontend.
7. Ajustar el frontend para mostrar esos datos de forma clara en la landing.
8. Si el backend no puede obtener datos nuevos temporalmente, mantener el último snapshot válido o un fallback coherente sin romper la página.
9. Mostrar en la UI una referencia honesta del momento de actualización basada en datos reales del snapshot, no en texto ficticio.
10. Mantener el alcance razonable: consultas periódicas y presentación de datos, sin abrir todavía automatizaciones más complejas de observabilidad o infraestructura.

Files to Read First

• AGENTS.md
• ai/repo-context.md
• ai/architecture-index.md
• docs/frontend-backend-contract.md
• docs/discord-and-server-data-plan.md
• docs/current-hll-servers-source-plan.md
• backend/README.md
• backend/app/init.py
• backend/app/main.py
• backend/app/routes.py
• backend/app/payloads.py
• backend/app/config.py
• frontend/index.html
• frontend/assets/js/main.js
• frontend/assets/css/styles.css

Expected Files to Modify

• backend/app/main.py
• backend/app/routes.py
• backend/app/payloads.py
• backend/app/config.py
• opcionalmente uno o más archivos nuevos de servicio dentro de backend/app/, por ejemplo:
  • backend/app/server_status_service.py
  • backend/app/server_queries.py
• frontend/index.html
• frontend/assets/js/main.js
• frontend/assets/css/styles.css
• backend/README.md
• opcionalmente documentación técnica si fuera necesario alinear el comportamiento real

Constraints

• No usar capturas de imagen para representar el estado de servidores.
• No introducir texto temporal ficticio.
• No consultar fuentes externas directamente desde frontend.
• Mantener la arquitectura frontend → backend → fuente de datos.
• No romper el fallback actual si no hay datos disponibles.
• No hacer cambios destructivos.
• Mantener la solución clara, trazable y coherente con la fase del proyecto.

Validation

• Existe una base de consulta periódica con objetivo de refresco cada 2 minutos.
• GET /api/servers devuelve un snapshot de datos de servidores con timestamp real del snapshot.
• La landing muestra esos datos en lugar de una “captura” manual o ficticia.
• Si falla la actualización, la web no se rompe.
• La UI muestra de forma honesta la actualización real del estado de servidores.
• No se introducen capturas de imagen como solución del problema.

Change Budget

• Preferir menos de 8 archivos modificados o creados.
• Preferir menos de 320 líneas cambiadas.

Outcome

• backend/app/payloads.py hace que GET /api/servers devuelva un snapshot coherente preparado para frontend: prioriza el ultimo snapshot A2S real persistido cuando existe y, si no existe ninguno, responde un respaldo controlado con last_snapshot_at.
• backend/app/config.py alinea la frecuencia objetivo de refresco local a 120 segundos.
• frontend/assets/js/main.js deja de depender de una segunda llamada a /api/servers/latest para el bloque principal y pinta directamente el snapshot devuelto por /api/servers, mostrando un estado honesto con timestamp real del snapshot.
• frontend/index.html ajusta el polling por defecto a 120000 ms y aclara que el bloque muestra snapshots de estado consultados desde backend.
• backend/README.md documenta el nuevo comportamiento de /api/servers y el intervalo de 120 segundos.

Validation Result

• Validado con python -m py_compile backend/app/config.py backend/app/payloads.py backend/app/routes.py backend/app/main.py.
• Validado con node --check frontend/assets/js/main.js.
• Validado con python -m app.collector --source controlled, que persistio un snapshot controlado en backend/data/hll_vietnam_dev.sqlite3.
• Validado inspeccionando build_servers_payload() desde Python para confirmar que /api/servers devuelve last_snapshot_at e items listos para frontend.
• Revisado en diff: la task queda limitada a backend/README.md, backend/app/config.py, backend/app/payloads.py, frontend/assets/js/main.js, frontend/index.html, este archivo de task y la actualizacion de backend/data/hll_vietnam_dev.sqlite3 causada por la validacion persistente.

Decision Notes

• Se reutilizo la infraestructura de snapshots ya existente en lugar de introducir otro scheduler o un segundo endpoint principal para el estado visible en landing.
• /api/servers devuelve un unico conjunto coherente de items para evitar mezclar timestamps de fallback con tarjetas reales A2S en la UI.