rgonsal/comunidadhll
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

sistema A2S

Browse Source
This commit is contained in:
devRaGonSa
2026-03-20 14:38:57 +01:00
parent a82a90a1b4
commit 87c1f4e8c3
75 changed files with 7625 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
ai/tasks/done/TASK-030-historical-snapshot-quality-pass.md Normal file
View File

@@ -0,0 +1,84 @@
# TASK-030-historical-snapshot-quality-pass
## Goal
Revisar y ajustar la calidad de los snapshots persistidos tras la primera captura A2S real, asegurando consistencia de datos, timestamps, procedencia y utilidad de cara a historico y visualizacion.
## Context
Una vez incorporado el target real y validada una primera captura, el siguiente paso es comprobar la calidad del dato persistido. No basta con guardar snapshots; deben ser consistentes y utiles para construir historico, estadisticas y visualizacion sin ruido innecesario.
## Steps
1. Revisar snapshots persistidos a partir de la captura real de Comunidad Hispana #01.
2. Verificar consistencia de campos clave:
- nombre del servidor
- host o referencia de origen
- timestamp
- mapa actual
- jugadores
- capacidad
- fuente efectiva
3. Revisar si hay problemas de calidad como:
- duplicados innecesarios
- timestamps incoherentes
- normalizacion deficiente
- mezcla poco clara entre fallback y captura real
4. Ajustar la capa de persistencia, normalizacion o payloads si fuera necesario para mejorar claridad.
5. Revisar el impacto en endpoints historicos existentes:
- `/api/servers/latest`
- `/api/servers/history`
- `/api/servers/{id}/history`
6. Mantener el cambio centrado en calidad y coherencia del historico, no en nuevas visualizaciones.
7. Actualizar documentacion minima si el modelo efectivo de snapshot cambia ligeramente.
## Files to Read First
- AGENTS.md
- ai/repo-context.md
- ai/architecture-index.md
- backend/README.md
- backend/app/collector.py
- backend/app/normalizers.py
- backend/app/storage.py
- backend/app/routes.py
- backend/app/payloads.py
- datos persistidos generados en la task anterior
## Expected Files to Modify
- backend/app/normalizers.py
- backend/app/storage.py
- backend/app/routes.py
- backend/app/payloads.py
- backend/README.md
- opcionalmente documentacion tecnica relacionada si la claridad del historico necesita ajuste
## Constraints
- No tocar frontend en esta task.
- No anadir nuevas fuentes externas.
- No introducir complejidad analitica alta.
- No hacer cambios destructivos.
- Mantener el resultado centrado en calidad de datos historicos.
## Validation
- Los snapshots reales persistidos son consistentes y utiles.
- Los endpoints historicos reflejan correctamente el dato real almacenado.
- La distincion entre captura real y fallback queda razonablemente clara.
- El backend queda listo para una siguiente task de mejora visual o estadistica sobre datos reales.
## Change Budget
- Preferir menos de 5 archivos modificados.
- Preferir menos de 180 lineas cambiadas.
## Outcome
- `backend/app/normalizers.py` anade `snapshot_origin` y `source_ref` al modelo normalizado para que la procedencia no se infiera de forma ambigua en historico.
- `backend/app/snapshots.py` conserva esos campos en cada snapshot persistible.
- `backend/app/storage.py` migra la tabla SQLite sin destruir datos, serializa ambos campos en las consultas historicas y backfilla referencias A2S registradas para snapshots ya existentes.
- `backend/README.md` documenta los nuevos metadatos historicos y el valor esperado para la captura real de Comunidad Hispana #01.
## Validation Result
- Ejecutado: lectura de `list_latest_snapshots()`, `list_snapshot_history()` y `list_server_history('comunidad-hispana-01')` desde Python.
- Resultado: los snapshots historicos exponen `snapshot_origin` con `real-a2s` o `controlled-fallback` y `source_ref` coherente.
- Ejecutado fuera del sandbox: `python -m app.collector --source a2s --no-fallback`.
- Resultado: nuevo snapshot real persistido con `source_ref=a2s://152.114.195.174:7778`, `current_map=Remagen`, `players=0`, `max_players=100`.
- Endpoints verificados: `/api/servers/latest`, `/api/servers/history` y `/api/servers/{id}/history` devuelven el snapshot real mas reciente con la nueva metadata de procedencia.
## Decision Notes
- No se tocaron `routes.py` ni `payloads.py` porque ya reutilizan directamente los registros serializados de almacenamiento y heredaron la mejora sin cambios de contrato adicionales.
- No se introdujo deduplicacion agresiva de snapshots porque dos capturas reales con distinto `captured_at` siguen siendo historico valido; el ajuste se centro en claridad y consistencia de procedencia.