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.