snapshots

ai/tasks/in-progress/TASK-044-historical-snapshots-api.md

@@ -0,0 +1,57 @@
+# TASK-044-historical-snapshots-api
+
+## Goal
+Exponer una API de snapshots históricos precalculados para que el frontend pueda consumir resumen, tops y partidas recientes sin disparar agregaciones costosas en tiempo real.
+
+## Context
+Con snapshots ya persistidos y generados periódicamente, el siguiente paso es exponer endpoints ligeros para que la UI histórica lea directamente datos preparados.
+
+## Steps
+1. Revisar la capa de snapshots ya creada y el runner de generación.
+2. Diseñar endpoints claros para leer snapshots por servidor, tipo y métrica.
+3. Cubrir como mínimo:
+   - resumen de servidor
+   - tops semanales por métrica
+   - partidas recientes
+4. Asegurar que los endpoints devuelven también información útil de actualización:
+   - generated_at
+   - rango fuente
+   - stale/fresh si aplica
+5. Mantener compatibilidad razonable con la UI histórica ya existente o dejar clara la migración.
+6. Documentar los endpoints en backend.
+7. No cambiar todavía toda la UI 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/routes.py
+- backend/app/payloads.py
+- backend/app/historical_snapshot_storage.py
+- backend/app/historical_snapshots.py
+
+## Expected Files to Modify
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/README.md
+- opcionalmente nuevos módulos de payload/query de snapshots
+
+## Constraints
+- No usar A2S para esta capa.
+- No hacer cálculos pesados on-demand si ya existe snapshot válido.
+- No crear UI nueva en esta task.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en una API ligera de snapshots.
+
+## Validation
+- Existen endpoints de snapshots para resumen, tops y partidas recientes.
+- Los payloads incluyen metadatos de actualización útiles.
+- La capa está lista para que la UI deje de depender de agregados pesados en tiempo real.
+- Los cambios quedan committeados y se hace push al remoto si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 220 líneas cambiadas.

frontend/assets/js/main.js

@@ -7,9 +7,9 @@ const SERVER_HISTORY_URLS = Object.freeze({
 const COMMUNITY_CLANS = Object.freeze([
   {
     name: "LCM",
-    badge: "Comunidad aliada",
+    badge: "Clan CH",
     description:
-      "Clan visible dentro de la red comunitaria hispana con acceso confirmado a Discord.",
+      "Clan activo de la comunidad, con acceso directo a su discord.",
     logoSrc: "./assets/img/clans/lcm.png",
     logoAlt: "Logo de LCM",
     logoClassName: "",
@@ -18,9 +18,9 @@ const COMMUNITY_CLANS = Object.freeze([
   },
   {
     name: "La 129",
-    badge: "Discord pendiente",
+    badge: "Clan CH",
     description:
-      "Presencia confirmada para la seccion comunitaria mientras se publica su acceso definitivo.",
+      "Clan activo de la comunidad, con acceso directo a su discord.",
     logoSrc: "./assets/img/clans/la129.png",
     logoAlt: "Logo de La 129",
     logoClassName: "clan-card__logo--wide",
@@ -29,9 +29,9 @@ const COMMUNITY_CLANS = Object.freeze([
   },
   {
     name: "250 Hispania",
-    badge: "Comunidad aliada",
+    badge: "Clan CH",
     description:
-      "Entrada mostrada con su emblema principal y acceso confirmado al Discord compartido.",
+      "Clan activo de la comunidad, con acceso directo a su discord.",
     logoSrc: "./assets/img/clans/250hispania-shield.png",
     logoAlt: "Escudo de 250 Hispania",
     logoClassName: "clan-card__logo--shield",
@@ -40,9 +40,9 @@ const COMMUNITY_CLANS = Object.freeze([
   },
   {
     name: "H9H",
-    badge: "Logo pendiente",
+    badge: "Clan CH",
     description:
-      "Comunidad incluida en la rotacion mientras se incorpora su identidad visual final.",
+      "Clan activo de la comunidad, con acceso directo a su discord.",
     logoSrc: "",
     logoAlt: "",
     logoClassName: "",
@@ -52,9 +52,9 @@ const COMMUNITY_CLANS = Object.freeze([
   },
   {
     name: "BxB",
-    badge: "Discord pendiente",
+    badge: "Clan CH",
     description:
-      "Clan incorporado a la red visible con su emblema actual y enlace aun por confirmar.",
+      "Clan activo de la comunidad, son raretes.",
     logoSrc: "./assets/img/clans/bxb.png",
     logoAlt: "Logo de BxB",
     logoClassName: "",
@@ -63,9 +63,9 @@ const COMMUNITY_CLANS = Object.freeze([
   },
   {
     name: "7dv",
-    badge: "Comunidad aliada",
+    badge: "Clan CH",
     description:
-      "Entrada activa dentro de la seccion con acceso disponible a su Discord comunitario.",
+      "Clan activo de la comunidad, con acceso directo a su discord.",
     logoSrc: "./assets/img/clans/7dv.png",
     logoAlt: "Logo de 7dv",
     logoClassName: "",

frontend/index.html

@@ -168,12 +168,11 @@
         <section class="panel panel--clans" aria-labelledby="clans-title">
           <div class="panel__shell">
             <div class="panel__header">
-              <p class="eyebrow eyebrow--section">Clanes y comunidades</p>
-              <h2 id="clans-title">Red de comunidad</h2>
+              <p class="eyebrow eyebrow--section">Clanes de la comunidad</p>
+              <h2 id="clans-title">Grupo de la comunidad</h2>
             </div>
             <p class="panel__intro">
-              Clanes y comunidades activas de la escena hispana con presencia
-              confirmada o en preparacion para esta red compartida.
+              Clanes activos de la escena hispana con presencia confirmada.
             </p>
             <div class="clans-grid" id="community-clans-list"></div>
           </div>