Process historical snapshot tasks 047-051

ai/tasks/done/TASK-047-fix-server-02-snapshot-generation.md

@@ -0,0 +1,86 @@
+# TASK-047-fix-server-02-snapshot-generation
+
+## Goal
+Diagnosticar y corregir por qué `comunidad-hispana-02` sigue apareciendo sin snapshots válidos en la UI histórica, asegurando que resumen, tops y partidas recientes se generen y queden disponibles igual que en `comunidad-hispana-01`.
+
+## Context
+La capa histórica ya genera snapshots funcionales para al menos uno de los servidores, pero en la práctica `comunidad-hispana-02` sigue mostrando estados vacíos o “sin snapshot” en la interfaz. El problema no parece ser la ausencia de soporte de servidor en el código, sino un fallo de generación, persistencia, selección o consumo de snapshots. Antes de seguir ampliando la plataforma histórica, hay que dejar corregida la paridad entre ambos servidores actuales.
+
+## Steps
+1. Revisar la configuración histórica actual de `comunidad-hispana-01` y `comunidad-hispana-02`.
+2. Revisar la ruta completa de snapshots para ambos servidores:
+   - histórico bruto
+   - generación de snapshots
+   - persistencia de snapshots
+   - lectura de snapshots
+   - consumo frontend
+3. Identificar por qué `comunidad-hispana-02` no devuelve snapshots válidos aunque exista histórico bruto o soporte parcial.
+4. Corregir la causa raíz, ya sea en:
+   - mapeo de servidor
+   - generación
+   - persistencia
+   - recuperación
+   - cache frontend
+5. Asegurar que para `comunidad-hispana-02` queden disponibles snapshots de:
+   - resumen
+   - leaderboard semanal por métrica
+   - partidas recientes
+6. Verificar que ambos servidores actuales se comportan de forma equivalente.
+7. Documentar brevemente la causa detectada y la corrección.
+8. No añadir todavía el servidor #03 en esta task.
+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/config.py
+- backend/app/historical_ingestion.py
+- backend/app/historical_storage.py
+- backend/app/historical_snapshot_storage.py
+- backend/app/historical_snapshots.py
+- backend/app/payloads.py
+- backend/app/routes.py
+- frontend/historico.html
+- frontend/assets/js/historico.js
+- frontend/assets/css/historico.css
+- docs/historical-coverage-report.md
+- docs/historical-data-quality-notes.md
+
+## Expected Files to Modify
+- backend/app/historical_ingestion.py
+- backend/app/historical_storage.py
+- backend/app/historical_snapshot_storage.py
+- backend/app/historical_snapshots.py
+- backend/app/payloads.py
+- backend/app/routes.py
+- frontend/assets/js/historico.js
+- backend/README.md
+- opcionalmente documentación técnica adicional si ayuda a dejar trazabilidad
+
+## Constraints
+- No usar A2S para esta corrección.
+- No crear páginas nuevas.
+- No romper el flujo actual de `comunidad-hispana-01`.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en que `comunidad-hispana-02` tenga snapshots funcionales.
+
+## Validation
+- `comunidad-hispana-02` deja de mostrar estados vacíos si existe histórico suficiente.
+- Resumen, tops y partidas recientes funcionan también para `comunidad-hispana-02`.
+- No se rompe `comunidad-hispana-01`.
+- 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
+- Causa detectada: `comunidad-hispana-02` ya tenía histórico bruto persistido, pero la API de snapshots devolvía `found: false` cuando faltaba la fila precalculada en `historical_precomputed_snapshots`, sin recomponerla desde `historical_*`.
+- Corrección aplicada: los builders de payload histórico ahora regeneran automáticamente el lote de snapshots del servidor solicitado cuando falta una fila precalculada y luego reintentan la lectura.
+- Validación realizada:
+- simulación sobre una copia del SQLite eliminando las filas de snapshot de `comunidad-hispana-02`
+- la API recompuso `6` snapshots del servidor y devolvió `found: true` para resumen, ranking semanal y partidas recientes
+- verificado también el SQLite real: `comunidad-hispana-02` queda con `6` snapshots persistidos

ai/tasks/done/TASK-048-add-server-03-historical-source-and-ingestion.md

