diff --git a/ai/tasks/done/TASK-076-player-event-pipeline-v2-design.md b/ai/tasks/done/TASK-076-player-event-pipeline-v2-design.md new file mode 100644 index 0000000..60f60f3 --- /dev/null +++ b/ai/tasks/done/TASK-076-player-event-pipeline-v2-design.md @@ -0,0 +1,63 @@ +# TASK-076-player-event-pipeline-v2-design + +## Goal +Diseñar una arquitectura mínima de pipeline de eventos de jugador que permita, en una futura fase, persistir y agregar datos avanzados necesarios para una V2 del ranking MVP. + +## Context +Si métricas como killer/victim, `most_killed`, `death_by`, kills por arma o acciones tácticas no salen listas de RCON puro, el proyecto necesitará una canalización propia de eventos/logs y una persistencia específica para construir esas vistas. + +## Steps +1. Revisar la auditoría sobre el origen de métricas avanzadas. +2. Diseñar una arquitectura mínima para una futura canalización de eventos. +3. Definir qué tipos de eventos serían necesarios como base, por ejemplo: + - kill + - death + - killer -> victim + - weapon used + - teamkill + - cualquier otro evento imprescindible confirmado +4. Definir qué tabla o modelo de persistencia haría falta a alto nivel. +5. Definir cómo se agregarían después métricas como: + - `most_killed` + - `death_by` + - kills por arma + - distinción infantry/tank/artillery si fuera posible +6. Explicar cómo esa capa podría alimentar una futura V2 del MVP mensual. +7. Mantener fuera de alcance la implementación real. +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/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 + +## Expected Files to Modify +- docs/player-event-pipeline-v2-design.md +- opcionalmente ai/architecture-index.md +- opcionalmente docs/decisions.md + +## Constraints +- No implementar todavía la canalización. +- No crear tablas ni rutas reales. +- No tocar producto visible. +- No hacer cambios destructivos. +- Mantener el trabajo centrado en diseño técnico. + +## Validation +- Existe un documento claro con la arquitectura mínima propuesta para eventos de jugador. +- Queda claro qué eventos serían necesarios y cómo alimentarían una V2 del MVP. +- Los cambios quedan committeados y se hace push si el entorno lo permite. + +## Change Budget +- Preferir menos de 4 archivos modificados o creados. +- Preferir menos de 220 líneas cambiadas. diff --git a/docs/player-event-pipeline-v2-design.md b/docs/player-event-pipeline-v2-design.md new file mode 100644 index 0000000..c5b63d0 --- /dev/null +++ b/docs/player-event-pipeline-v2-design.md @@ -0,0 +1,340 @@ +# 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.