comunidadhll/docs/player-event-pipeline-v2-design.md

# Player Event Pipeline V2 Design

## Validation Date

- 2026-03-24

## Scope

Diseno tecnico minimo de una futura canalizacion de eventos de jugador para
alimentar una V2 del ranking MVP mensual con metricas avanzadas.

Fuera de alcance:

- implementacion real del pipeline
- nuevas tablas o migraciones
- nuevos endpoints
- cambios de UI

## Inputs Reviewed

- `docs/rcon-data-capability-audit.md`
- `docs/crcon-advanced-metrics-origin-audit.md`
- `docs/monthly-mvp-ranking-scoring-design.md`
- `backend/README.md`
- `backend/app/historical_models.py`
- `backend/app/historical_storage.py`
- `backend/app/rcon_client.py`

## Problem Statement

La capa historica actual persiste bien metricas agregadas por jugador y partida:

- kills
- deaths
- teamkills
- tiempo
- combat
- offense
- defense
- support

Eso basta para un MVP V1. No basta para una V2 que quiera exponer o puntuar:

- killer -> victim
- `most_killed`
- `death_by`
- kills por arma
- `kills_by_type`
- `death_by_weapons`
- distincion infantry / tank / artillery

La auditoria previa deja claro que esas senales no salen del RCON live minimo
implementado hoy.

## Design Goals

La V2 necesita una capa nueva con estos objetivos:

- capturar eventos finos fuera del request path HTTP
- persistir eventos crudos con identidad suficiente para reprocess y auditoria
- derivar agregados reproducibles por partida, jugador y mes
- convivir con el modelo historico actual sin romper V1

## Minimal Architecture

La arquitectura minima propuesta tiene cuatro capas:

1. Source adapter

- un adaptador futuro conectado a eventos, logs o feed equivalente
- responsable solo de leer senales crudas y normalizarlas

2. Event ingestion worker

- proceso batch o loop dedicado, separado de `app.main`
- valida, deduplica y persiste eventos crudos
- nunca calcula ranking dentro del request HTTP

3. Raw event storage

- ledger append-only por evento
- base de auditoria y reproceso

4. Derived aggregates

- jobs posteriores que resumen por partida, jugador y ventana mensual
- capa consumible por un futuro MVP V2

## Proposed Flow

Flujo minimo:

1. El source adapter recibe un evento crudo del servidor o del origen elegido.
2. El worker normaliza el evento a un contrato comun.
3. El evento se persiste en un ledger crudo con claves de deduplicacion.
4. Un agregador por partida resume los eventos cerrados del match.
5. Un agregador mensual construye metricas V2 por jugador y servidor.
6. El ranking MVP V2 consume solo agregados ya cerrados y auditables.

## Minimum Event Types

El subconjunto minimo recomendado es:

- `player_kill`
- `player_death`
- `player_teamkill`
- `player_weapon_usage`

En la practica, `player_death` y `player_weapon_usage` pueden modelarse como
parte del mismo evento de kill si la fuente trae toda la informacion en un solo
registro. Aun asi, conceptualmente la V2 debe capturar estas piezas:

- match id o match scope
- timestamp del evento
- server slug
- killer player key
- victim player key
- killer team
- victim team
- weapon id o nombre de arma
- kill type o damage type
- contexto opcional de vehiculo, artilleria o explosivo
- indicador de teamkill

## Event Contract Proposal

Contrato minimo recomendado para un evento normalizado:

- `event_id`
- `event_type`
- `occurred_at`
- `server_slug`
- `external_match_id`
- `source_kind`
- `source_ref`
- `killer_player_key`
- `victim_player_key`
- `killer_team_side`
- `victim_team_side`
- `weapon_name`
- `weapon_category`
- `kill_category`
- `is_teamkill`
- `raw_event_ref`

Campos opcionales pero utiles desde el inicio:

- `killer_display_name`
- `victim_display_name`
- `vehicle_name`
- `explosive_name`
- `match_phase`

## High-Level Persistence Model

No se crean tablas en esta task, pero la persistencia minima deberia separar:

### 1. Raw player event ledger

Rol:

- guardar cada evento de forma append-only
- permitir reprocess y auditoria

Campos minimos:

- event key estable
- server
- match
- timestamp
- tipo de evento
- actor y target
- arma o categoria
- flags de clasificacion

### 2. Match event aggregates

Rol:

- resumir por partida ya cerrada
- evitar recalcular toda la historia cada vez