@@ -0,0 +1,79 @@
+# TASK-048-add-server-03-historical-source-and-ingestion
+
+## Goal
+Añadir el tercer servidor histórico de la comunidad (`https://scoreboard.comunidadhll.es:3443/`) a la capa histórica del proyecto, dejándolo preparado para ingesta, snapshots y consumo posterior por la UI propia.
+
+## Context
+Ahora mismo el proyecto trabaja con dos servidores históricos de comunidad, pero existe un tercer servidor real:
+- `https://scoreboard.comunidadhll.es:3443/`
+
+El sistema debe poder tratarlo como una tercera fuente histórica formal, no como un caso manual o externo, manteniendo la misma arquitectura de ingestión, persistencia y snapshots propia del proyecto.
+
+## Steps
+1. Revisar cómo están definidos hoy los servidores históricos actuales.
+2. Añadir la configuración y el mapeo del tercer servidor con una identidad estable, por ejemplo:
+   - `comunidad-hispana-03`
+3. Asegurar que la capa de ingestión histórica puede consultar la fuente CRCON JSON del puerto `3443`.
+4. Preparar la persistencia histórica para ese servidor:
+   - matches
+   - players
+   - stats por match
+   - checkpoints/backfill
+5. Integrar el tercer servidor en la capa de snapshots:
+   - resumen
+   - rankings semanales
+   - partidas recientes
+6. Ajustar documentación y configuración operativa para reflejar que ya existen tres servidores históricos.
+7. No exponer todavía UI nueva si no es imprescindible en esta task.
+8. 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/config.py
+- backend/app/historical_ingestion.py
+- backend/app/historical_storage.py
+- backend/app/historical_snapshot_storage.py
+- backend/app/historical_snapshots.py
+- backend/app/payloads.py
+- backend/app/routes.py
+- docs/historical-crcon-source-discovery.md
+- docs/historical-domain-model.md
+
+## Expected Files to Modify
+- backend/app/config.py
+- backend/app/historical_ingestion.py
+- backend/app/historical_storage.py
+- backend/app/historical_snapshot_storage.py
+- backend/app/historical_snapshots.py
+- backend/app/payloads.py
+- backend/app/routes.py
+- backend/README.md
+- opcionalmente documentación técnica adicional
+
+## Constraints
+- No usar A2S para el histórico del servidor #03.
+- No crear páginas externas o dependientes de la comunidad.
+- No romper los servidores #01 y #02.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en registrar correctamente el servidor #03 en la plataforma histórica.
+
+## Validation
+- El servidor #03 queda definido con identidad estable en backend.
+- La ingesta histórica puede trabajar con su fuente.
+- La capa de snapshots queda preparada para ese servidor.
+- La documentación backend refleja el nuevo servidor.
+- 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
+- Se añadió `comunidad-hispana-03` como tercera fuente histórica estable en el seed declarativo de `historical_servers`, con `scoreboard_base_url` `https://scoreboard.comunidadhll.es:3443` y `server_number` `3`.
+- La validación local de `list_historical_servers()` confirma que el backend ya registra `3` servidores históricos.
+- La validación local de `build_historical_server_snapshots(server_key='comunidad-hispana-03')` devuelve el lote esperado de `6` snapshots, dejando preparada la capa para ingesta, persistencia y consumo posterior aunque la UI aún no se haya ampliado en esta task.
+- Se actualizó la documentación backend y de dominio para reflejar la nueva fuente histórica.

ai/tasks/done/TASK-049-global-all-servers-historical-tops.md

@@ -0,0 +1,81 @@
+# TASK-049-global-all-servers-historical-tops
+
+## Goal
+Añadir soporte para rankings históricos globales agregando los tres servidores de la comunidad, de forma que el proyecto pueda mostrar tops totales además de tops por servidor.
+
+## Context
+Actualmente los rankings históricos están organizados por servidor. El siguiente paso es poder consultar tops globales, por ejemplo:
+- top kills total
+- top muertes total
+- top soporte total
+- top partidas con más de 100 kills total
+
+La forma más limpia es tratar este agregado como una entidad lógica propia, por ejemplo `all-servers`, compatible con la capa de snapshots y con la futura UI.
+
+## Steps
+1. Revisar la estructura actual de rankings históricos por servidor.
+2. Diseñar una estrategia clara para soportar rankings totales agregados, preferiblemente mediante una clave lógica como:
+   - `all-servers`
+3. Implementar el agregado global para:
+   - top kills
+   - top muertes
+   - top soporte
+   - top partidas con más de 100 kills
+4. Asegurar que estos rankings globales:
+   - no mezclan mal identidades de jugador
+   - respetan la ventana semanal o política temporal definida
+   - son compatibles con snapshots
+5. Integrar el agregado global en resumen y metadatos cuando aplique.
+6. Documentar la semántica de `all-servers`.
+7. No crear todavía una UI nueva compleja en esta task si no es estrictamente necesario.
+8. 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/payloads.py
+- backend/app/routes.py
+- docs/historical-domain-model.md
+- docs/historical-data-quality-notes.md
+
+## Expected Files to Modify
+- backend/app/historical_storage.py
+- backend/app/historical_snapshot_storage.py
+- backend/app/historical_snapshots.py
+- backend/app/payloads.py
+- backend/app/routes.py
+- backend/README.md
+- opcionalmente documentación técnica adicional
+
+## Constraints
+- No romper rankings por servidor existentes.
+- No usar A2S para rankings globales históricos.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en el agregado global de tops y snapshots.
+
+## Validation
+- Existe soporte histórico para tops globales `all-servers`.
+- Los rankings globales funcionan para las métricas ya soportadas.
+- Los rankings por servidor siguen funcionando.
+- La documentación backend refleja la nueva capacidad.
+- Los cambios quedan committeados y se hace push si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 6 archivos modificados o creados.
+- Preferir menos de 240 líneas cambiadas.
+
+## Outcome
+- Se añadió la clave lógica `all-servers` para la capa histórica agregada sin crear una fila física adicional en `historical_servers`.
+- `list_weekly_leaderboard()` y los payloads/snapshots asociados ya devuelven rankings globales para `kills`, `deaths`, `support` y `matches_over_100_kills`.
+- `list_historical_server_summaries(server_slug='all-servers')` devuelve un resumen agregado con identidad estable `all-servers`.
+- `list_snapshot_server_keys()` ya incluye `all-servers`, por lo que la capa de snapshots queda compatible con el agregado global.
+- Validación local:
+- `list_weekly_leaderboard(server_id='all-servers', metric='kills', limit=5)` devolvió resultados agregados con servidor lógico `all-servers`
+- `build_historical_server_snapshots(server_key='all-servers')` devolvió `6` snapshots
+- `build_weekly_leaderboard_snapshot_payload(server_id='all-servers', metric='kills')` devolvió `found: true`

