Add historical CRCON storage ingestion and weekly rankings

docs/decisions.md

@@ -99,3 +99,30 @@ futura agregacion semanal por servidor.
 A2S se mantiene como fuente de estado actual de servidores. El historico de
 partidas y rankings debe construirse en una linea separada basada en CRCON. La
 discovery detallada queda en `docs/historical-crcon-source-discovery.md`.
+
+## Decision 013: persistencia historica local separada del flujo live
+
+El backend mantiene el estado live de servidores y el historico CRCON en el
+mismo SQLite local de desarrollo para no introducir infraestructura prematura,
+pero ambas lineas quedan separadas por tablas y contratos distintos.
+
+El flujo live sigue usando `server_snapshots` via A2S. El flujo historico usa
+tablas `historical_*` para:
+
+- servidores historicos configurados
+- partidas
+- mapas
+- jugadores
+- estadisticas por jugador y partida
+- ejecuciones de ingesta
+
+Las claves estables son:
+
+- servidor: `historical_servers.slug`
+- partida: `(historical_server_id, external_match_id)`
+- jugador: `stable_player_key`
+- estadistica por partida: `(historical_match_id, historical_player_id)`
+
+Esto permite bootstrap, refresco incremental e idempotencia sin mezclar
+semanticas de estado actual con historico persistido. El modelo detallado queda
+en `docs/historical-domain-model.md`.

docs/historical-domain-model.md

@@ -0,0 +1,149 @@
+# Historical Domain Model
+
+## Objective
+
+Definir la base minima de dominio y persistencia para historico de partidas y
+metricas por jugador obtenidas desde la capa JSON publica de los scoreboards
+CRCON de Comunidad Hispana.
+
+## Scope
+
+Esta capa cubre solo historico persistido en backend:
+
+- identidad estable de los 2 servidores historicos
+- partidas cerradas o actualizadas desde CRCON
+- mapas asociados a esas partidas
+- identidad reutilizable de jugadores
+- estadisticas de jugador por partida
+- trazabilidad de ejecuciones de ingesta
+
+No sustituye ni modifica el flujo actual de snapshots live via A2S.
+
+## Stable Identities
+
+### Server
+
+- tabla: `historical_servers`
+- clave estable: `slug`
+- ejemplos:
+  - `comunidad-hispana-01`
+  - `comunidad-hispana-02`
+- atributos de soporte:
+  - `scoreboard_base_url`
+  - `server_number`
+  - `source_kind`
+
+### Match
+
+- tabla: `historical_matches`
+- clave estable: `(historical_server_id, external_match_id)`
+- `external_match_id` corresponde al `id` devuelto por CRCON para cada partida
+- razon:
+  - el `id` de partida es estable dentro de cada scoreboard
+  - se conserva separado por servidor para evitar asumir unicidad global sin
+    contrato formal
+
+### Player
+
+- tabla: `historical_players`
+- clave estable: `stable_player_key`
+- estrategia de identidad:
+  1. `steam:{steamid}` cuando existe `steaminfo.profile.steamid`
+  2. `steaminfo:{id}` cuando existe `steaminfo.id`
+  3. `crcon-player:{player_id}` cuando existe `player_id`
+  4. `name:{normalized-name}` como ultimo fallback
+
+La prioridad evita perder continuidad cuando CRCON expone SteamID. Los
+fallbacks quedan documentados porque la calidad del origen no es totalmente
+uniforme.
+
+### Player Stats Per Match
+
+- tabla: `historical_player_match_stats`
+- clave estable: `(historical_match_id, historical_player_id)`
+- efecto:
+  - la misma partida puede reingestarse sin duplicar filas
+  - si una partida cambia despues, la fila se actualiza por `UPSERT`
+
+### Ingestion Run
+
+- tabla: `historical_ingestion_runs`
+- registra:
+  - tipo de ejecucion (`bootstrap` o `incremental`)
+  - inicio y fin
+  - estado
+  - paginas procesadas
+  - matches vistos
+  - inserts y updates
+
+## Data Model
+
+### `historical_servers`
+
+Fuente historica por scoreboard CRCON.
+
+### `historical_maps`
+
+Catalogo reutilizable de mapas usando `map.id` cuando existe.
+
+### `historical_matches`
+
+Partida historica persistida con:
+
+- servidor
+- identidad externa
+- tiempos (`creation_time`, `start`, `end`)
+- mapa y metadatos visibles
+- resultado axis/allied
+- referencia de procedencia
+
+### `historical_players`
+
+Identidad reutilizable del jugador entre partidas y servidores.
+
+### `historical_player_match_stats`
+
+Metricas por jugador y partida con al menos:
+
+- kills
+- deaths
+- teamkills
+- time_seconds
+- kills_per_minute
+- deaths_per_minute
+- kill_death_ratio
+- combat
+- offense
+- defense
+- support
+
+### `historical_ingestion_runs`
+
+Trazabilidad operativa para bootstrap y refresh incremental.
+
+## Idempotency Strategy
+
+- servidores sembrados de forma declarativa y actualizables por `slug`
+- partidas persistidas con `UPSERT` por `(historical_server_id, external_match_id)`
+- jugadores persistidos con `UPSERT` por `stable_player_key`
+- estadisticas por jugador actualizadas con `UPSERT` por
+  `(historical_match_id, historical_player_id)`
+- el refresco incremental usa una ventana de solape temporal para volver a leer
+  partidas recientes y absorber cambios tardios sin rehacer todo el historico
+
+## Query Readiness
+
+La estructura soporta ya consultas futuras como:
+
+- top kills de la ultima semana por servidor
+- partidas recientes por servidor
+- mapas jugados y frecuencia
+- agregados por jugador sobre ventanas temporales
+
+## Separation From Live State
+
+- live state actual: `server_snapshots` via A2S
+- historico persistido: `historical_*` via CRCON scoreboard JSON
+
+Ambas lineas comparten el mismo SQLite local de desarrollo para reducir
+complejidad operativa, pero mantienen tablas y contratos separados.