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

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

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-179	Fix Stats Review Follow-ups	done	documentation	Analista	Frontend Senior Backend Senior PM	foundation	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.