Fix Stats review follow-ups

ai/tasks/done/TASK-179-fix-stats-review-followups.md

@@ -0,0 +1,116 @@
+---
+id: TASK-179
+title: Fix Stats Review Follow-ups
+status: done
+type: documentation
+team: Analista
+supporting_teams:
+  - Frontend Senior
+  - Backend Senior
+  - PM
+roadmap_item: foundation
+priority: medium
+---
+
+# TASK-179 - Fix Stats Review Follow-ups
+
+## Goal
+
+Resolver los hallazgos no bloqueantes detectados en TASK-178 sobre el bloque Stats después del hardening.
+
+## Context
+
+Tras la revisión de TASK-178 quedaron pendientes 3 correcciones de consistencia y resiliencia:  
+- documentación desincronizada en `timeframe`,  
+- fallo total de perfil al fallar en paralelo una ventana semanal/mensual,  
+- validación de regresión demasiado dependiente de texto literal en UI.
+
+El objetivo es cerrar estos puntos sin ampliar el alcance funcional del bloque Stats ni de ranking.
+
+## Files to Read First
+
+- `AGENTS.md`
+- `ai/repo-context.md`
+- `ai/architecture-index.md`
+- `ai/tasks/done/TASK-178-review-stats-implementation-after-hardening.md`
+- `docs/stats-section-functional-plan.md`
+- `frontend/stats.html`
+- `frontend/assets/js/stats.js`
+- `scripts/run-stats-validation.ps1`
+- `scripts/run-integration-tests.ps1`
+- `backend/app/routes.py`
+
+## Steps
+
+1. Leer los archivos listados arriba.
+2. Corregir únicamente los cambios de alcance identificados:
+   - actualizar documentación para reflejar `timeframe=weekly|monthly`,
+   - tolerar fallo parcial entre `weekly` y `monthly` en el frontend,
+   - endurecer el script de validación para no depender de textos literales cuando no sea necesario.
+3. Ejecutar validaciones:
+   - `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`
+   - Servidor HTTP local para validar HTTP 200 de `stats.html` y `assets/js/stats.js`.
+4. Documentar resultado en el apartado Outcome y cerrar la task.
+
+## Expected Files to Modify
+
+- `docs/stats-section-functional-plan.md`
+- `frontend/assets/js/stats.js`
+- `scripts/run-stats-validation.ps1`
+- `ai/tasks/done/TASK-179-fix-stats-review-followups.md`
+
+## Constraints
+
+- Corregir sin agregar nuevas funcionalidades.
+- No cambiar la lógica de ranking.
+- No introducir o reactivar Elo/MMR.
+- No reintroducir `Comunidad Hispana #03`.
+- No crear migraciones.
+- No modificar backend salvo bug menor estrictamente necesario.
+- Mantener estilos y comportamiento existente salvo el mensaje mínimo necesario para fallo parcial.
+- No ampliar la sección Stats con nuevas funcionalidades.
+
+## 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`
+- Servir frontend y confirmar HTTP 200 para `stats.html` y `assets/js/stats.js`.
+- `git diff --name-only` y verificación de scope.
+
+## Outcome
+
+- Cambios aplicados:
+  - `docs/stats-section-functional-plan.md`:
+    - Se actualizó la especificación de `timeframe` en
+      `/api/stats/players/{player_id}` a `weekly|monthly`.
+    - Se explicitó que `timeframe=all` no está soportado en el contrato actual.
+  - `frontend/assets/js/stats.js`:
+    - Se reemplazó `Promise.all` por `Promise.allSettled` para carga semanal/mensual.
+    - Se añadio render parcial para escenarios de éxito parcial por ventana.
+    - Se mantiene fallback de error total si ambas ventanas fallan.
+  - `scripts/run-stats-validation.ps1`:
+    - Se reforzaron validaciones de IDs, endpoints y shape de payload.
+    - Se quitaron chequeos frágiles dependientes de texto visible de UI.
+    - Se añadieron verificaciones para `requested_limit`, `effective_limit`, `snapshot_limit` y `item_count`.
+- Modo de fallo parcial semanal/mensual:
+  - Si una ventana responde y la otra falla:
+    - se muestran sus datos y estado disponible.
+    - la otra muestra aviso de bloque no disponible y se evita degradar todo el panel.
+    - se agrega aviso global de carga parcial.
+  - Si ambas fallan:
+    - se conserva el estado de error completo y backend-inusable para ese perfil.
+- Validaciones endurecidas:
+  - Validación de contrato en JS y HTML basada en funciones/rutas/IDs.
+  - Validación de forma de payload y metadatos de snapshot en bloque anual.
+- 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`
+  - `python -m http.server` (servido desde `frontend/`) con `HTTP 200` para:
+    - `stats.html`
+    - `assets/js/stats.js`
+- Limitaciones o follow-ups:
+  - No se identificaron follow-ups de producto inmediatos dentro del alcance de TASK-179.