ai/tasks/done/TASK-050-file-based-historical-snapshots.md

@@ -0,0 +1,86 @@
+# 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`

ai/tasks/done/TASK-051-historical-ui-fast-snapshot-consumption.md

@@ -0,0 +1,74 @@
+# TASK-051-historical-ui-fast-snapshot-consumption
+
+## Goal
+Ajustar la UI histórica para consumir de forma rápida y estable los snapshots precalculados de resumen, rankings y partidas recientes, incluyendo soporte para el tercer servidor y para tops globales.
+
+## Context
+Una vez exista una capa de snapshots en archivos JSON y estén resueltos los servidores #02 y #03, la UI histórica debe consumir esa capa sin esperas innecesarias, permitiendo cambiar de servidor o pestaña sin sensaciones de bloqueo. Además, debe soportar un selector ampliado con:
+- Comunidad Hispana #01
+- Comunidad Hispana #02
+- Comunidad Hispana #03
+- Totales / Todos
+
+## Steps
+1. Revisar la UI histórica actual y su consumo de snapshots.
+2. Ajustar el selector de servidor para incluir:
+   - `comunidad-hispana-01`
+   - `comunidad-hispana-02`
+   - `comunidad-hispana-03`
+   - `all-servers`
+3. Asegurar que resumen, tops y partidas recientes se cargan desde snapshots rápidos ya preparados.
+4. Evitar caches frontales que congelen indefinidamente respuestas `found: false`.
+5. Mantener estados de loading, empty y error, pero con una experiencia más ágil.
+6. Reflejar correctamente:
+   - servidor seleccionado
+   - rango real usado
+   - fallback semanal si aplica
+7. No depender de URLs externas de la comunidad.
+8. Mantener coherencia visual con la página histórica ya existente.
+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
+- frontend/historico.html
+- frontend/assets/js/historico.js
+- frontend/assets/css/historico.css
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/README.md
+
+## Expected Files to Modify
+- frontend/historico.html
+- frontend/assets/js/historico.js
+- frontend/assets/css/historico.css
+- opcionalmente backend docs mínimas si cambia el contrato visible de consumo
+
+## Constraints
+- No crear páginas nuevas.
+- No romper la UI histórica existente.
+- No introducir frameworks nuevos.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en velocidad percibida, selector ampliado y consumo de snapshots.
+
+## Validation
+- La UI histórica soporta #01, #02, #03 y tops globales.
+- Cambiar de servidor o métrica es rápido.
+- No se quedan cacheadas indefinidamente respuestas vacías antiguas.
+- La página consume snapshots precalculados y no agregados pesados en tiempo real.
+- Los cambios quedan committeados y se hace push si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 220 líneas cambiadas.
+
+## Outcome
+- El selector histórico se amplió a `comunidad-hispana-01`, `comunidad-hispana-02`, `comunidad-hispana-03` y `all-servers`.
+- La UI sigue consumiendo los endpoints propios de snapshots precalculados, pero ahora hace prefetch de resumen, partidas recientes y rankings del alcance activo para acelerar los cambios de selector y pestaña.
+- La caché frontend ya no conserva indefinidamente respuestas con `found: false`; las respuestas negativas vencen rápido y se reintentan automáticamente.
+- La cabecera y las notas de sección reflejan mejor el alcance activo, incluyendo el caso agregado `Totales / Todos`.
+- Validación local:
+- `node --check frontend/assets/js/historico.js`
+- comprobación de strings y selectores en `frontend/historico.html` y `frontend/assets/js/historico.js` para `comunidad-hispana-03`, `all-servers` y `recent-matches-note`