# TASK-050-file-based-historical-snapshots

## Goal
Migrar la capa de snapshots históricos orientados a UI desde almacenamiento SQLite a archivos JSON independientes en disco, manteniendo SQLite para el histórico bruto y dejando los snapshots como artefactos rápidos, inspeccionables y fáciles de servir.

## Context
El proyecto ya usa snapshots precalculados, pero actualmente se almacenan en SQLite. Se quiere cambiar el enfoque para que cada snapshot UI exista como archivo JSON independiente, actualizado periódicamente por backend y consumido a través de la API propia. La razón es reducir complejidad percibida, facilitar inspección/depuración y reforzar una carga rápida y estable del frontend.

El histórico bruto persistido en SQLite debe mantenerse. Lo que cambia en esta task es solo la capa de snapshots precalculados de UI.

## Steps
1. Revisar la capa actual de snapshots precalculados en SQLite.
2. Diseñar una nueva estructura de archivos para snapshots en disco, por ejemplo:
   - `backend/data/snapshots/comunidad-hispana-01/server-summary.json`
   - `backend/data/snapshots/comunidad-hispana-01/weekly-kills.json`
   - `backend/data/snapshots/comunidad-hispana-01/weekly-deaths.json`
   - `backend/data/snapshots/comunidad-hispana-01/weekly-support.json`
   - `backend/data/snapshots/comunidad-hispana-01/weekly-matches-over-100-kills.json`
   - `backend/data/snapshots/comunidad-hispana-01/recent-matches.json`
   - y equivalentes para `comunidad-hispana-02`, `comunidad-hispana-03` y `all-servers`
3. Implementar almacenamiento y lectura de snapshots en JSON.
4. Migrar la generación de snapshots para que escriba estos archivos.
5. Mantener metadatos útiles dentro de cada snapshot, como:
   - generated_at
   - source_range_start
   - source_range_end
   - freshness / is_stale
   - found
   - política semanal usada si aplica
6. Mantener SQLite para histórico bruto y no mezclar ambas capas.
7. Documentar claramente la nueva arquitectura:
   - histórico bruto en SQLite
   - snapshots UI en archivos JSON
8. No romper todavía la UI actual.
9. Al completar la implementación:
   - dejar el repositorio consistente
   - hacer commit
   - hacer push al remoto si el entorno lo permite

## Files to Read First
- AGENTS.md
- backend/README.md
- backend/app/historical_storage.py
- backend/app/historical_snapshot_storage.py
- backend/app/historical_snapshots.py
- backend/app/historical_runner.py
- backend/app/payloads.py
- backend/app/routes.py
- docs/historical-domain-model.md

## Expected Files to Modify
- backend/README.md
- backend/app/historical_snapshot_storage.py
- backend/app/historical_snapshots.py
- backend/app/historical_runner.py
- backend/app/payloads.py
- backend/app/routes.py
- opcionalmente nuevos módulos auxiliares, por ejemplo:
  - backend/app/historical_file_snapshots.py
- opcionalmente documentación técnica adicional

## Constraints
- No eliminar SQLite del histórico bruto.
- No romper la API histórica existente salvo para adaptarla a la nueva fuente de snapshots.
- No hacer cambios destructivos.
- Mantener el trabajo centrado en pasar snapshots UI a JSON en disco.

## Validation
- Los snapshots UI se generan y guardan como archivos JSON independientes en disco.
- El histórico bruto sigue persistiendo en SQLite.
- La API histórica puede servir esos snapshots correctamente.
- La estructura es inspeccionable y mantenible.
- Los cambios quedan committeados y se hace push si el entorno lo permite.

## Change Budget
- Preferir menos de 7 archivos modificados o creados.
- Preferir menos de 260 líneas cambiadas.

## Outcome
- La persistencia de snapshots históricos orientados a UI se migró de SQLite a archivos JSON bajo `backend/data/snapshots/<server_key>/`.
- `historical_snapshot_storage.py` conserva la misma interfaz pública (`persist_*`, `get_*`, `list_*`) pero ahora escribe y lee archivos como `server-summary.json`, `weekly-kills.json` y `recent-matches.json`.
- SQLite se mantiene exclusivamente para el histórico bruto (`historical_*`) y ya no es la fuente de lectura de snapshots UI.
- Validación local:
- `generate_and_persist_historical_snapshots(server_key='comunidad-hispana-03')` y `generate_and_persist_historical_snapshots(server_key='all-servers')` escribieron su lote de `6` archivos JSON cada uno
- verificado el árbol `backend/data/snapshots/` con `24` archivos JSON esperados para `comunidad-hispana-01`, `comunidad-hispana-02`, `comunidad-hispana-03` y `all-servers`
- los payloads `build_historical_server_summary_snapshot_payload(server_slug='comunidad-hispana-02')`, `build_weekly_leaderboard_snapshot_payload(server_id='all-servers', metric='kills')` y `build_recent_historical_matches_snapshot_payload(server_slug='comunidad-hispana-03')` devolvieron `found: true`