Connect annual ranking snapshot to Stats frontend

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

@@ -0,0 +1,125 @@
+---
+id: TASK-170
+title: Connect annual ranking snapshot to Stats frontend
+status: done
+type: frontend
+team: Frontend Senior
+supporting_teams: []
+roadmap_item: foundation
+priority: 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.