comunidadhll/ai/tasks/done/TASK-030-historical-snapshot-quality-pass.md

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.