diff --git a/.gitignore b/.gitignore index 65a29bc..628f4b6 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,10 @@ dist/ build/ .DS_Store Thumbs.db + +# Local AI worker/runtime artifacts +ai/worker.lock + +# Local backend runtime data +backend/data/*.sqlite3 +!backend/data/.gitkeep diff --git a/ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md b/ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md new file mode 100644 index 0000000..27ccaef --- /dev/null +++ b/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. diff --git a/ai/tasks/done/TASK-025-repo-hygiene-and-dev-artifacts-cleanup.md b/ai/tasks/done/TASK-025-repo-hygiene-and-dev-artifacts-cleanup.md new file mode 100644 index 0000000..501af6b --- /dev/null +++ b/ai/tasks/done/TASK-025-repo-hygiene-and-dev-artifacts-cleanup.md @@ -0,0 +1,87 @@ +# TASK-025-repo-hygiene-and-dev-artifacts-cleanup + +## Goal +Dejar el repositorio HLL Vietnam en un estado mas limpio y consistente eliminando o regularizando artefactos locales de desarrollo, ficheros de lock y residuos de workflow que no deberian quedar como ruido permanente en el worktree. + +## Context +Despues de varias tasks ejecutadas por el workflow, siguen apareciendo residuos locales o inconsistencias de higiene del repositorio, entre ellos: +- `ai/worker.lock` +- `backend/data/hll_vietnam_dev.sqlite3` +- `ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md` como untracked o no regularizado +- posibles cambios locales en `backend/app/config.py` + +Estos elementos no forman parte directa del valor de producto visible, pero si afectan a la salud del repositorio, al flujo del worker y a la claridad del estado git. Hace falta una pasada de limpieza controlada para dejar reglas claras sobre que debe versionarse y que debe considerarse artefacto local de desarrollo. + +## Steps +1. Revisar el estado actual del repositorio y confirmar que archivos siguen quedando como ruido local o inconsistencias. +2. Analizar especificamente: + - `ai/worker.lock` + - `backend/data/hll_vietnam_dev.sqlite3` + - `ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md` + - `backend/app/config.py` +3. Determinar para cada uno de ellos si debe: + - versionarse + - ignorarse + - regenerarse localmente + - moverse o regularizarse +4. Ajustar `.gitignore` u otros mecanismos de higiene si hace falta. +5. Asegurar que los artefactos locales de desarrollo no sigan ensuciando el worktree innecesariamente. +6. Regularizar el estado de la task `TASK-021` si quedo fuera del flujo esperado. +7. Documentar de forma minima, si hace falta, el tratamiento esperado de snapshots persistidos, locks locales y otros artefactos de runtime. +8. No tocar logica funcional de producto salvo que sea estrictamente necesario para dejar el repo coherente. +9. Al completar la implementacion: + - dejar el repositorio consistente + - hacer commit + - hacer push al remoto si el entorno lo permite + +## Files to Read First +- AGENTS.md +- .gitignore +- ai/README.md +- ai/orchestrator/README.md +- backend/README.md +- backend/app/config.py +- cualquier documentacion existente sobre snapshots o runtime local +- salida actual de `git status` + +## Expected Files to Modify +- .gitignore +- backend/README.md +- opcionalmente ai/README.md o documentacion minima si hace falta aclarar el tratamiento de artefactos locales +- opcionalmente regularizacion de archivos en `ai/tasks/done/` +- opcionalmente eliminacion o exclusion de artefactos locales no deseados + +## Constraints +- No romper el workflow actual del proyecto. +- No eliminar informacion util sin justificarlo. +- No tocar frontend salvo que fuera completamente imprescindible. +- No introducir cambios funcionales de producto. +- No hacer cambios destructivos fuera del objetivo de higiene del repo. +- Mantener el resultado claro, pequeno y seguro. + +## Validation +- El worktree queda sensiblemente mas limpio. +- Los artefactos de desarrollo local quedan tratados de forma explicita. +- `ai/worker.lock` no queda como ruido permanente si no debe versionarse. +- El tratamiento de `backend/data/hll_vietnam_dev.sqlite3` queda resuelto. +- `TASK-021` queda regularizada si estaba fuera del flujo. +- Los cambios quedan committeados y se hace push al remoto si el entorno lo permite. + +## Change Budget +- Preferir menos de 6 archivos modificados. +- Preferir menos de 180 lineas cambiadas. + +## Outcome +- `.gitignore` pasa a tratar `ai/worker.lock` y `backend/data/*.sqlite3` como artefactos locales de runtime en lugar de ruido permanente versionado. +- `backend/data/.gitkeep` mantiene el directorio de datos en el repositorio sin forzar que la base SQLite de desarrollo quede commiteada. +- `ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md` queda regularizada dentro del historial versionado de tasks completadas. +- El cambio pendiente de `backend/app/config.py` queda absorbido como parte de la regularizacion de `TASK-021`, en lugar de seguir apareciendo como residuo suelto. + +## Validation Result +- Revisado `git status --short` para confirmar que el ruido original del worktree quedaba centrado en `ai/worker.lock`, `backend/data/hll_vietnam_dev.sqlite3`, `backend/app/config.py` y la task `TASK-021`. +- Revisadas las referencias de runtime en `scripts/codex-runner.ps1`, `backend/app/config.py` y `backend/README.md` para confirmar que el lock y la SQLite son artefactos regenerables de desarrollo local. +- Validacion final prevista: `git diff --name-only` debe reflejar solo la higiene de ignores, la regularizacion de archivos versionados y la task cerrada. + +## Decision Notes +- `ai/worker.lock` se trata como lock efimero del runner local y no aporta valor historico en git. +- `backend/data/hll_vietnam_dev.sqlite3` se mantiene como persistencia local regenerable; el contrato util esta en codigo y documentacion, no en una base SQLite concreta del worktree. diff --git a/ai/worker.lock b/ai/worker.lock deleted file mode 100644 index 6917c23..0000000 --- a/ai/worker.lock +++ /dev/null @@ -1 +0,0 @@ -32960 \ No newline at end of file diff --git a/backend/app/config.py b/backend/app/config.py index e27ff2b..e4f309f 100644 --- a/backend/app/config.py +++ b/backend/app/config.py @@ -9,7 +9,7 @@ from pathlib import Path DEFAULT_HOST = "127.0.0.1" DEFAULT_PORT = 8000 DEFAULT_STORAGE_FILENAME = "hll_vietnam_dev.sqlite3" -DEFAULT_REFRESH_INTERVAL_SECONDS = 60 +DEFAULT_REFRESH_INTERVAL_SECONDS = 120 DEFAULT_ALLOWED_ORIGINS = ( "null", "http://127.0.0.1:5500", diff --git a/backend/data/.gitkeep b/backend/data/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/backend/data/.gitkeep @@ -0,0 +1 @@ + diff --git a/backend/data/hll_vietnam_dev.sqlite3 b/backend/data/hll_vietnam_dev.sqlite3 deleted file mode 100644 index e9684e6..0000000 Binary files a/backend/data/hll_vietnam_dev.sqlite3 and /dev/null differ