comunidadhll/ai/tasks/done/TASK-028-historical-stats-source-and-domain-model.md

TASK-028-historical-stats-source-and-domain-model

Goal

Definir la fuente real, el modelo de dominio y la estrategia técnica base para estadísticas históricas de los 2 servidores reales de la comunidad.

Context

Ya existen páginas de scoreboard/histórico para ambos servidores de la comunidad. El siguiente paso del proyecto es construir una capa histórica propia que permita consultas y rankings agregados, por ejemplo “jugadores con más kills de la última semana” por servidor. Antes de implementar ingesta o endpoints, hay que fijar claramente qué datos se van a extraer, cómo se modelan y cómo se relacionan con cada servidor.

Steps

1. Revisar las dos fuentes reales de histórico ya disponibles para los servidores de la comunidad.
2. Definir qué entidades de dominio hacen falta como base. Incluir al menos:
   • servidor
   • partida
   • mapa
   • modo
   • jugador
   • participación de jugador en partida
   • métricas de partida por jugador
3. Definir qué métricas históricas mínimas interesan en esta primera fase. Incluir al menos:
   • kills
   • muertes si está disponible
   • fecha/hora de partida
   • duración
   • mapa
   • servidor
4. Definir la estrategia de identidad y deduplicación:
   • cómo identificar partidas
   • cómo identificar jugadores si el scoreboard no da un id perfecto
   • cómo evitar duplicados en la ingesta
5. Definir el alcance inicial de analítica histórica. Incluir expresamente:
   • top kills de la última semana por servidor
6. Documentar riesgos y límites:
   • estructura real del scoreboard
   • disponibilidad
   • scraping/control de cambios de HTML si aplica
   • granularidad de datos
7. Actualizar la documentación técnica del repo con este modelo base.
8. Al completar la implementación:
   • dejar el repositorio consistente
   • hacer commit
   • hacer push al remoto si el entorno lo permite

Files to Read First

• AGENTS.md
• ai/repo-context.md
• ai/architecture-index.md
• docs/current-hll-servers-source-plan.md
• docs/frontend-backend-contract.md
• backend/README.md
• cualquier código ya existente sobre histórico o scoreboard
• las URLs reales de scoreboard ya usadas por la comunidad

Expected Files to Modify

• ai/architecture-index.md
• docs/decisions.md
• opcionalmente un nuevo documento técnico, por ejemplo:
  • docs/historical-stats-domain-model.md
• opcionalmente backend/README.md si conviene reflejar el nuevo frente técnico

Constraints

• No implementar todavía scraping/ingesta completa en esta task.
• No introducir UI histórica aún.
• No hacer cambios destructivos.
• Mantener el trabajo centrado en fuente, dominio y estrategia técnica.
• Mantener foco en los 2 servidores reales de la comunidad.

Validation

• Existe un modelo de dominio claro para histórico.
• Queda definida la fuente real de histórico para ambos servidores.
• Queda definida la métrica inicial prioritaria: top kills de la última semana por servidor.
• La documentación queda utilizable como base directa para las siguientes tasks.
• Los cambios quedan committeados y se hace push si el entorno lo permite.

Change Budget

• Preferir menos de 5 archivos modificados o creados.
• Preferir menos de 220 líneas cambiadas.

Outcome

• Se crea docs/historical-stats-domain-model.md como documento base para fuente real, entidades de dominio, identidad y deduplicación del histórico.
• docs/decisions.md fija que el histórico de scoreboards reales queda separado del estado A2S actual.
• ai/architecture-index.md y backend/README.md referencian explícitamente el nuevo frente histórico.

Validation Result

• Verificadas las dos fuentes reales de la comunidad en https://scoreboard.comunidadhll.es/games y https://scoreboard.comunidadhll.es:5443/games.
• Verificado además que ambas cargan la misma SPA pública Hell Let Loose Stats, con referencias visibles a games, players, kills, deaths, matches y server.
• Revisado git diff --name-only.
• Resultado: el alcance documental queda limitado a docs/historical-stats-domain-model.md, docs/decisions.md, ai/architecture-index.md y backend/README.md.

Decision Notes

• Se documenta el scoreboard como fuente real del histórico y A2S como fuente del estado live para no mezclar dominios distintos.
• La primera analítica prioritaria se fija en top kills de la última semana por servidor y no en un dashboard histórico genérico.