75 lines
3.8 KiB
Markdown
75 lines
3.8 KiB
Markdown
# TASK-026-a2s-backed-snapshot-collection
|
|
|
|
## Goal
|
|
Hacer que el colector de snapshots del backend pueda capturar datos reales desde servidores HLL consultables por A2S y persistir esos snapshots en la base local ya preparada.
|
|
|
|
## Context
|
|
El proyecto ya tiene persistencia local, consultas históricas mínimas y un bootstrap de colector. Tras introducir un cliente A2S y una configuración de targets, el siguiente paso es cerrar el primer flujo real de captura y persistencia sobre servidores actuales de HLL.
|
|
|
|
## Steps
|
|
1. Revisar el colector actual, la persistencia local y el cliente A2S.
|
|
2. Integrar el cliente A2S dentro del flujo de colecta de snapshots.
|
|
3. Hacer que el colector capture datos desde los targets configurados y los normalice al modelo interno.
|
|
4. Persistir los snapshots reales usando la capa de almacenamiento ya existente.
|
|
5. Manejar de forma controlada los casos de timeout, servidor inaccesible o respuesta inválida.
|
|
6. Mantener la posibilidad de usar datos controlados o fallback de desarrollo si la fuente real no responde.
|
|
7. Actualizar la documentación backend para explicar el flujo de captura real en esta fase.
|
|
8. Mantener el alcance centrado en captura y persistencia, no en nuevas visualizaciones.
|
|
|
|
## 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
|
|
- backend/app/storage.py
|
|
- backend/app/a2s_client.py
|
|
- backend/app/server_targets.py si existe
|
|
|
|
## Expected Files to Modify
|
|
- backend/README.md
|
|
- backend/app/collector.py
|
|
- backend/app/normalizers.py
|
|
- backend/app/storage.py
|
|
- opcionalmente archivos auxiliares nuevos si son estrictamente necesarios para mantener claridad
|
|
|
|
## Constraints
|
|
- No tocar frontend en esta task.
|
|
- No introducir todavía estadísticas complejas.
|
|
- No añadir scraping de terceros.
|
|
- No hacer cambios destructivos.
|
|
- Mantener el pipeline claro, comprobable y pequeño.
|
|
|
|
## Validation
|
|
- El colector puede capturar snapshots reales desde al menos un target A2S configurado.
|
|
- Los snapshots se persisten en la base local actual.
|
|
- Los errores de consulta quedan manejados de forma razonable.
|
|
- La documentación backend refleja cómo ejecutar esta captura en local.
|
|
|
|
## Change Budget
|
|
- Preferir menos de 6 archivos modificados o creados.
|
|
- Preferir menos de 240 líneas cambiadas.
|
|
|
|
## Outcome
|
|
- `backend/app/collector.py` ahora puede ejecutar captura en modo `a2s`, `controlled` o `auto`, persistiendo snapshots reales cuando las consultas A2S tienen exito.
|
|
- El colector registra errores por target sin abortar todo el lote y usa fallback controlado cuando no obtiene respuestas reales y el fallback esta habilitado.
|
|
- `backend/app/storage.py` persiste `source_name` por snapshot para conservar la procedencia efectiva de cada captura.
|
|
- `backend/README.md` documenta como ejecutar captura real, captura controlada y captura automatica con fallback en local.
|
|
|
|
## Validation Result
|
|
- Ejecutado: `python -m compileall backend/app`
|
|
- Resultado: compilacion correcta de los modulos del backend.
|
|
- Ejecutado: validacion con `collect_server_snapshots(source_mode="a2s", persist=True, probe_target=stub_probe)` sobre SQLite temporal.
|
|
- Resultado: flujo A2S simulado persistio 1 snapshot y `list_snapshot_history()` devolvio 1 registro.
|
|
- Ejecutado: validacion con `collect_server_snapshots(source_mode="auto", timeout=0.1, persist=True)` usando el target local por defecto.
|
|
- Resultado: el colector registro 1 error de consulta, activo fallback controlado y persistio 3 snapshots de desarrollo.
|
|
|
|
## Decision Notes
|
|
- Se mantuvo un fallback explicito de desarrollo para no romper el flujo local mientras los targets A2S reales siguen siendo configurables y potencialmente inestables.
|