diff --git a/ai/tasks/done/TASK-075-crcon-advanced-metrics-origin-audit.md b/ai/tasks/done/TASK-075-crcon-advanced-metrics-origin-audit.md new file mode 100644 index 0000000..b8981c1 --- /dev/null +++ b/ai/tasks/done/TASK-075-crcon-advanced-metrics-origin-audit.md @@ -0,0 +1,76 @@ +# TASK-075-crcon-advanced-metrics-origin-audit + +## Goal +Auditar el origen técnico real de métricas avanzadas visibles en ecosistemas tipo CRCON / HLL Records, como `most_killed`, `death_by`, killer-victim, kills por arma y otras señales avanzadas, para determinar si provienen de RCON directo, de eventos/logs, o de una persistencia/agregación propia. + +## Context +El proyecto ya integra RCON para live state y la auditoría previa concluyó que el RCON actual del proyecto solo cubre estado live directo. Sin embargo, CRCON / HLL Records muestran métricas avanzadas como: +- `most_killed` +- `death_by` +- duelos entre jugadores +- kills por arma +- otros agregados históricos avanzados + +Antes de diseñar una V2 del MVP, hace falta entender exactamente de dónde salen esos datos en términos técnicos. + +## Steps +1. Revisar la auditoría existente sobre capacidades RCON. +2. Analizar la implementación actual del proyecto y documentar claramente qué NO está saliendo del cliente RCON actual. +3. Investigar conceptualmente qué caminos posibles explican la existencia de métricas avanzadas en CRCON / HLL Records: + - comandos RCON directos + - flujo de eventos + - logs del servidor + - almacenamiento propio de CRCON + - API interna o snapshots enriquecidos +4. Revisar si en la repo ya hay pistas, docs o referencias sobre: + - `most_killed` + - `death_by` + - `kills_by_type` + - `death_by_weapons` + - killer/victim +5. Documentar una conclusión clara: + - qué es plausible obtener por RCON puro + - qué parece requerir captura de eventos o logs + - qué parece requerir agregación histórica propia +6. Dejar una matriz clara de origen probable por métrica. +7. No implementar todavía la captura ni nuevas tablas. +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/monthly-player-ranking-data-audit.md +- backend/README.md +- backend/app/rcon_client.py +- backend/app/providers/rcon_provider.py +- backend/app/data_sources.py +- cualquier doc local relacionada con CRCON, HLL Records o métricas avanzadas si existiera + +## Expected Files to Modify +- docs/crcon-advanced-metrics-origin-audit.md +- opcionalmente ai/architecture-index.md +- opcionalmente docs/decisions.md si surge una conclusión técnica clara + +## Constraints +- No implementar todavía captura avanzada. +- No tocar producto visible. +- No asumir sin evidencia que una métrica sale de RCON directo. +- No hacer cambios destructivos. +- Mantener el trabajo centrado en discovery técnico. + +## Validation +- Existe un documento que separa claramente: + - RCON directo + - eventos/logs + - agregación/persistencia propia +- Queda claro el origen probable de métricas como `most_killed` y `death_by` +- 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/crcon-advanced-metrics-origin-audit.md b/docs/crcon-advanced-metrics-origin-audit.md new file mode 100644 index 0000000..9709f30 --- /dev/null +++ b/docs/crcon-advanced-metrics-origin-audit.md @@ -0,0 +1,223 @@ +# CRCON Advanced Metrics Origin Audit + +## Validation Date + +- 2026-03-24 + +## Scope + +Auditoria tecnica del origen probable de metricas avanzadas visibles en +ecosistemas tipo CRCON / HLL Records, separando: + +- RCON directo implementado hoy en esta repo +- campos historicos ya visibles en la capa publica tipo scoreboard +- metricas que solo resultan plausibles con eventos/logs y agregacion propia + +No se implementa captura nueva, tablas nuevas ni cambios de producto. + +## Evidence Reviewed + +- `docs/rcon-data-capability-audit.md` +- `docs/monthly-player-ranking-data-audit.md` +- `docs/historical-crcon-source-discovery.md` +- `backend/README.md` +- `backend/app/rcon_client.py` +- `backend/app/providers/rcon_provider.py` +- `backend/app/data_sources.py` + +## Confirmed Boundary In This Repository + +La evidencia local confirma dos superficies distintas: + +- RCON live directo para estado actual del servidor +- historico CRCON / scoreboard publico para partidas cerradas y metricas ricas + +El cliente RCON implementado en `backend/app/rcon_client.py` solo usa: + +- `ServerConnect` +- `Login` +- `GetServerInformation` + +El proveedor `RconLiveDataSource` solo convierte eso en: + +- nombre del servidor +- estado online +- jugadores actuales +- capacidad maxima +- mapa actual +- metadata de procedencia del snapshot + +La repo no contiene hoy evidencia de comandos RCON integrados para: + +- killer -> victim +- kills por arma +- teamkills por evento +- duelos jugador contra jugador +- ledger tactico de acciones +- reconstruccion historica de partidas cerradas + +## What The Historical Source Already Exposes + +La discovery historica local ya documenta que el detalle CRCON / scoreboard +publico expone campos avanzados como: + +- `kills_by_type` +- `most_killed` +- `death_by` +- `weapons` +- `death_by_weapons` + +Ademas, `docs/monthly-player-ranking-data-audit.md` confirma que esos campos +existen en el origen, aunque la persistencia actual del proyecto todavia no los +guarda. + +## Technical Interpretation + +La mejor lectura tecnica basada en la repo es esta: + +- RCON puro hoy solo cubre estado live operativo +- metricas como `most_killed` y `death_by` no salen del cliente RCON actual +- esas metricas ya existen en una capa historica enriquecida externa al cliente + RCON local +- para reproducirlas dentro del proyecto haria falta una persistencia propia o + una fuente historica equivalente que conserve eventos o agregados avanzados + +Esto no demuestra por si solo el mecanismo interno exacto de CRCON o HLL +Records, pero si permite descartar algo importante: en esta repo no hay base +para afirmar que esas metricas provengan de RCON directo ya listo para usar. + +## Plausible Origin Paths + +### 1. Direct RCON Commands + +Plausibilidad en esta repo: baja para metricas avanzadas. + +Motivo: + +- no hay comandos RCON avanzados integrados en codigo +- no hay provider historico RCON operativo +- `RconHistoricalDataSource` es solo un placeholder que falla con + `Historical RCON provider is not implemented yet.` + +Conclusion: + +- RCON directo es plausible para live state +- no hay evidencia local suficiente para atribuirle `most_killed`, + `death_by`, killer/victim o kills por arma + +### 2. Event Stream Or Server Logs + +Plausibilidad en esta repo: alta como origen tecnico necesario si el proyecto +quisiera reconstruir esas metricas por cuenta propia. + +Motivo: + +- killer/victim requiere granularidad por evento o al menos por encounter +- kills por arma requieren capturar el arma asociada al kill +- teamkills por evento requieren distinguir el evento individual +- clasificaciones como infantry / tank / artillery requieren una senal por tipo + de kill o contexto del evento + +Conclusion: + +- para producir estas metricas dentro de HLL Vietnam, un pipeline de eventos o + logs es la hipotesis tecnica mas consistente + +### 3. CRCON Internal Storage / Enriched Aggregation + +Plausibilidad en esta repo: alta para explicar lo que ya se observa en el +scoreboard publico. + +Motivo: + +- la fuente publica ya devuelve campos agregados que el proyecto no calcula +- esos campos no se derivan del snapshot live RCON implementado hoy +- `most_killed` y `death_by` parecen vistas agregadas de encounters, no simples + contadores live del servidor + +Conclusion: + +- CRCON / HLL Records probablemente sirve esos campos desde una capa historica + propia ya enriquecida y persistida, no desde la llamada live minima que esta + repo usa por RCON + +## Origin Matrix By Metric + +| Metrica | RCON directo hoy en esta repo | Requiere eventos/logs para reproducirla | Requiere agregacion/persistencia propia | Origen probable segun evidencia local | +| --- | --- | --- | --- | --- | +| Estado live del servidor | Si | No | No | RCON directo | +| Jugadores actuales | Si | No | No | RCON directo | +| Mapa actual | Si | No | No | RCON directo | +| Scoreboard live basico por jugador | No confirmado | Posiblemente no siempre | Posiblemente no | No confirmado en la repo | +| `most_killed` | No | Si o fuente historica equivalente | Si | Capa historica enriquecida | +| `death_by` | No | Si o fuente historica equivalente | Si | Capa historica enriquecida | +| killer -> victim | No | Si | Si | Eventos/logs + persistencia | +| kills por arma | No | Si | Si | Eventos/logs + persistencia | +| `kills_by_type` | No | Si | Si | Eventos/logs + persistencia | +| `death_by_weapons` | No | Si | Si | Eventos/logs + persistencia | +| teamkills por evento | No | Si | Si | Eventos/logs + persistencia | +| teamkills agregados historicos | No desde RCON actual | Si | Si | Agregacion historica | +| duelos reutilizables | No | Si | Si | Eventos/logs + persistencia | +| distincion infantry / tank / artillery | No | Si | Si | Eventos/logs + clasificacion propia | +| acciones tacticas finas | No confirmadas | Si | Si | No confirmadas, pero no salen del RCON actual | + +## What RCON Purely Can Plausibly Provide + +Con evidencia local, RCON puro queda limitado a: + +- estado actual del servidor +- jugadores presentes +- capacidad maxima +- mapa actual +- metadata live util para un panel operativo + +Eso sirve para monitoreo live, no para un MVP mensual V2 con rivalidades, +armas, killers, victims o taxonomias tacticas. + +## What Seems To Require Event Capture Or Logs + +Las metricas siguientes solo son defendibles si el proyecto capta eventos o +logs con granularidad suficiente: + +- killer -> victim +- `most_killed` +- `death_by` +- kills por arma +- `kills_by_type` +- `death_by_weapons` +- teamkills por evento +- segmentacion infantry / tank / artillery + +La razon comun es que todas dependen de relaciones o atributos de eventos +individuales, no solo de un snapshot agregado del servidor. + +## What Seems To Require Historical Aggregation + +Incluso con eventos capturados, haria falta una capa propia de persistencia y +agregacion para exponer de forma estable: + +- rivales mas frecuentes +- resumen `most_killed` +- resumen `death_by` +- perfiles de armas por jugador +- acumulados mensuales auditables por servidor + +Sin esa capa, la señal estaria dispersa en eventos crudos y no seria operativa +para un ranking MVP V2. + +## Final Conclusion + +La conclusion mas solida que soporta esta repo es: + +- `most_killed`, `death_by`, killer/victim y kills por arma no salen del RCON + directo implementado hoy +- esas metricas ya son visibles en una fuente historica enriquecida externa al + cliente RCON local +- para reproducirlas dentro del proyecto haria falta una canalizacion nueva de + eventos/logs y una persistencia historica propia con agregados derivados + +## Recommended Follow-Up + +La siguiente task tecnica correcta es disenar el pipeline minimo de eventos de +jugador necesario para alimentar una V2 del ranking mensual sin asumir que RCON +directo ya entrega esas metricas listas.