Ejemplos de campos:

- kills por jugador
- deaths por jugador
- teamkills por jugador
- kills por arma
- kills por categoria
- tabla de killer -> victim mas frecuente
- tabla de victim <- killer mas frecuente

### 3. Monthly player advanced aggregates

Rol:

- dejar lista la capa consumible por el ranking V2

Ejemplos de campos:

- total kills por arma
- total kills por categoria
- rival mas matado (`most_killed`)
- rival que mas le mata (`death_by`)
- teamkills mensuales
- pesos o subscores avanzados V2

## Relationship With Current Historical Model

La propuesta no sustituye el modelo existente `historical_player_match_stats`.

Relacion recomendada:

- `historical_*` sigue guardando el resumen estable V1 por partida
- el nuevo ledger de eventos guarda granularidad que hoy no existe
- los agregados V2 se derivan del ledger y se pueden unir despues al dominio
  mensual existente

Esto evita dos errores:

- inflar `historical_player_match_stats` con JSON opaco o columnas prematuras
- mezclar captura cruda y vistas derivadas en la misma tabla

## How Advanced Metrics Would Be Derived

### `most_killed`

Derivacion:

- agrupar eventos de kill por `killer_player_key` y `victim_player_key`
- contar ocurrencias
- elegir el victim con mayor conteo por jugador y ventana

### `death_by`

Derivacion:

- agrupar eventos de kill por `victim_player_key` y `killer_player_key`
- contar ocurrencias
- elegir el killer con mayor conteo recibido por jugador y ventana

### Kills por arma

Derivacion:

- agrupar kills por `killer_player_key` y `weapon_name`

### `kills_by_type`

Derivacion:

- clasificar cada kill en una categoria normalizada
- agrupar por `killer_player_key` y `kill_category`

Categorias minimas sugeridas:

- `infantry`
- `vehicle`
- `artillery`
- `explosive`
- `unknown`

### `death_by_weapons`

Derivacion:

- agrupar eventos por `victim_player_key` y `weapon_name`

### Distincion infantry / tank / artillery

Solo es viable si el origen del evento trae senales suficientes para clasificar:

- arma
- vehiculo
- damage type
- o una taxonomia equivalente ya normalizada

Si la fuente no trae esa precision, la categoria debe quedarse en `unknown` y
la V2 no debe inventar inferencias fragiles.

## Recommended Processing Policy

Politica minima recomendada:

- ingesta continua o semi-continua fuera de HTTP
- deduplicacion por `event_id` o hash determinista
- agregacion solo sobre partidas cerradas
- recomputacion idempotente por partida y por ventana mensual
- capacidad de rehidratar agregados desde el ledger crudo

## Integration Point With Monthly MVP V2

La V2 mensual deberia seguir la misma forma general de la V1:

- elegibilidad explicita
- componentes normalizados
- pesos auditables
- tie-breaks deterministas

La diferencia es la entrada:

- V1 consume agregados simples ya persistidos por partida
- V2 consumiria un agregado mensual enriquecido derivado del ledger de eventos

Componentes plausibles para una futura V2:

- kills totales
- support total
- eficiencia base
- variedad o efectividad por arma
- penalizacion por teamkills
- subscore de encounters a partir de killer/victim
- categoria de impacto por tipo de kill si la fuente lo soporta

## Minimal Rollout Path

Secuencia minima recomendada para futuras tasks:

1. Validar la fuente real de eventos/logs reutilizable.
2. Definir el contrato normalizado del evento.
3. Implementar ledger crudo con deduplicacion.
4. Implementar agregador por partida cerrada.
5. Implementar agregado mensual avanzado por jugador.
6. Disenar formula MVP V2 sobre esos agregados.
7. Exponer lectura API solo cuando los agregados sean estables.

## Main Risks

- la fuente real puede no exponer todas las senales necesarias
- clasificar kills por tipo puede requerir un mapa de armas adicional
- sin deduplicacion robusta, los agregados V2 serian poco fiables
- mezclar eventos abiertos con partidas no cerradas inflaria metricas

## Final Recommendation

La arquitectura minima correcta para una V2 no es ampliar el snapshot live ni
sobrecargar `historical_player_match_stats`. Es anadir una capa separada de
eventos crudos, con agregacion derivada por partida y por mes, para producir de
forma auditable metricas como `most_killed`, `death_by`, kills por arma y
clasificaciones avanzadas.