Files
comunidadhll/docs/stats-frontend-integration-plan.md
2026-06-08 12:21:43 +02:00

4.3 KiB

Plan de integracion de Stats en frontend

1. Pagina prevista

  • Pantalla objetivo: frontend/stats.html (nueva).
  • Objetivo V1: pagina ligera, statically-safe, con componentes para:
    • buscador
    • resultados
    • panel de stats personales
    • resumen semanal
    • resumen mensual
    • bloque futuro de ranking anual top 20 (placeholder)

2. Navegacion

El cambio no debe romper Inicio, Historico ni Partida actual.

  • Mantener frontend/index.html con su estructura actual.
  • Cambios de navegacion propuestos:
    • Añadir un link Stats en el bloque de acciones del hero:
      • href="./stats.html"
      • texto: Stats
      • estilo reutilizando .secondary-button o variante especifica en CSS si se requiere.
    • En frontend/historico.html:
      • añadir boton de regreso a Inicio si no existe.
      • opcionalmente incluir acceso rapido a stats.html en el header.
    • En partida-actual.html (futuro, si usa una plantilla):
      • no modificar por ahora.
  • Regla de compatibilidad:
    • No alterar rutas de historico.html ni de partida-actual.html.
    • Mantener rutas existentes (./historico.html, ./index.html) intactas.

3. Componentes V1

  • Buscador de jugador
    • Input para texto libre.
    • Boton de ejecucion.
    • Debounce/submit manual para evitar ruido.
    • Query query param q.
  • Lista de resultados
    • Mostrar por fila:
      • player_name
      • player_id (texto de soporte)
      • matches_considered
      • last_seen_at
      • servers_seen (solo si se integra en payload final).
    • Cada fila habilita seleccion de jugador.
  • Panel de estadisticas personales
    • Estado base despues de seleccionar jugador:
      • nombre y player_id
      • server/scope visible.
    • Datos por GET /api/stats/players/{player_id}?timeframe=...&server_id=....
  • Resumen semanal
    • Render a partir de data.weekly_ranking y data para la misma ventana.
  • Resumen mensual
    • Render a partir de data.monthly_ranking y datos de ventana.
  • Bloque anual futuro
    • Reservado en layout con estado:
      • Proximo: ranking anual top 20.
    • Sin llamada ni dependencia now.

4. Endpoints usados

  • GET /api/stats/players/search?q=<query>
    • q obligatorio.
    • parametros recomendados V1:
      • server_id opcional (all-servers como default).
      • limit opcional.
  • GET /api/stats/players/{player_id}
    • para semana: timeframe=weekly.
    • para mes: timeframe=monthly.
    • para cambios de scope: server_id=all-servers|comunidad-hispana-01|comunidad-hispana-02.

5. Estados de UI

  • Loading
    • Skeleton o placeholder en buscador y lista de resultados.
    • Mensaje breve en paneles de resumen con estado neutro.
  • Error
    • Mensaje tactico y silencioso en consola.
    • Mantener contenido previo visible.
  • Sin resultados
    • estado vacio: No se encontraron jugadores para esta busqueda.
  • Jugador sin stats
    • si matches_considered == 0:
      • mostrar Sin actividad registrada en el periodo.
  • Backend no disponible
    • banner no intrusivo de estado.
    • no bloquear el resto de la pagina.

6. Identidad visual

  • Mantener estilo militar / Vietnam / tactico / sobrio:
    • variables CSS existentes en frontend/assets/css/styles.css.
    • paleta actual.
    • tarjetas y borders similares a panel, clan-card, server-card.
  • No introducir frameworks.
  • Preferir reutilizacion:
    • hero, panel, status-chip, secondary-button y utilidades de layout existentes.
  • Agregar estilos nuevos solo en styles.css si la combinacion base no cubre el layout.

7. Archivos esperados para implementacion futura

  • frontend/stats.html
  • frontend/assets/js/stats.js
  • frontend/assets/css/styles.css (solo si necesario para grid, estados, card o tabla simple)
  • frontend/index.html y/o frontend/historico.html para navegacion a Stats, sin tocar la logica de secciones actuales.

Alcance de validacion

Esta task es un plan y no requiere pruebas automaticas.

  • Verificar por dif:
    • solo ai/tasks/pending/TASK-164-design-stats-frontend-integration-plan.md
    • docs/stats-frontend-integration-plan.md
  • Revisar que el plan respete las restricciones:
    • sin cambios backend
    • sin implementacion
    • sin ranking anual
    • sin elo/mmr
    • sin comunidad hispana #03
  • Preparar siguiente task: implementacion de frontend/stats.html y frontend/assets/js/stats.js usando endpoints V1.