Add scoreboard-backed weekly historical stats

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

@@ -0,0 +1,91 @@
+# 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.