comunidadhll/docs/historical-domain-model.md

# 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 3 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
- snapshots precalculados para lectura rapida

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`
  - `comunidad-hispana-03`
- atributos de soporte:
  - `scoreboard_base_url`
  - `server_number`
  - `source_kind`

La capa de lectura y snapshots admite además una clave lógica adicional:

- `all-servers`

Esta clave no representa una fila física extra en `historical_servers`; es una
vista agregada sobre los tres servidores históricos reales para rankings y
resúmenes globales.

### 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

### Precomputed Snapshot

- directorio: `backend/data/snapshots/<server_key>/`
- identidad estable:
  - `server_key`
  - `snapshot_type`
  - `metric`
  - `window`
- razon:
  - permite exponer resumen, rankings y partidas recientes sin recalcular
    agregados pesados en cada request
  - mantiene metadatos operativos sobre frescura y rango fuente como artefactos
    JSON inspeccionables

## 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.

### `backend/data/snapshots/<server_key>/*.json`

Payloads JSON precalculados listos para lectura rapida desde API/UI con:

- `server_key`
- `snapshot_type`
- `metric`
- `window`
- `payload`
- `generated_at`
- `source_range_start`
- `source_range_end`
- `is_stale`

## 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
- los snapshots precalculados usan reemplazo por identidad logica de archivo
  para refrescar el payload sin crear duplicados

## Query Readiness

La estructura soporta ya consultas futuras como:

- top kills de la ultima semana por servidor
- top muertes, soporte y partidas de 100+ kills desde una capa cacheada
- partidas recientes por servidor
- rankings y resumenes globales con la clave logica `all-servers`
- 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
- snapshots precalculados: archivos JSON bajo `backend/data/snapshots/`
  generados desde el mismo historico persistido

Ambas lineas siguen compartiendo el mismo SQLite local para el estado live y el
historico bruto, pero la capa de snapshots UI queda desacoplada como archivos
en disco para simplificar inspeccion, servicio y depuracion.