comunidadhll/ai/tasks/done/TASK-170-connect-annual-ranking-snapshot-to-stats-frontend.md

id, title, status, type, team, supporting_teams, roadmap_item, priority

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-170	Connect annual ranking snapshot to Stats frontend	done	frontend	Frontend Senior		foundation	medium

TASK-170 - Connect annual ranking snapshot to Stats frontend

Goal

Conectar el bloque anual top 20 del módulo Stats con la API pública ya creada:

• GET /api/stats/rankings/annual?year=<year>&server_id=<server-or-all>&metric=kills&limit=20

Context

Después de implementar el endpoint anual en backend y diseñar la integración frontend de Stats, esta tarea conecta el bloque de placeholder con datos reales de snapshots precomputados y mantiene el comportamiento por estados sin romper la sección actual.

No se implementan cambios de backend ni migraciones en esta tarea.

Steps

1. Revisar los archivos obligatorios antes de iniciar cambios:
   • AGENTS.md
   • ai/repo-context.md
   • ai/architecture-index.md
   • docs/stats-section-functional-plan.md
   • docs/stats-frontend-integration-plan.md
   • docs/annual-ranking-snapshot-schema-plan.md
   • frontend/stats.html
   • frontend/assets/js/stats.js
   • frontend/assets/css/styles.css
   • backend/app/routes.py
   • backend/app/payloads.py
   • backend/app/rcon_annual_rankings.py
2. Mantener el placeholder de ranking anual en el HTML, reemplazándolo por estados y tabla dinámica del endpoint.
3. Implementar consumo del endpoint anual con estado por:
   • ready
   • missing
   • error/backend no disponible
4. Mantener metric=kills y limit=20 fijos en V1.
5. Validar carga/estado con node --check y pruebas de endpoint si hay backend.

Files to Read First

• AGENTS.md
• ai/repo-context.md
• ai/architecture-index.md
• docs/stats-section-functional-plan.md
• docs/stats-frontend-integration-plan.md
• docs/annual-ranking-snapshot-schema-plan.md
• frontend/stats.html
• frontend/assets/js/stats.js
• frontend/assets/css/styles.css
• backend/app/routes.py
• backend/app/payloads.py
• backend/app/rcon_annual_rankings.py

Expected Files to Modify

• frontend/stats.html
• frontend/assets/js/stats.js
• frontend/assets/css/styles.css (solo si se requiere ajuste visual para el bloque anual)
• ai/tasks/pending/TASK-170-connect-annual-ranking-snapshot-to-stats-frontend.md (estado + outcome)

Constraints

• Mantener frontend vanilla sin frameworks ni cambios de backend.
• No crear migraciones.
• No modificar frontend/assets/js/partida-actual.js.
• No modificar frontend/assets/img/clans/bxb.png.
• No reintroducir Comunidad Hispana #03.
• Mantener el bloque anual como consumo de snapshot (ready, missing o backend no disponible).
• No implementar generador anual desde frontend.

Validation

Antes de cerrar:

• node --check frontend/assets/js/stats.js
• (si aplica) python -m http.server y comprobar HTTP 200 para frontend/stats.html y frontend/assets/js/stats.js.
• Consumir GET /api/stats/rankings/annual desde la UI cuando backend local esté disponible.
• Verificar caso con snapshot existente y caso sin snapshot (snapshot_status="missing").
• scripts/run-integration-tests.ps1 si aplica.
• git diff --name-only y validar que el alcance no excede la task.
• git status --short --untracked-files=all y confirmar que no se tocó partida-actual.js ni img/clans/bxb.png.

Outcome

• Archivos modificados:
  • frontend/stats.html
  • frontend/assets/js/stats.js
  • frontend/assets/css/styles.css (ajustes del bloque anual)
  • ai/tasks/done/TASK-170-connect-annual-ranking-snapshot-to-stats-frontend.md
• Endpoint consumido:
  • GET /api/stats/rankings/annual?year=<year>&server_id=<server-or-all>&metric=kills&limit=20
• Comportamiento snapshot_status=ready:
  • Muestra el bloque de ranking anual con filas del top (ranking_position, player_name, metric_value, matches_considered, kills, deaths, teamkills, kd_ratio), metadatos de servidor, fuente y fecha.
• Comportamiento snapshot_status=missing:
  • Muestra estado informativo de no disponibilidad de ranking para el año seleccionado.
  • No lanza error ni bloquea el resto del flujo.
• Comportamiento con backend no disponible:
  • El estado general y anual muestran error (Backend no disponible...) y no se hacen cambios de UI inconsistentes.
• Validaciones ejecutadas:
  • node --check frontend/assets/js/stats.js
  • powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1
  • Servido local con python -m http.server y comprobación HTTP 200 de frontend/stats.html y frontend/assets/js/stats.js
  • git status --short --untracked-files=all
  • git diff --name-only
• Limitaciones conocidas:
  • No se pudo validar integración real contra backend porque http://127.0.0.1:8000 no estaba disponible en este entorno.
  • Los textos en este bloque se mantienen en ASCII para evitar cambios de encoding.
• Siguiente tarea recomendada:
  • Conectar la vista de Stats con frontend/index.html/frontend/historico.html si aplica y/o añadir mejoras visuales en el bloque anual.

Change Budget

• Preferir cambios < 5 archivos y < 200 líneas.
• Mantener cambio pequeño y verificable.