Review Stats implementation after hardening

ai/tasks/done/TASK-178-review-stats-implementation-after-hardening.md

@@ -0,0 +1,143 @@
+---
+id: TASK-178
+title: Review Stats Implementation After Hardening
+status: done
+type: documentation
+team: Analista
+supporting_teams:
+  - Frontend Senior
+  - Backend Senior
+  - PM
+roadmap_item: foundation
+priority: medium
+---
+
+# TASK-178 - Review Stats Implementation After Hardening
+
+## Goal
+
+Realizar una revisión técnica del bloque Stats tras TASK-175, TASK-176 y TASK-177, sin implementar nuevas funcionalidades, para verificar coherencia funcional, robustez y consistencia entre documentación, contratos y comportamiento real.
+
+## Context
+
+La revisión debe cubrir el estado actual de Stats en frontend y backend con enfoque en comportamiento funcional estable, confiabilidad operativa y ausencia de regresiones en restricciones previas (sin Elo/MMR, sin reintroducir Comunidad Hispana #03).  
+Se debe preservar la identidad del repositorio y no ampliar alcance fuera del bloque Stats.
+
+## Steps
+
+1. Leer los archivos listados en “Files to Read First” para ubicar el estado base de la revisión.
+2. Auditar los archivos objetivo y verificar los 9 puntos solicitados por el alcance de la task.
+3. Ejecutar las validaciones técnicas solicitadas (`node --check`, scripts de stats y de integración).
+4. Documentar hallazgos por severidad y marcar follow-up tasks para gaps no triviales.
+
+## Files to Read First
+
+- `ai/task-template.md`
+- `ai/tasks/done/TASK-175-add-stats-regression-validation-script.md`
+- `ai/tasks/done/TASK-176-add-stats-player-comparison-cards.md`
+- `ai/tasks/done/TASK-177-harden-annual-ranking-snapshot-operations.md`
+- `frontend/stats.html`
+- `frontend/assets/js/stats.js`
+
+## Expected Files to Modify
+
+- `ai/tasks/pending/TASK-178-review-stats-implementation-after-hardening.md`
+
+## Scope
+
+Revisar técnicamente los siguientes archivos:
+
+- `frontend/stats.html`
+- `frontend/assets/js/stats.js`
+- `frontend/assets/css/styles.css`
+- `backend/app/rcon_historical_player_stats.py`
+- `backend/app/rcon_annual_rankings.py`
+- `backend/app/payloads.py`
+- `backend/app/routes.py`
+- `scripts/run-stats-validation.ps1`
+- `scripts/run-integration-tests.ps1`
+- `docs/stats-section-functional-plan.md`
+- `docs/annual-ranking-snapshot-runbook.md`
+
+La revisión debe cubrir explícitamente:
+
+1. Consistencia entre contratos documentados y payloads reales.
+2. Confirmación de que Stats no depende de Elo/MMR.
+3. Confirmación de que no se reintroduce Comunidad Hispana #03.
+4. Validación del manejo frontend para:
+   - backend offline
+   - búsqueda sin resultados
+   - jugador sin stats
+   - ranking anual missing
+   - ranking anual ready vacío
+   - métrica inválida
+5. Revisión de fetch semanal + mensual en paralelo y análisis de fallo parcial.
+6. Revisión de documentación y validación de los nuevos metadatos `requested_limit`, `effective_limit`, `snapshot_limit`, `item_count`.
+7. Revisión de fragilidad de `scripts/run-stats-validation.ps1` por comparaciones de strings exactos.
+8. Ejecutar validaciones técnicas:
+   - `node --check frontend/assets/js/stats.js`
+   - `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
+   - `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
+9. Documentar hallazgos, clasificarlos y, si hay gaps no triviales, crear tareas de seguimiento en vez de ampliar esta task.
+
+## Constraints
+
+- No implementar nuevas funcionalidades.
+- No modificar backend salvo bug menor evidente y estrictamente necesario para permitir una revisión correcta.
+- No modificar frontend salvo bug menor evidente y estrictamente necesario.
+- No crear migraciones.
+- No cambiar lógica de ranking.
+- No reactivar Elo/MMR.
+- No reintroducir Comunidad Hispana #03.
+
+## Validation
+
+- `node --check frontend/assets/js/stats.js`
+- `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
+- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
+
+Antes de completar, verificar:
+
+- alcance evaluado solo en los archivos de esta task;
+- hallazgos priorizados por severidad;
+- `git diff --name-only` debe incluir únicamente este archivo de task.
+- no se ejecuta ningún cambio de código fuera del objetivo de revisión.
+
+## Outcome
+
+## Outcome
+
+- Hallazgos de calidad funcional y consistencia:
+  1. [SEVERIDAD BAJA] Documentación funcional (`docs/stats-section-functional-plan.md`) incluye `timeframe=weekly|monthly|all` en la sección de perfil jugador, pero el contrato real expuesto en `backend/app/routes.py` acepta solo `weekly|monthly` (`/api/stats/players/{id}?timeframe=`). Esto limita la superficie a lo realmente probado.
+  2. [SEVERIDAD BAJA] El flujo de perfil en `frontend/assets/js/stats.js` consulta semanal y mensual en paralelo con `Promise.all`. Si una de esas dos peticiones falla (timeout o error puntual), se marca el backend offline y se pierde información parcial del otro periodo. Se recomienda separación con `Promise.allSettled` para degradación parcial.
+- Validación de consistencia de contratos vs payloads:
+  - `frontend/assets/js/stats.js` consume exactamente los contratos actuales definidos en `backend/app/payloads.py`: 
+    - búsqueda en `build_stats_player_search_payload` (`/api/stats/players/search`) con `data.query`, `data.server_id`, `data.items`
+    - perfil en `build_stats_player_profile_payload` (`/api/stats/players/{id}`) con `data.matches_considered`, `weekly_ranking`, `monthly_ranking`, metadatos de `source`
+    - ranking anual en `build_annual_ranking_snapshot_payload` (`/api/stats/rankings/annual`) con `snapshot_status`, `requested_limit`, `effective_limit`, `snapshot_limit`, `item_count`
+  - Los nuevos metadatos de snapshot (`requested_limit`, `effective_limit`, `snapshot_limit`, `item_count`) están documentados en `docs/annual-ranking-snapshot-runbook.md` y aparecen en los payloads.
+- Restricciones de producto verificadas:
+  - No hay dependencia de Elo/MMR en el bloque Stats revisado (endpoints de Elo/MMR son rutas separadas en `routes.py`).
+  - No se detectó reintroducción de `Comunidad Hispana #03` en `frontend/stats.html`, `frontend/assets/js/stats.js`, `docs/stats-section-functional-plan.md`, `docs/annual-ranking-snapshot-runbook.md` ni en los endpoints de Stats revisados.
+  - El manejo de estados solicitados en frontend se encuentra cubierto:
+    - backend offline -> mensajes de estado y estado de paneles configurados en `markAsBackendUnavailable`
+    - búsqueda sin resultados -> `search_empty` con "Sin resultados"
+    - jugador sin stats -> aviso `profileNoStats` con bloque de identidad/counters en 0
+    - ranking anual `missing` -> `annualMissing`
+    - ranking anual `ready` pero vacío -> `annualReadyEmpty`
+    - métrica inválida anual -> `annualMetricInvalid`
+- Fragilidad de validación script:
+  - `scripts/run-stats-validation.ps1` usa múltiples `Assert-Contains` con cadenas exactas para comprobar assets/endpoints/mensajes.
+  - Es útil como regresión, pero es sensible a cambios de copy/UI no funcionales; recomendado considerar validación semántica adicional (`toLowerCase`, patrones de forma/falla HTTP) en un follow-up.
+- Evidencia de validaciones ejecutadas:
+  - `node --check frontend/assets/js/stats.js`
+  - `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
+  - `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
+- Riesgos/acciones:
+  - No se observan bloqueos funcionales críticos en el estado actual.
+  - Riesgo residual de degradación parcial del perfil semanal/mensual por fallo parcial en cargas paralelas.
+
+Tareas de seguimiento:
+1. Alinear `docs/stats-section-functional-plan.md` con el contrato real de `timeframe` (o ampliar explícitamente ruta para aceptar `all`) como decisión de producto.
+2. Implementar degradación parcial en carga de perfil (semana/mensual) para no degradar ambas tablas por un fallo aislado.
+3. Endurecer `scripts/run-stats-validation.ps1` para validar semántica de estados además de string-matches exactos.