comunidadhll/ai/tasks/done/TASK-163-add-player-personal-stats-endpoint.md

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

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-163	Add player personal stats endpoint	done	backend	Backend Senior	Arquitecto de Base de Datos Arquitecto Python	foundation	medium

TASK-163 - Add player personal stats endpoint

Goal

Implementar únicamente el endpoint backend de estadísticas personales: GET /api/stats/players/{player_id}.

Use existing RCON materialized data for weekly/monthly context.

Files modified

• backend/app/rcon_historical_player_stats.py (nuevo)
• backend/app/payloads.py
• backend/app/routes.py

Endpoint created

• GET /api/stats/players/{player_id}
  • Parámetros:
    • server_id (opcional, alias server)
    • timeframe (weekly | monthly, validación en ruta)
  • Respuesta:
    • status
    • data.player_id
    • data.player_name
    • data.matches_considered
    • data.kills
    • data.deaths
    • data.teamkills
    • data.kd_ratio
    • data.kills_per_match
    • data.deaths_per_match
    • data.window_start
    • data.window_end
    • data.window_kind
    • data.weekly_ranking
    • data.monthly_ranking
    • data.source

Validaciones realizadas

• python -m compileall backend/app
• scripts/run-integration-tests.ps1
• Endpoint manual con backend levantado y Invoke-WebRequest:
  • Query corta: /api/stats/players/a?timeframe=weekly => 200 OK
  • Query normal: /api/stats/players/valid-player-uuid?timeframe=monthly => 200 OK
  • Sin resultados: /api/stats/players/nonexistent-9999?timeframe=weekly => 200 OK con métricas en cero
  • Rechazo de timeframe inválido: /api/stats/players/a?timeframe=yearly => 400 Bad Request

Limitaciones conocidas

• El ranking semanal/mensual incluye solo jugadores con kills > 0.
• source_range puede ir en null cuando no hay datos materializados.
• player_name se resuelve al player_id si no hay nombre persistido en el rango solicitado.

Siguiente task recomendada

• Endpoint de vista inicial de estadísticas personales del jugador en frontend (consumo del contrato GET /api/stats/players/{player_id}).