chore: clean repo runtime artifacts

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

@@ -0,0 +1,96 @@
+# 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.