comunidadhll/ai/tasks/done/TASK-021-snapshot-persistence-bootstrap.md

TASK-021-snapshot-persistence-bootstrap

Goal

Preparar una persistencia local minima para snapshots de servidores en el backend Python, de forma que los datos recogidos durante las pruebas con HLL actual puedan guardarse y reutilizarse para consultas historicas posteriores.

Context

El proyecto ya dispone de plan de ingesta, modelo logico de almacenamiento y bootstrap de colector. El siguiente paso es dejar de depender exclusivamente de estructuras temporales o payloads controlados y empezar a guardar snapshots de forma persistente para validar el circuito real de estadisticas.

Steps

1. Revisar la documentacion actual de ingesta, esquema logico y colector.
2. Definir una estrategia de persistencia local minima adecuada para esta fase de pruebas.
3. Implementar una capa pequena de persistencia alineada con las entidades ya definidas logicamente:
   • game_sources
   • servers
   • server_snapshots
4. Mantener la implementacion simple, reutilizable y desacoplada de una base de datos de produccion futura.
5. Hacer que el colector pueda guardar snapshots reales o controlados en esa persistencia local.
6. Documentar como inicializar y usar esta persistencia en desarrollo.
7. No introducir todavia consultas historicas complejas ni visualizacion en frontend.
8. Mantener el alcance centrado en almacenamiento basico funcional.

Files to Read First

• AGENTS.md
• ai/repo-context.md
• ai/architecture-index.md
• docs/current-hll-data-ingestion-plan.md
• docs/stats-database-schema-foundation.md
• backend/README.md
• backend/app/init.py
• backend/app/config.py
• backend/app/collector.py
• backend/app/normalizers.py
• backend/app/snapshots.py

Expected Files to Modify

• backend/README.md
• backend/app/init.py
• backend/app/config.py
• backend/app/collector.py
• backend/app/snapshots.py
• opcionalmente archivos nuevos dentro de backend/app/ si mejoran la separacion de persistencia, por ejemplo:
  • backend/app/storage.py
  • backend/app/repository.py

Constraints

• No implementar todavia integraciones reales complejas de terceros.
• No tocar frontend.
• No anadir una infraestructura de produccion sobredimensionada.
• No hacer cambios destructivos.
• Mantener la persistencia simple y util para desarrollo local.

Validation

• El backend puede guardar snapshots de servidores en una persistencia local real.
• La persistencia sigue el modelo logico documentado.
• La documentacion explica como usar esta base minima en local.
• El resultado prepara el terreno para consultas historicas inmediatas.

Change Budget

• Preferir menos de 7 archivos modificados o creados.
• Preferir menos de 260 lineas cambiadas.

Outcome

• Se anadio backend/app/storage.py con una persistencia SQLite minima basada en libreria estandar.
• El colector puede persistir snapshots controlados en game_sources, servers y server_snapshots.
• La configuracion local expone HLL_BACKEND_STORAGE_PATH para cambiar la ruta del archivo SQLite sin fijar una decision de produccion.
• backend/README.md documenta la inicializacion y uso de la persistencia local.

Validation Result

• Ejecutado: python -m app.collector
• Resultado: lote de 3 snapshots persistido correctamente en SQLite local de desarrollo.

Decision Notes

• Se eligio SQLite porque cubre persistencia local real con dependencias cero y mantiene abierta la migracion futura a otra tecnologia de almacenamiento.